---
title: "CLI reference"
description: "Every cf-orbs command, flag, output format, and exit code."
---

> Documentation Index
> Fetch the complete documentation index at: https://cf-orbs-site.mdick85.workers.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

| Option | Meaning |
| --- | --- |
| `--dir <path>` | The project directory. Default: the current directory |
| `--url <url>` | The control-plane URL. Default: `CF_ORBS_URL`, then `.cf-orbs/state.json` |
| `--json` | Print one JSON document on stdout. Progress goes to stderr |
| `--non-interactive` | Never prompt. Read `AMP_ORB_PROVIDER_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` from the environment. This is also on when `CI` is set or stdin is not a terminal |
| `-h`, `--help` | Show help |
| `-v`, `--version` | Show the version |

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

| Code | Meaning |
| --- | --- |
| 0 | Success |
| 1 | A command failed, or `doctor` found a failed check |
| 2 | A bad flag, a missing flag value, or an unknown command |

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

```text
cf-orbs init [dir]
```

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

| Flag | Meaning |
| --- | --- |
| `--provider cloudflare\|external` | Where `amp orb provider` runs. Default: `cloudflare`, or the value in the config |
| `--token-file <file>` | File with the Amp provider token. Else `AMP_ORB_PROVIDER_TOKEN`, else a prompt |
| `--account-id <id>` | Cloudflare account. Else `CLOUDFLARE_ACCOUNT_ID`, else it asks |
| `--provider-name <name>` | The Amp provider name, as in Amp → Settings → Orbs. Default `cloudflare`. `AMP_ORB_PROVIDER_NAME` or the saved name wins over the default. Not given explicitly: `init` warns that the name must match the one in Amp |
| `--subdomain <name>` | The workers.dev subdomain to register if the account has none. Else `CF_ORBS_SUBDOMAIN` |
| `--vcpu <1\|2\|3\|4>` | Orb size: N vCPU, N x 3 GiB, 20 GB disk. Writes `instance` |
| `--name <name>` | The Worker name. Lowercase letters, digits, and dashes, up to 63 characters. Default `cf-orbs` |
| `--no-deploy` | Preview. No Docker and no deploy. Prepares a git repo for [Workers Builds](/docs/guides/install-workers-builds/) |
| `--adopt` | Take over a Worker of the same name that this folder did not create. A new control token replaces the old one, so the folder that made the Worker loses CLI access. This folder's config and `image/` are deployed. Without it, `init` stops. See [Back up and restore](/docs/guides/back-up-and-restore/) |

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

```text
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

```text
cf-orbs status [orb]
```

Shows the install status, or the state of one orb. See [Check health and read logs](/docs/guides/check-health/#status).

## logs

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

| Flag | Meaning |
| --- | --- |
| `--lines <N>` | Number of lines, 1 to 5000. Default 200 |
| `--provider` | Show the provider log (last 20 lines) instead of an orb log |

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

## doctor

```text
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](/docs/guides/check-health/#doctor).

## snapshots

```text
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]
```

| Flag | Applies to | Meaning |
| --- | --- | --- |
| `--all-project` | `forget` | Drop every project snapshot mapping. Asks first unless `--yes` |
| `--older-than <age>` | `prune` | Minimum unused age. `7d`, `36h`, or `90m`. Default `7d` |
| `--all` | `prune` | No age limit. Mapped snapshots and orb disks stay |
| `--yes`, `-y` | `forget --all-project`, `prune` | Skip the question, or delete |

See [Manage snapshots](/docs/guides/manage-snapshots/).

## upgrade

```text
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>`.

| Flag | Meaning |
| --- | --- |
| `--digest sha256:<64 hex>` | The new digest. Required |
| `--no-deploy` | Edit the files and do not deploy. In a Workers Builds project, also writes `.cf-orbs/wrangler.jsonc` |

See [Upgrade](/docs/guides/upgrade/).

## uninstall

```text
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](/docs/guides/uninstall/).

## bench

```text
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.

| Command | Fields |
| --- | --- |
| `init` | `ok`, `url`, `mode`, `providerName`, `next`. With `--no-deploy`: `mode: "git"`, `providerHost`, `settings`, `steps` |
| `deploy` | `ok`, `url`, `attempts`, `provider`, `prewarm` |
| `doctor` | `ok`, `checks` (a list of `name`, `status`, `detail`) |
| `logs` | `lines` |
| `snapshots forget` | `ok`, `forgotten` |
| `snapshots prune` | `ok`, `dryRun`, `candidates`, `totalBytes`, `kept`, and with `--yes`: `deleted`, `failed`, `forgotten` |
| `upgrade` | `ok`, `changed`, `deployed`, `oldKey`, `nextSteps` |
| `uninstall` | `ok`, `dryRun`, `worker`, `apps`, `images`, `errors` |
| `status` | The Worker's status document |

Source: https://cf-orbs-site.mdick85.workers.dev/docs/reference/cli/index.mdx