# CLI reference

Every command and flag in Testkit 0.4.1.

## How to run a command

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

```console $ 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.

```usage
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`](https://turnstone.cloud/docs/configuration.md#execution). |
| `--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](https://turnstone.cloud/docs/ci.md#what-fails-the-gate) lists the other cases.

### `testkit run status`

Shows the runs that are active.

```console $ 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](https://turnstone.cloud/docs/ci.md#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](https://turnstone.cloud/docs/campaigns.md) 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.

```console $ 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](https://turnstone.cloud/docs/bug-reports.md#write-the-bug-record) lists the fields.

```usage
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](https://turnstone.cloud/docs/bug-reports.md#what-testkit-bug-file-checks) lists the cases where it files nothing.

```usage
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](https://turnstone.cloud/docs/test-files.md#see-what-testkit-found) 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](https://turnstone.cloud/docs/results.md) shows each use.

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

```console $ 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.

```console $ 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`](https://turnstone.cloud/docs/configuration.md#lint) lists the rules and their defaults.

```console $ 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.

```console $ 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`](https://turnstone.cloud/docs/configuration.md#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.

```console $ 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.

```console $ 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. |

```console $ 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.
```