Anvil Cloud / Reference

CLI reference

The normal user-facing command is anvil cloud ... through the umbrella @anvilstack/cli package:

npm install --global @anvilstack/cli
npm install --global @anvilstack/cloud-cli

anvil cloud check --json
anvil cloud dev

The product package is @anvilstack/cloud-cli and the direct binary is anvil-cloud. The wrapper dispatches to that binary, so these are equivalent when both packages are installed:

anvil cloud check --json
anvil-cloud check --json

Use anvil cloud ... in docs, tutorials, and normal shell usage. Use anvil-cloud ... when you are testing the product package directly, debugging wrapper dispatch, or writing a package-specific CI path. From a checkout, run the command contract through pnpm anvil-cloud ... at the workspace root, or through node ../../packages/cli/dist/index.js ... inside checked-in examples. Human output can be friendly, but automation output must be stable.

Commands

Command	Purpose
`anvil cloud new <name>`	Create a new Cell project.
`anvil cloud dev`	Build and start the local runtime and client server.
`anvil cloud doctor`	Check local toolchain, project artifacts, runtime ports, AWS preview env, and auth smoke setup.
`anvil cloud check`	Validate config, import policy, capabilities, and TypeScript without writing build output.
`anvil cloud review`	Aggregate Guard diagnostics and AWS preview approval gates into one trust report.
`anvil cloud build`	Build server and client artifacts, manifest, generated client, generated types, and metadata.
`anvil cloud manifest diff`	Compare manifest baselines against current source or an explicit candidate manifest.
`anvil cloud agents validate`	Validate mounted agents and compile their contracts without calling a model provider.
`anvil cloud agents manifest`	Emit provider-neutral agent manifests from the current Cell build.
`anvil cloud agents discover`	Discover project agent instruction files and mounted Cell agents.
`anvil cloud agents guardian`	Run the deterministic Guardian review over the Cell trust report.
`anvil cloud agents sandboxes`	Report AWS Lambda MicroVM sandbox readiness for sandbox-required agents.
`anvil cloud agents invoke <name>`	Invoke a mounted agent locally through the registered provider (`--input <text>`).
`anvil cloud channels simulate`	Send a simulated channel message to a mounted agent through the local runtime (`--channel`, `--input`).
`anvil cloud inspect --local`	Inspect local manifest, auth, database counts, and recent errors.
`anvil cloud lens`	Verify the local runtime is reachable and print the Anvil Lens URL.
`anvil cloud logs --local`	Read local NDJSON logs.
`anvil cloud usage --local`	Read local usage events: invocations, tokens, estimated cost, budget warnings, and top consumers.
`anvil cloud db list --local`	List local database tables on the active branch, or `--branch <name>`.
`anvil cloud db dump <table> --local`	Dump local table rows on the active branch, or `--branch <name>`.
`anvil cloud db branch <name>`	Snapshot a local database branch (`--from main`, optional `--ttl` and `--use`).
`anvil cloud db branches`	List local database branches; add `--expired` to filter TTL-expired branches.
`anvil cloud db use <name>`	Store the active local database branch for CLI inspection and dev runs.
`anvil cloud db diff <name>`	Compare row counts and schema fields against `main` or `--against <branch>`.
`anvil cloud db promote <name>`	Copy a branch snapshot back to `main`.
`anvil cloud db delete <name> --yes`	Delete a named local database branch.
`anvil cloud db cleanup --expired`	Delete TTL-expired local database branches.
`anvil cloud deploy --preview`	Build and synthesize AWS preview deployment output, with provisioning when configured.
`anvil cloud usage --preview`	Report declared preview resource counts, cost-driver hints, and cleanup commands.
`anvil cloud rollback --preview --dry-run`	Emit rollback intent for a previous preview deployment.
`anvil cloud auth users`	List local identity provider users.
`anvil cloud auth add-user <id>`	Create a local user (`--email`, `--roles a,b`).
`anvil cloud auth remove-user <id>`	Delete a local user.
`anvil cloud auth login <id>`	Set the ambient dev identity and print a JWT.
`anvil cloud auth token <id>`	Mint a JWT for a user (`--ttl` seconds); ideal for agents and curl.
`anvil cloud auth whoami`	Show the ambient dev identity.
`anvil cloud workflows list`	List local workflow runs.
`anvil cloud workflows show <runId>`	Show a local workflow run with per-step state.
`anvil cloud workflows run <name>`	Build the Cell and execute a workflow locally (`--input '<json>'`).
`anvil cloud services list`	Show the last recorded local service states from `.anvil/local/services.json`.

Remote inspection:

anvil cloud inspect --app notes --env preview --json
anvil cloud logs --app notes --env preview --json

Remote AWS readers require ANVIL_AWS_DEPLOYMENT_METADATA_TABLE.

`anvil cloud new <name>`

Creates a starter Cell:

anvil cloud new notes
pnpm dlx @anvilstack/cloud-cli new notes

The package name is @anvilstack/cloud-cli; the binary name is anvil-cloud.

JSON output:

{
  "ok": true,
  "cell": "notes",
  "template": "crud",
  "path": "./notes",
  "lensUrl": "http://localhost:8787/_anvil/lens",
  "next": ["cd notes", "anvil-cloud dev"]
}

Human mode scaffolds, installs dependencies with pnpm install --ignore-scripts, runs git init, prints the Lens URL, and starts the local dev server. Pass --no-install, --no-git, or --no-start to split the flow. --json stays finite by default so coding agents get the project path, Lens URL, bootstrap plan, and next commands without being trapped inside a long-running server.

Useful starter options:

--client vite-react|expo-router|headless
--template crud|auth|workflow|service|agent|sandbox
--package-manager pnpm|npm|bun

`anvil cloud dev`

Starts local runtime and client servers after a successful build.

Options:

--json
--agent
--host <address>
--port <port>
--client-port <port>

The runtime binds to 127.0.0.1 by default. Only use --host on a trusted network; it also exposes local Lens management actions.

Human output:

Anvil Local runtime  http://localhost:8787
Anvil client         http://localhost:5173
Anvil Lens           http://localhost:8787/_anvil/lens

--agent --json emits JSONL events and avoids rich terminal output.

`anvil cloud lens`

Checks that a local runtime is reachable (GET /_anvil/health at --port, default 8787) and prints the Lens URL:

anvil cloud lens
anvil cloud lens --json

Success:

{ "ok": true, "url": "http://localhost:8787/_anvil/lens" }

If nothing is running, the command exits with code 5 and returns LENS_SERVER_NOT_RUNNING telling you to run anvil cloud dev first. See Anvil Lens.

`anvil cloud doctor`

Checks the local toolchain, Cell config, built artifacts, generated client freshness, local runtime state, runtime/client ports, AWS preview environment, and OIDC smoke-test variables:

anvil cloud doctor --json
anvil cloud doctor --port 8787 --client-port 5173 --json

Each check includes a stable id, status, display message, optional remediation hint, optional details, and a docs link. See Doctor diagnostics for the full ID list.

`anvil cloud check`

Runs validation without writing artifacts:

anvil cloud check --json

Failure shape:

{
  "ok": false,
  "phase": "import-policy",
  "diagnostics": [
    {
      "code": "FORBIDDEN_IMPORT",
      "severity": "error",
      "message": "Import '@aws-sdk/client-s3' is not allowed in Cell server code.",
      "hint": "Use declared Anvil capabilities such as ctx.db or ctx.files."
    }
  ],
  "errors": [
    {
      "code": "FORBIDDEN_IMPORT",
      "severity": "error",
      "message": "Import '@aws-sdk/client-s3' is not allowed in Cell server code.",
      "hint": "Use declared Anvil capabilities such as ctx.db or ctx.files."
    }
  ]
}

errors is kept as a compatibility alias for older automation; new agent flows should read diagnostics.

`anvil cloud agents`

Agent commands build the current Cell and use the same manifest extraction path as anvil cloud build.

Contract validation:

anvil cloud agents validate --json

Manifest output:

anvil cloud agents manifest --json

Project discovery:

anvil cloud agents discover --json

Guardian review:

anvil cloud agents guardian --json

Local invocation:

anvil cloud agents invoke support --input "Review this Cell" --json

validate, manifest, discover, and guardian do not call a model provider. discover reports agents/**/instructions.md files plus mounted Cell agents from the manifest. guardian runs the same trust aggregation as anvil-cloud review and emits deterministic findings for Guard errors, approval gates, rollback posture, and cleanup evidence. invoke resolves the agent model provider through the runtime provider registry. The local stub provider is deterministic and does not make external calls. Provider mode can use a registered provider such as aws-bedrock while still enforcing the Anvil agent contract locally.

See Anvil Agents.

`anvil cloud channels`

Simulate provider-neutral channel ingress against a running local runtime:

anvil cloud channels simulate \
  --channel supportSlack \
  --sender U123 \
  --thread T456 \
  --input "Can you review this issue?" \
  --json

The command posts to /_anvil/channels/simulate. The JSON response includes the matched channel, session summary, ordered events, continuation token, and reply chunks. Real Slack, GitHub, and Discord credentials stay platform-side; Cell agent code receives normalized context and remains channel-agnostic.

`anvil cloud build`

Writes .anvil/dist and .anvil/generated:

anvil cloud build --json

Successful output includes build paths, manifest, and diagnostics.

`anvil cloud manifest diff`

Compares Cell manifests without deploying anything:

anvil cloud manifest diff --json
anvil cloud manifest diff --from .anvil/dist/manifest.json --to candidate.json --json

Without --to, the command compares the previous local .anvil/dist/manifest.json with a scratch build of the current Cell source. With --to, it reads both manifest files directly and skips the build.

JSON output includes:

status: "no-baseline" | "unchanged" | "changed" | "block"
summary counts for additions, removals, changes, warnings, and errors
stable changes[].id values
category, action, severity, path, message, optional before, after, and hint for each change

Error-severity changes currently include public file access escalation, schema table removal, schema field removal, and schema field type changes. The command exits with code 5 when any error-severity diff is present.

Local inspection commands

anvil cloud inspect --local --json
anvil cloud logs --local --json
anvil cloud logs --trace run_123 --json
anvil cloud db list --local --json
anvil cloud db dump notes --local --json
anvil cloud services list --json

anvil cloud services list reads the snapshot file written by the dev server, so it shows the last recorded states. For live service state, query GET /_anvil/services on a running dev server. See Services.

Use these before deploying. They are cheap and they catch the kind of "it worked in my imagination" issues that make preview environments do performance art.

logs --trace <traceId> reads local trace records from .anvil/local/traces.json. Workflow traces use the workflow run id; agent invocations return a traceId in local runtime responses.

For remote AWS inspection:

anvil cloud inspect --app notes --env preview --json
anvil cloud logs --app notes --env preview --json

Both commands read the deployment metadata table configured with ANVIL_AWS_DEPLOYMENT_METADATA_TABLE. Missing or malformed records return stable JSON errors: AWS_DEPLOYMENT_METADATA_NOT_FOUND or AWS_DEPLOYMENT_METADATA_INVALID.

Remote inspect includes deploy artifact metadata when present, including the Lambda bundle key and SHA-256 digest from the latest preview deploy. Remote logs accept --since as a millisecond timestamp or a relative duration with ms, s, m, h, or d, such as 30s, 10m, or 1h. They page through CloudWatch events until the requested --limit is reached or CloudWatch has no more pages. --limit must be a positive whole number.

`anvil cloud deploy --preview`

anvil cloud deploy --preview --json
anvil cloud deploy --preview --wait --wait-timeout 60 --json
anvil cloud deploy --preview --name branch --json

The CLI:

builds the Cell with target: "preview"
creates an AWS preview deployment plan
synthesizes a CloudFormation template
packages deploy artifacts when build output is present
provisions AWS resources only when the AWS provisioner is configured

If provisioning is not configured, the adapter returns:

ok: false
code: "AWS_PROVISIONER_NOT_CONFIGURED"
deployment plan
CloudFormation template
artifact summary when available

That is useful. It means deploy planning can be reviewed without mutating an AWS account.

The deployment plan includes an operations block with rollback notes, cleanup commands, and cost drivers for the generated preview resources. Treat these as operator hints, not billing estimates.

Named previews use --name <preview>. The default preview keeps the existing metadata key. Named previews add the normalized name to the adapter-owned stack and deployment metadata key so branch previews do not overwrite each other.

`anvil-cloud usage --preview`

anvil-cloud usage --preview --json

Builds the Cell and reports declared preview resource counts plus AWS preview cost-driver hints and cleanup commands. It does not query AWS and is not a bill.

`anvil-cloud rollback --preview`

anvil-cloud rollback --preview --app notes --to-deployment dep_previous --dry-run --json

Returns stable rollback intent: target deployment id, inspection/log commands, and redeploy guidance. Automated promotion is unsupported because current metadata stores only the active deployment and client assets are not archived as a restorable set.

If CloudFormation reaches a failed terminal state during provisioning, deploy returns ok: false with code: "AWS_STACK_FAILED" and structured stack event details so CI and agents can report the failing resource directly. If the stack remains in progress past the provisioner polling limit, deploy returns ok: false with code: "AWS_STACK_TIMEOUT" and the last observed stack status. If a completed stack omits a required adapter output, deploy returns ok: false with code: "AWS_STACK_OUTPUT_MISSING" and the missing output key. If an AWS SDK operation fails while uploading artifacts, applying the stack, or publishing deployment metadata, deploy returns ok: false with code: "AWS_PROVISIONING_OPERATION_FAILED" and the failed operation plus provider error cause.

With --wait, deploy polls the deployed runtime /_anvil/health endpoint after successful provisioning. If the runtime does not become healthy within the timeout, deploy returns ok: false with code: "AWS_RUNTIME_UNHEALTHY" and keeps the deployment result in the JSON payload for debugging. --wait-timeout must be a positive number of seconds.

The workspace also includes a repeatable AWS preview smoke verifier for the checked-in examples/aws-preview Cell:

ANVIL_AWS_ARTIFACT_BUCKET=<artifact-bucket> \
AWS_REGION=eu-west-2 \
pnpm verify:aws-preview

It deploys with --wait, checks the runtime health and public status query, runs remote inspect and logs, and destroys the preview stack unless ANVIL_AWS_SMOKE_KEEP_STACK=1 is set. Set ANVIL_AWS_SMOKE_TOKEN to include authenticated mutation/query checks.

`anvil cloud destroy --preview`

anvil cloud destroy --preview --app notes --yes --json
anvil cloud destroy --preview --app notes --name branch --yes --json

Deletes the computed AWS preview CloudFormation stack for a Cell. The command requires --app and --yes because accidental cleanup commands are how preview environments become a small billing-themed mystery novel.

Before deleting the stack, destroy empties stack-owned S3 buckets exposed by CloudFormation outputs, including client assets and Cell files when present. If ANVIL_AWS_DEPLOYMENT_METADATA_TABLE is configured, destroy also removes the matching deployment metadata record. The JSON result includes emptiedBuckets and metadataDeleted, so automation can see which cleanup steps actually ran. Pass --name <preview> to clean up a named preview stack and metadata record. If CloudFormation reports a failed delete status, destroy returns AWS_DESTROY_FAILED. If deletion remains in progress past the polling limit, destroy returns AWS_DESTROY_TIMEOUT. If an AWS SDK operation fails while emptying buckets, deleting the stack, or deleting deployment metadata, destroy returns AWS_DESTROY_OPERATION_FAILED.

Exit codes

Code	Meaning
`0`	Success
`1`	General failure
`2`	Invalid CLI usage
`3`	Project validation failed
`4`	Build failed
`5`	Runtime unavailable, remote reader not configured, doctor blocking errors, or manifest diff blocking errors
`6`	Deploy or destroy failed

Automation rule

Every automation-oriented command should support --json. Do not parse human output in CI or agent workflows unless you enjoy finding out that punctuation is an API now.

Generated client Doctor diagnostics