Check health and read logs

Three commands show the state of an install: doctor, status and logs. All three only read, so they never start a provider or an orb.

doctor

npx cf-orbs doctor

doctor prints one line for each check:

PASS  config                 4 vCPU, 12288 MiB, 20000 MB disk; maxRunning 20; providerHost cloudflare
FAIL  provider               Failed: provider is not running — fix: wait for the 5-min cron to restart it, ...

Statuses:

Status	Meaning
`PASS`	The check passed
`FAIL`	The check failed. The line holds a one-line fix, and the exit code is 1
`WARN`	A risk, not a failure
`INFO`	A hint
`SKIP`	The check cannot run now

The last line is All checks passed. or N check(s) failed.

The checks, in order:

Check	What it tests
`config`	The config file is valid
`control token`	`.cf-orbs/control-token` exists with mode 600
`orb image pin`	Each `FROM` in `image/*.Dockerfile` has an `@sha256` digest
`provider image pin`	The provider Dockerfile `FROM` has a digest
`debugExec`	It is `false`. `WARN` when `true`
`secrets in git`	No `aop_live_` token or control token value is in a file that git tracks. `SKIP` outside a git repo
`gitignore`	Workers Builds projects only. Git ignores `.cf-orbs/control-token` and `.cf-orbs/state.json`
`wrangler pin`	Workers Builds projects only. `package.json` pins the wrangler version that cf-orbs uses
`deployment`	The Worker has a deployment
`health`	`/v1/health` answers
`status`	`/v1/status` accepts the control token
`provider`	The provider runs. It also fails when the Worker has no `AMP_ORB_PROVIDER_TOKEN` secret, or when an external-mode install still runs a Cloudflare provider
`image keys`	Every image key that snapshots or orbs use is still in the config
`Amp snapshot cache`	`INFO`. A reminder about Amp’s 72-hour cache

status

npx cf-orbs status

It shows:

provider: running or not, start time, restart count, image.
snapshots: retained count and size, project snapshots, next expiry.
prunable: snapshot data that nothing uses.
prewarm: the last run, for example prewarm: 2 of 2 ready in 41 s and 39 s, 3m ago.
A project snapshot table with age, amp version, image, and a stale flag.
awake orbs: N of <maxRunning> and their ids.

For one orb:

npx cf-orbs status <orb>

Orb ids are amp-<thread id>, where the thread id is the id of the Amp thread (it starts with T-). cf-orbs status lists only awake orbs, so for a paused orb you build the id from the thread id in Amp, for example amp-T-.... cf-orbs status <orb> works for any orb the Worker knows. The output has state (warm (Nm left) for a warm orb), container running, bootstrap, image key, instance, awake since, last wake source, last spawn, recent spawns, snapshot, snapshot expires, last stop, and in-flight op.

logs

npx cf-orbs logs <orb> --lines 200
npx cf-orbs logs --provider

The orb log is the redacted log of amp orb bootstrap, the Amp start-up step inside the orb. --lines takes 1 to 5000 (default 200). The provider log is the last 20 lines that the Worker keeps, also redacted.

For live Worker logs:

npx wrangler tail --config .cf-orbs/wrangler.jsonc

The self-test

After a deploy, init starts the prewarm instances (throwaway orbs that prove the image starts) and waits up to 3 min. If one starts, it prints:

self-test: orb image starts (2 of 2 ready in 41 s and 39 s)

If none starts, init fails with orb self-test failed: no instance started from the new image (see Troubleshooting). The self-test is skipped when prewarm is 0.

Machine-readable output

Add --json to any command. See CLI reference.