vk doctor

Usage

vk doctor [options]

vk doctor runs a fixed list of checks against the current project and machine and prints one line per finding — ✓ ok, ! warning, ✗ problem — with the fix under every line that is not ok. The checks are the misconfigurations that otherwise surface as a puzzling runtime error two steps later: an undeclared stage that silently deploys the dev config, @venturekit/* packages pinned to different versions, a link: specifier that breaks every CI install, VENTURE_LOCAL=true left on while deploying.

The process exits 1 when any check fails; warnings alone exit 0, so the command can gate a CI job without failing it on advice.

Option	Description	Default
`-s, --stage <stage>`	Stage to check against — `dev` checks the local loop (Docker, `.env.local`, cognito-local variables); any other stage checks deploy readiness (stage declared, no local-only markers, AWS credentials)	`dev`
`--json`	Machine-readable output: `{ stage, findings: [{ id, status, summary, fix? }] }`	`false`

Checks

Id	Stage	What it verifies	Not ok when
`node.version`	all	Node.js `>= 20`	fail below 20
`pnpm.present`	all	`pnpm` on `PATH`	warn
`docker.reachable`	`dev`	Docker installed and the daemon answers `docker info` — `vk dev` needs it for Postgres and cognito-local	warn
`config.loads`	all	`vk.config.ts` loads for the stage (`name`, `region` shown)	fail on a load error — `vk check` type-checks the project
`config.stage`	deploy stages	The stage is declared under `envs`	fail — an undeclared stage silently deploys the dev config
`dirs.routes` / `dirs.functions` / `dirs.queues` / `dirs.crons`	all	The handler directories from the config exist	warn when `routes/` is missing (no HTTP routes would deploy); the others are reported only when present
`db.migrations`	all	`db/migrations/` exists when a database is declared	warn
`packages.local-links`	all	No `link:` / `file:` / `workspace:` specifier on a VentureKit dependency	fail — every CI install of the workspace fails on them
`packages.lockstep`	all	Every `@venturekit/` and `@venturekit-pro/` dependency is on the same version (they publish in lockstep)	warn
`env.VENTURE_LOCAL` / `env.DB_SSL_INSECURE`	deploy stages	The local-only markers are not set to `true`	fail
`env.cognito`	`dev`	`COGNITO_USER_POOL_ID` and `COGNITO_APP_CLIENT_ID` are set when an auth intent is declared (`vk dev` writes them)	warn
`env.database`	`dev`	`DATABASE_URL`, or `DB_HOST` + `DB_NAME`, is set when a database is declared	warn
`env.dotenv`	`dev`	`.env.local` exists when `.env.example` does	warn
`aws.region`	deploy stages	A region resolves from `AWS_REGION`, `AWS_DEFAULT_REGION` or `providers.aws.region`	warn
`aws.credentials`	deploy stages	`sts:GetCallerIdentity` succeeds (the account id is shown)	fail

A check that throws is reported as a fail finding (Check crashed: …) rather than aborting the run, so one broken probe never hides the others.

Examples

# Before the first `vk dev` on a new machine
vk doctor

# Before deploying — is the stage declared, are credentials in place?
vk doctor --stage prod

# CI — fail the job on problems, keep the report as an artifact
pnpm exec vk doctor --stage staging --json > doctor.json

vk doctor — stage 'prod'

  ✓ Node v22.12.0
  ✓ pnpm found
  ✓ Docker not needed for a deployed stage
  ✓ vk.config.ts loads (my-app, eu-west-1)
  ✗ Stage 'prod' is not declared in envs (dev, staging)
      → Add envs.prod to vk.config.ts — an undeclared stage silently deploys the dev config.
  ✓ routes/ present
  ✓ db/migrations/ present
  ✓ 6 VentureKit packages @ ^0.1.0
  ✓ No local-only markers set
  ✓ Region eu-west-1
  ✓ AWS credentials resolve (account 123456789012)

1 problem(s)

vk doctor

Usage

Checks

Examples

See also