the cli · nine commands

Nine commands. One JSON object each.

Every command prints a short summary for people, or one JSON object with --json. Scenario arguments are directories holding manifest.json and the journey script.

the cli · nine commands

Built for people, scripts and agents.

Each command prints a short summary, or one JSON object with --json.

doctor: Checks k6 is exactly v2.2.0, Python is 3.11 or newer, the output directory is writable, and, with --target, that the app answers.
init: Generates a tenant-isolation scenario from a small JSON config, then validates it.
inspect: Explains a scenario: actors, budgets, fixtures, observations and the resolved schedule. Runs nothing.
approve: Binds the scenario's digest to a target origin, so verify --require-approval refuses a changed scenario.
verify: Runs the scenario and prints the verdict, each assertion, any limitations and the report path.
diff: Compares a baseline and a candidate run, with an optional p95 regression gate.
dashboard: Serves your runs on 127.0.0.1 to filter, read failing samples and compare.
up: Repeats bounded runs as slices until Ctrl+C. Records each slice, gives no overall verdict.
prune: Deletes old run directories by count or age, with an optional --dry-run that deletes nothing.

verify · exit codes

0pass
1fail
2inconclusive
3error
130cancelled

A target that never answers is an error, never a pass. Ctrl+C still saves the evidence collected so far. Exit codes for every command

`doctor`

litetraffic doctor [--target URL] [--k6-path PATH] [--output-dir PATH] [--json]

Checks k6 is exactly v2.2.0, Python is 3.11 or newer, the output directory is writable with at least 100 MiB free, and, with a target, that one GET returns 2xx or 3xx within three seconds. It installs nothing and never writes to the target.

`init`

litetraffic init tenant-isolation --config KIT_JSON --out DIR [--json]

Generates a tenant-isolation scenario from a kit config, then loads it the way inspect does. It warns about any identity without markers, since status-only checks cannot see data returned in a denial body.

`inspect`

litetraffic inspect SCENARIO [--seed INTEGER] [--json]

Validates the manifest and script path, resolves the schedule, and reports planned journeys, request and write maxima, phases, assertions, budgets, fixtures, observations and the bundle digest. Secret variables are listed by name only. It runs nothing.

`approve`

litetraffic approve SCENARIO --target-profile NAME --target URL [--json]

Records the scenario's digest and the target's origin in .litetraffic/approvals.json. verify --require-approval then refuses a scenario edited since; in CI, verify --approved-digest SHA does the same without the file.

`verify`

litetraffic verify SCENARIO (--target URL | --e2b-sandbox-id ID --e2b-port PORT)
  [--seed INTEGER] [--repeat COUNT [--same-seed]] [--capture docker:NAME[,NAME...]]
  [--require-approval] [--approved-digest SHA] [--output-dir PATH] [--k6-path PATH] [--json]

Runs the scenario once (or once per seed with --repeat): fixture, k6, evidence, observation, cleanup, then the verdict, each assertion, any limitations and the path to report.html.

`diff`

litetraffic diff BASELINE CANDIDATE [--runs-dir DIR] [--max-p95-regression-percent NUMBER] [--json]

Compares two runs, by directory or run ID, for correctness regressions and p95 change, overall and per operation. It never contacts a target.

`dashboard`

litetraffic dashboard [--runs-dir DIR] [--port PORT]

Serves a read-only dashboard on 127.0.0.1 (default port 8780), with a JSON API behind it. Requests with any other Host header are refused.

`up`

litetraffic up SCENARIO --target URL [--seed N] [--max-slices N] [--json]

Repeats bounded verify runs as slices, with seeds counting up, until Ctrl+C or --max-slices. Each slice keeps its own result; the activity itself has no verdict, and budgets apply per slice.

`prune`

litetraffic prune [--runs-dir DIR] [--keep N] [--older-than DAYS] [--dry-run] [--json]

Deletes old run directories by count or age. --dry-run lists what would be deleted and deletes nothing. Symlinks and series summaries are never deleted.

Exit codes

Every command exits 2 on a CLI usage error. dashboard exits 3 when its port cannot be bound and 130 when stopped; a cancelled verify also exits 130. Integrations should read the JSON verdict as well as the shell status.

Command	0	1	2	3
`doctor`	Checks succeeded	—	Usage error	Failed check
`inspect`	Valid manifest	—	Usage error	Invalid scenario
`verify`	pass	fail	inconclusive	error, or a preflight or approval problem
`diff`	Comparison pass	Comparison fail	Inconclusive	Invalid arguments or artifacts
`up`	Completed or stopped	—	Usage error	Preflight error or a slice raised
`approve`	Approval recorded	—	Usage error	Invalid scenario, target or approvals file
`prune`	Pruned or listed	—	Usage error	Invalid options or deletion failed

The full reference, with every option and default, is in the CLI documentation.