CLI reference

Run the CLI with npx cf-orbs <command>; the package needs Node 22 or later. Run cf-orbs --help for the command list, and cf-orbs <command> --help for one command.

Global options

These options work with every command:

Flag syntax: --flag value, --flag=value, and --no-flag for a boolean. -- ends the flags.

For init, the first positional argument is the project directory.

Exit codes

Every failure is one line: Failed: <cause> — fix: <action>. With --json, a failure prints {"ok": false, "error": "..."}. To get a stack trace for an unexpected error, set CF_ORBS_DEBUG=1.

init

cf-orbs init [dir]

Sets up a project directory, deploys it, and checks that the provider runs. It’s safe to run again.

Without --vcpu, a rerun keeps the instance in the config.

init stops, with one Failed: line, on any of these:

• Node older than 22.
• Docker not running (not checked with --no-deploy).
• wrangler not logged in, no account, or several accounts and no --account-id.
• No Amp token, an empty token, or a token with spaces. A token without the aop_live_ prefix gives a warning. With --no-deploy, the token is optional.
• An invalid config file.
• An extra image key with no image/<key>.Dockerfile.
• No workers.dev subdomain and no --subdomain (in a terminal, init asks).
• --no-deploy with --provider external.
• A Worker named name already exists in the account and this folder has no saved deployment (no URL in .cf-orbs/state.json). The check runs wrangler deployments list --json --name <name> before init makes a token, sets a secret or deploys. It applies to all modes. Pass --adopt to take the Worker over. If the check cannot run (network, login), it is a warning. A rerun in the folder that made the Worker is not checked.
• wrangler containers list fails with a clear plan or login error. Any other error is a warning.

It writes cf-orbs.config.jsonc and image/Dockerfile only when they don’t exist yet. A rerun with --provider, --name, or --vcpu changes those keys in the existing config.

deploy

cf-orbs deploy

Copies the templates into .cf-orbs/, regenerates .cf-orbs/wrangler.jsonc from the config, and runs wrangler deploy. It sends the control token again each time, which repairs a lost secret. In external mode it also deletes the Worker secret AMP_ORB_PROVIDER_TOKEN.

After the deploy, it asks the Worker to restart the provider if the provider image changed, and to start the prewarm instances. Both are best effort, so a failure there is only a warning.

deploy retries these known registry errors up to 3 times: a push that times out, and an Unauthorized answer after image preparation.

It prints Deployed <name>: <url>.

status

cf-orbs status [orb]

Shows the install status, or the state of one orb. See Check health and read logs.

logs

cf-orbs logs <orb> [--lines N]
cf-orbs logs --provider

Both logs are redacted. With neither an orb id nor --provider, the command fails with no orb id given.

doctor

cf-orbs doctor

Prints PASS, FAIL, WARN, INFO, or SKIP for each check. Exits 1 if any check is FAIL. See Check health and read logs.

snapshots

cf-orbs snapshots list
cf-orbs snapshots forget <ampSnapshotId>
cf-orbs snapshots forget --all-project [--yes]
cf-orbs snapshots prune [--older-than 7d] [--all] [--yes]

See Manage snapshots.

upgrade

cf-orbs upgrade --digest sha256:<hex> [--no-deploy]

Moves the orb image to a new Amp orb image digest and keeps the old image under the key orb-<short>.

See Upgrade.

uninstall

cf-orbs uninstall [--yes]

Lists (dry run) or deletes the Worker, the container apps, and their images. -y is the short form of --yes. See Uninstall.

bench

cf-orbs bench substrate

Prints how to run the substrate benchmark from a clone of the repo: npm run bench:substrate -- --dir <this directory>. That benchmark tests the container platform alone (cold start, restore, pause, and parallel restores, with no Amp thread), and it needs "debugExec": true. The command itself runs no benchmark.

JSON results

With --json, each command prints one document. The main fields are below; before version 1.0, a minor version can change them.