CLI reference. Testkit docs

How to run a command

Run testkit through npx from the repo root, or from a package script.

$npx testkit --version

@gfdelarue/testkit/0.4.1 linux-x64 node-v24.19.0

Shared flags

Flag	Meaning
`--dir <path>`	The product directory. The default is the current directory.
`--service <name>`	Limit the command to one service.
`--json`	Print one JSON document instead of text.
`-h, --help`	Print the command's flags.
`-v, --version`	Print the Testkit version. Root command only.

doctor, lint, typecheck, setup playwright, ci report, bug record, bug file, and the three campaign commands take --dir and --json but not --service. bug guide takes --json only. guard unsafe-entrypoint takes none of the three.

The tables below list only the flags that belong to one command.

Run tests

`testkit run`

Runs test files. With no argument, it runs every file that Testkit discovers.

testkit run [type] [flags]

type is ui, e2e, int, contract, data, dal, load, or all.

Flag	Meaning
`-t, --type <type>`	Run one test type. Repeat the flag to add more.
`-s, --suite <suite>`	Run one suite. `contract:checkout` selects one suite, and `checkout` selects that name in every type. Repeat the flag to add more.
`-f, --file <path>`	Run one file. Repeat the flag to add more.
`--task-concurrency <n>`	The most test tasks that run at once. Overrides `execution.taskConcurrency`.
`--file-timeout-seconds <n>`	The wall-clock limit for each file, in seconds.
`--allow-empty`	Let the run pass when no file runs.
`--ignore-skip-rules`	Run files that a skip rule holds back.
`--skip-schema-source-verify`	Skip the check that the local schema matches the source database schema.
`--output-mode <mode>`	`compact`, `debug`, or `events`. `events` prints one JSON object per line.
`--debug`	The same as `--output-mode debug`.

testkit run exits 0 only when at least one file completed and every required file passed. What fails the gate lists the other cases.

`testkit run status`

Shows the runs that are active.

$npx testkit run status

Testkit Run Status
  product: /repo
  local runs: none

Flag	Meaning
`--run <id>`	Show one run.
`--full`	Include the full live status in the JSON output.

`testkit run stop`

Stops the newest active run.

Flag	Meaning
`--run <id>`	Stop this run.
`--all`	Stop every active run for the product.
`--reason <text>`	A reason, recorded with the cancelled run.

`testkit stop`

Stops every run that Testkit owns in the product.

Flag	Meaning
`--reason <text>`	A reason, recorded with the cancelled runs.

`testkit ci report`

Posts the last run in the checkout as one commit status, the job's step summary, and one pull request comment. Report the run to GitHub or Gitea shows the workflow step and the token it needs.

Flag	Meaning
`--context <name>`	The commit status context. The default is `testkit`.

testkit ci report exits 0 when it posts the report, and that includes the report of a failed run.

Hunt bugs

These commands need no Turnstone account. Run a campaign shows them in order.

`testkit campaign start`

Starts a campaign and prints the agent's brief.

Flag	Meaning
`--target <text>`	Required. What the agent should hunt, in one line of at most 200 characters.
`--id <id>`	The campaign id. The default is made from the target and the date.

`testkit campaign status`

Shows the active campaign, the bugs it has recorded, and how much of the source the area map covers.

$npx testkit campaign status

No campaign is active.
Last finished: refunds-2026-10, finished 2026-10-14T00:37:22.377Z
Area map: 3.9% of source bytes unclaimed, 0 double-claimed files.

`testkit campaign finish`

Finishes the active campaign, writes its summary to .testkit/campaigns/<id>/summary.md, and prints the summary. The summary is for the pull request that adds the tests.

`testkit bug guide`

Prints the bug record format, the severities, and the lists of cause, impact, and escape ids.

`testkit bug record`

Checks a bug record, stores it as a draft under .testkit/bugs/, and prints the draft id. Write the bug record lists the fields.

testkit bug record <file> [flags]

file is a bug record JSON file, or - to read standard input.

`testkit bug file`

Runs a draft's test at the checked-out commit, and files the bug as an issue only when the test fails. What testkit bug file checks lists the cases where it files nothing.

testkit bug file <id> [flags]

id is the draft id that testkit bug record printed.

Inspect

`testkit discover`

Lists test files and their metadata without running one. Test files shows the output.

Flag	Meaning
`-t, --type <type>`	List one test type. Repeat the flag to add more.
`-s, --suite <suite>`	List one suite. Repeat the flag to add more.
`-f, --file <path>`	List one file. Repeat the flag to add more.
`--runnable-only`	List only the files that no skip rule holds back.
`--strict`	Exit non-zero on a discovery or config diagnostic.
`--output <path>`	Write the discovery JSON to a file.
`--output-mode <mode>`	`compact` or `verbose`. The default is `compact`. `verbose` adds each file's path, id, and status.

`testkit artifacts`

Lists, verifies, or prints what a run kept. Read a run's results shows each use.

testkit artifacts [file] [flags]

Flag	Meaning
`--list`	List the runs that Testkit kept.
`--run <id>`	Read this run. The default is the latest run.
`--verify`	Check the run's manifest and checksums.
`--kind <kind>`	List one kind of artifact.
`--format <format>`	`list` or `text`. The default is `list`. `text` prints the artifact's content.

`testkit status`

Shows Testkit's local state for the product: its services, its active and stale runs, its runtime instances, and its caches.

`testkit workspace`

Prints a summary of the product.

$npx testkit workspace

shop · Testkit workspace
  1 services · 6 suites · 6 files
  latest passed · 6/6 files passed

Flag	Meaning
`--target-limit <n>`	The most quick-run targets to preview. The default is `24`.
`--no-status`	Skip the runtime status.

Check the repo

`testkit doctor`

Runs the config, discovery, lint, and typecheck checks in one command.

$npx testkit doctor

testkit doctor passed for /repo
PASS config-load Loaded testkit config and service config
PASS discovery Discovered 6 testkit files without diagnostics
PASS lint No Testkit lint violations across 6 suite file(s)
PASS typecheck Typechecked 4 generated program(s)

Flag	Meaning
`--no-typecheck`	Skip the TypeScript checks.

`testkit lint`

Runs Testkit's repository hygiene rules. lint lists the rules and their defaults.

$npx testkit lint

testkit lint passed for /repo
Checked 11 source file(s), 6 testkit suite file(s).

`testkit typecheck`

Typechecks testkit.config.ts, helpers, and test files. Testkit checks each engine's files as a separate program.

$npx testkit typecheck

Typechecked 4 testkit program(s) in /repo
PASS config /repo/.testkit/_typecheck/config.tsconfig.json
PASS k6 /repo/.testkit/_typecheck/k6.repo.tsconfig.json
PASS node-vitest /repo/.testkit/_typecheck/node-vitest.repo.tsconfig.json
PASS playwright /repo/.testkit/_typecheck/playwright.repo.tsconfig.json

Set up and clean up

`testkit setup playwright`

Installs the Chromium that browser tests run in.

Flag	Meaning
`--with-deps`	Also install the host libraries that Chromium needs.
`--force`	Repair the browser installation.

`testkit db schema refresh`

Refreshes the cached schema of a source database. It applies to a service whose database sets sourceSchema.

`testkit db schema verify`

Checks that the local schema replay matches the source database schema.

Flag	Meaning
`--skip-schema-source-verify`	Skip the check against the source database.

`testkit cleanup`

Removes stale local state.

$npx testkit cleanup --dry-run

No stale runs to clean.

Flag	Meaning
`--dry-run`	Print what the command would remove.
`--cache <cache>`	Also clear a cache: `runtime`, `bundles`, or `all`. Repeat the flag to add more.
`--resources`	Also remove Docker resources that Testkit owns and that are stale or orphaned.

`testkit destroy`

Removes the Postgres container of each service, and prints one line for each service. It keeps .testkit/results. The next run that needs the database builds it again.

$npx testkit destroy

Destroyed api

`testkit guard unsafe-entrypoint`

Fails with a message that names a replacement command. Use it as the body of a package script that people must run through Testkit.

Flag	Meaning
`-c, --command <name>`	Required. The disabled command, shown in the error.
`-u, --use <command>`	Required. The replacement command, shown in the error.

$npx testkit guard unsafe-entrypoint --command "npm run test:e2e" --use "npm run testkit -- e2e"

Error: npm run test:e2e is disabled because DB-touching tests must run through the isolated testkit harness.
Use npm run testkit -- e2e instead.