cimplify doctor

Run 14 pre-flight checks across your storefront and the linked project. Each row reports a verdict (`ok` / `warn` / `fail` / `skip`) and a fix hint. Exits `1` on any fail so CI can branch on `$?`.

doctor is the action-oriented counterpart to introspect. Where introspect reports state, doctor issues verdicts: "your next.config.ts has cacheComponents: true; disable it (incompatible with CF Workers)", "your token is rejected; run cimplify login again."

It's the right command to run before a deploy, in CI, or as the first step in an agent prompt that's about to mutate the project.

Usage

cimplify doctor               # full health check (local + 2 remote pings)
cimplify doctor --offline     # skip the remote checks
cimplify doctor --json        # machine-readable envelope

What it checks

Local (always run, ~ms)

Check	Fails when	Warns when
`cli`	(never)	—
`package_json`	no `./package.json`	—
`node_modules`	missing	—
`lockfile`	no `bun.lock(b)` and no other lockfile	a non-bun lockfile (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`) is present
`sdk_pin`	`@cimplify/sdk` not in dependencies	pinned to `*` or `latest`
`brand_file`	—	no `lib/brand.ts` in a project
`next_config`	`cacheComponents` is explicitly `true` (incompatible with CF Workers; Cimplify storefronts use ISR Previous Model)	—
`globals_css`	—	`@theme` block missing
`mock_seed`	—	no `cimplify-mock --seed <industry>` in `scripts.dev`
`git`	—	working tree is dirty (deploy hint)
`auth_present`	no token file at `~/.config/cimplify/auth.json`	—
`project_linked`	no `.cimplify/project.json`	—

Remote (skipped on `--offline`, ~1 s total)

Check	Fails when
`auth_valid`	`GET /v1/auth/me` returns 401 or the host is unreachable
`project_resolves`	`GET /v1/businesses/{bid}/projects/{pid}` returns 404

project_resolves skips automatically when project_linked failed or auth_valid failed; there's nothing useful to ask the server about.

Human output

Cimplify doctor

  ✓ cli               0.2.9
  ✓ package_json      my-store
  ✓ node_modules      installed
  ✓ lockfile          bun.lock
  ✓ sdk_pin           @cimplify/sdk ^0.45.4
  ✓ brand_file        lib/brand.ts · Currents Electronics
  ✓ next_config       ISR Previous Model (cacheComponents off)
  ✓ globals_css       app/globals.css · @theme block present
  ✓ mock_seed         seed: retail
  ! git               working tree dirty on main
                      → commit before `cimplify deploy` (or pass --allow-dirty)
  ✓ auth_present      dev@example.com
  ✓ project_linked    proj_abc
  ✓ auth_valid        live token · business biz_xyz
  ✗ project_resolves  project not found on server
                      → run `cimplify projects ls` to see available projects, then `cimplify link <id>`

14 checks · 12 ok · 1 warn · 1 fail

Verdict glyphs: ✓ = ok, ! = warn, ✗ = fail, - = skip.

JSON envelope

{
  "ok": true,
  "data": {
    "summary": { "total": 14, "ok": 12, "warn": 1, "fail": 1, "skip": 0 },
    "checks": [
      { "name": "cli", "level": "ok", "message": "0.2.9" },
      { "name": "git", "level": "warn", "message": "working tree dirty on main",
        "fix": "commit before `cimplify deploy` (or pass --allow-dirty)" },
      { "name": "project_resolves", "level": "fail", "message": "project not found on server",
        "fix": "run `cimplify projects ls` to see available projects, then `cimplify link <id>`" }
    ]
  }
}

Every check has the same shape: { name, level: "ok" | "warn" | "fail" | "skip", message, fix? }. The fix field is the actionable hint; agents should prefer it over the message when generating next steps.

Exit codes

Condition	Exit
All checks `ok` / `warn` / `skip`	`0`
Any check `fail`	`1`

Warnings never fail the run; they're advisory (e.g., a dirty git tree pre-deploy). Only fail rows block.

For CI: cimplify doctor --json --offline > doctor.json && jq '.data.summary.fail' doctor.json returns the count of failures.

Flags

Flag	Notes
`--offline`	Skip the two remote checks (`auth_valid`, `project_resolves`). Useful in CI sandboxes with no outbound network.
`--json`	Single envelope on stdout; suppresses colorized output.

cimplify doctor

On this page