---
title: "Check health and read logs"
description: "Use doctor, status, and logs to see what an install is doing."
---

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

# 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

```sh
npx cf-orbs doctor
```

`doctor` prints one line for each check:

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

```sh
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:

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

```sh
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:

```sh
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:

```text
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](/docs/troubleshooting/)). The self-test is skipped when `prewarm` is 0.

## Machine-readable output

Add `--json` to any command. See [CLI reference](/docs/reference/cli/#global-options).

Source: https://cf-orbs-site.mdick85.workers.dev/docs/guides/check-health/index.mdx