CLI reference
This page lists the commands and options of veritas, its exit codes and verdicts, the environment variables it reads, and its JSON output. The commands that run the pipeline (discover, analyze, mutate, prove, run and replay) write their results to .veritas/runs/<run-id>/; the files are described in Reports and artifacts.
veritas [global options] <command> [options]veritas init --yes
veritas run --profile standard
veritas report --format html > report.html
veritas explain F-0b43c88cc3a6Exit codes
| Code | Meaning |
|---|---|
0 | Success. The verdict can still be pass_with_warnings |
1 | Policy failure: a confirmed specification violation with policy.confirmedViolation: fail, or a missed policy.maxNewSurvivors or policy.minPropertyCoverage |
2 | User error: invalid arguments, a missing or invalid configuration, an unknown id, or a refused operation |
3 | Tool error: a stage failed, or a solver or child process crashed |
4 | Inconclusive results with policy.inconclusiveBehavior: fail |
Exit code 1 has two causes. One is a confirmed specification violation (a finding of kind spec_implementation_mismatch, counterexample or spec_violation_candidate with certainty confirmed) while policy.confirmedViolation is fail. The other is a missed policy.maxNewSurvivors or policy.minPropertyCoverage. Suspected findings and other confirmed findings, such as a surviving mutant, are reported but do not fail the run.
unknown, timeout and unsupported results never count as success: with policy.inconclusiveBehavior set to warn or ignore, the exit code is 0, but the verdict is pass_with_warnings and the reasons list each result.
veritas improve and veritas test replay give some codes a command-specific meaning; see Notes by command.
Verdicts
Commands that run stages (discover, analyze, mutate, prove, run, replay) end with a verdict, which is also recorded in run.json.
| Verdict | Exit code | When |
|---|---|---|
pass | 0 | No findings to review and no inconclusive results |
pass_with_warnings | 0 | Findings to review, confirmed violations reported as warnings (confirmedViolation: warn), or inconclusive results under warn or ignore |
policy_failure | 1 | A confirmed violation with confirmedViolation: fail, or a missed policy threshold |
tool_error | 3 | A stage ended with error or failed |
inconclusive | 4 | Inconclusive stages or claims with inconclusiveBehavior: fail |
When several apply, the first one in this order wins: policy_failure, tool_error, inconclusive.
JSON output
With the global --json option, stdout contains exactly one JSON value and nothing else; progress messages and logs go to stderr. Help and the version are JSON too ({"status":"ok","help":"..."}, {"status":"ok","version":"..."}), and so are errors:
{
"status": "error",
"category": "user",
"code": "USAGE",
"message": "unknown option '--frobnicate'",
"hint": "run `veritas --help`",
"exitCode": 2
}code identifies the error (for example CONFIG_MISSING, NO_RUN, ROOT_NOT_FOUND) and hint suggests what to do. --log-format json changes only the stderr log, to one JSON object per line.
veritas report --json is the same as veritas report --format json. --json together with another --format is a user error (FORMAT_CONFLICT).
Environment variables
| Variable | Effect |
|---|---|
VERITAS_DEBUG=1 | Same as --debug |
VERITAS_ACTOR | Name recorded for spec decisions and approvals when --actor is not given; without it, the git user.name is used |
VERITAS_SANDBOX_NODE | Path of a Node.js 25 or later used to run project code with network access blocked |
VERITAS_CACHE_KEY_FILE | Key file that signs cache entries (default ~/.cache/veritas/cache-key, or %LOCALAPPDATA%\veritas\cache-key on Windows) |
CI | When set to anything other than a false value, improve --apply refuses to run |
ANTHROPIC_API_KEY, OPENAI_API_KEY | Credentials for the claude and openai LLM providers (see LLM providers) |
Commands and options
Global options
These options belong to veritas itself and apply to every command. Put them before or after the command name.
| Option | Description | Values | Default |
|---|---|---|---|
-V, --version | output the version number | ||
--json | print machine-readable JSON on stdout; logs go to stderr | ||
-C, --root <dir> | project root | current directory | |
--allow-code-config | allow loading veritas.config.{ts,js,mjs}, which executes project code | ||
--debug | log child processes, restricted calls of project code, stages and cache use to stderr (also VERITAS_DEBUG=1) | ||
--log-format <format> | stderr log format: text, or json (one object per line) | text, json | text |
Commands
| Command | Description |
|---|---|
veritas init | detect the project and write .veritas/config.json |
veritas doctor | check tools, credentials and the restricted runner for project code; report disabled/degraded features |
veritas discover | collect specification evidence |
veritas spec | review the property registry |
veritas analyze | index code and tests, map them to properties and assess tests (only [path], if given) |
veritas mutate | run mutation testing and relate mutants to properties |
veritas test | property-based tests |
veritas prove | verify formalized properties with an SMT solver (bounded) |
veritas improve | plan test-only improvements (dry run, the default) or apply an approved plan in an isolated copy; exit 0 plan ready/improved, 4 no safe improvement or spec decision needed, 1 blocked, 2 bad token or CI, 3 tool error |
veritas report | print the latest results |
veritas run | run the full pipeline |
veritas replay | re-run a previous run with the same stages and options |
veritas explain | show the evidence chain of a finding |
veritas init
detect the project and write .veritas/config.json
veritas init [options]| Option | Description | Values | Default |
|---|---|---|---|
-y, --yes | non-interactive: accept the detected configuration | ||
--force | overwrite an existing configuration | ||
--dry-run | print the configuration without writing |
veritas doctor
check tools, credentials and the restricted runner for project code; report disabled/degraded features
veritas doctorveritas discover
collect specification evidence
veritas discover [options]| Option | Description | Values | Default |
|---|---|---|---|
--offline | make no network requests: local sources only, no LLM | ||
--sources <list> | comma-separated: local,github,web,all | local | |
--allow-domain <domain...> | allow a web domain (also needs sources.web.enabled in config) | ||
--max-pages <n> | web page budget |
veritas spec
review the property registry
veritas spec <command>| Subcommand | Description |
|---|---|
veritas spec list | list properties of the latest run |
veritas spec show | show a property, its sources and the decisions recorded for it |
veritas spec accept | accept a property as the specification (recorded in .veritas/approvals.json) |
veritas spec reject | reject a property (recorded in .veritas/approvals.json) |
veritas spec diff | compare properties of the last two runs |
veritas spec export | print the registry as JSON |
veritas spec list
list properties of the latest run
veritas spec listveritas spec show
show a property, its sources and the decisions recorded for it
veritas spec show <id>| Argument | Required | Description |
|---|---|---|
<id> | yes |
veritas spec accept
accept a property as the specification (recorded in .veritas/approvals.json)
veritas spec accept <id> [options]| Argument | Required | Description |
|---|---|---|
<id> | yes |
| Option | Description | Values | Default |
|---|---|---|---|
--reason <text> | reason recorded with the decision | required | |
--actor <name> | who decides (default: VERITAS_ACTOR, then git user.name) |
veritas spec reject
reject a property (recorded in .veritas/approvals.json)
veritas spec reject <id> [options]| Argument | Required | Description |
|---|---|---|
<id> | yes |
| Option | Description | Values | Default |
|---|---|---|---|
--reason <text> | reason recorded with the decision | required | |
--actor <name> | who decides (default: VERITAS_ACTOR, then git user.name) |
veritas spec diff
compare properties of the last two runs
veritas spec diffveritas spec export
print the registry as JSON
veritas spec exportveritas analyze
index code and tests, map them to properties and assess tests (only [path], if given)
veritas analyze [path] [options]| Argument | Required | Description |
|---|---|---|
[path] | no |
| Option | Description | Values | Default |
|---|---|---|---|
--since <ref> | mark candidates in code changed since this git ref |
veritas mutate
run mutation testing and relate mutants to properties
veritas mutate [options]| Option | Description | Values | Default |
|---|---|---|---|
--since <ref> | mutate only code changed since this git ref | ||
--scope <glob> | mutate only files matching this glob | ||
--import <file> | normalize an existing mutation-testing-elements report instead of running mutator | ||
--kill-matrix | run every covering test for every mutant and report the kill matrix (slower) |
veritas test
property-based tests
veritas test <command>| Subcommand | Description |
|---|---|
veritas test replay | replay a recorded property-based test with its seed and shrink path; exit 0 when the recorded result is reproduced, 4 when it is not |
veritas test generate | generate fast-check property tests for formalized properties (written under .veritas/generated-tests) |
veritas test replay
replay a recorded property-based test with its seed and shrink path; exit 0 when the recorded result is reproduced, 4 when it is not
veritas test replay <pbt-id> [options]| Argument | Required | Description |
|---|---|---|
<pbt-id> | yes |
| Option | Description | Values | Default |
|---|---|---|---|
--run <run-id> | look in this run instead of the most recent ones |
veritas test generate
generate fast-check property tests for formalized properties (written under .veritas/generated-tests)
veritas test generate [options]| Option | Description | Values | Default |
|---|---|---|---|
--property <id> | generate a test for this property only | ||
--dry-run | print instead of writing | ||
--force | replace generated files that were changed since they were written |
veritas prove
verify formalized properties with an SMT solver (bounded)
veritas prove [options]| Option | Description | Values | Default |
|---|---|---|---|
--property <id> | verify this property only | ||
--include-proposed | also check properties that are not accepted (experimental) | ||
--engine <engine> | z3 (bounded checks) or lean (kernel-checked proofs) | z3, lean | z3 |
veritas improve
plan test-only improvements (dry run, the default) or apply an approved plan in an isolated copy; exit 0 plan ready/improved, 4 no safe improvement or spec decision needed, 1 blocked, 2 bad token or CI, 3 tool error
veritas improve [options]| Option | Description | Values | Default |
|---|---|---|---|
--include-proposed | also use proposed (not yet accepted) properties as the oracle | ||
--dry-run | plan and print the plan and its approval token; never writes project files | ||
--apply | apply an approved plan (needs --plan and --approve; refused in CI) | ||
--plan <id> | plan id printed by the dry run | ||
--approve <token> | approval token printed by the dry run | ||
--actor <name> | who approves, recorded with the plan (default: VERITAS_ACTOR, then git user.name) | ||
--run <run-id> | plan from this run instead of the latest one | ||
--max-iterations <n> | maximum apply attempts for the plan (1-20) |
veritas report
print the latest results
veritas report [options]| Option | Description | Values | Default |
|---|---|---|---|
--format <format> | output format (default: text, or json with --json) | text, json, markdown, html, sarif | |
--run <run-id> | report on this run instead of the latest |
veritas run
run the full pipeline
veritas run [options]| Option | Description | Values | Default |
|---|---|---|---|
--profile <profile> | quick (no project code), standard (+ mutation) or deep (+ property tests and proofs) | quick, standard, deep | standard |
--offline | Veritas makes no network requests (sources, LLM); project tests still run as with pnpm test | ||
--since <ref> | limit mutation to code changed since this git ref | ||
--include-proposed | also verify properties that are not accepted (experimental) |
veritas replay
re-run a previous run with the same stages and options
veritas replay <run-id>| Argument | Required | Description |
|---|---|---|
<run-id> | yes |
veritas explain
show the evidence chain of a finding
veritas explain <finding-id>| Argument | Required | Description |
|---|---|---|
<finding-id> | yes |
Notes by command
init and doctor
init detects the package manager, tsconfig.json and the source and test globs, and writes .veritas/config.json. It does not overwrite an existing configuration unless you pass --force, and fails with VITEST_NOT_FOUND when the project does not use Vitest.
doctor lists each capability (node, git, package_manager, typescript, vitest, mutator, fast_check, z3, lean, llm, network, sandbox), its state, and the features it affects. Mutator, fast-check and Z3 are taken from the project when it installs them, and otherwise from the copies installed with Veritas; doctor shows which. For LLM CLIs, it checks only whether you are logged in.
Commands that run stages
| Command | Stages | Network access |
|---|---|---|
discover | discover | Sources and LLM enabled in the configuration |
analyze | index, discover, spec, map, assess | None |
mutate | index, discover, spec, map, mutate, assess | None |
prove | index, discover, spec, map, prove, assess, report | None |
run --profile quick | index, discover, spec, map, assess, report | Sources and LLM enabled in the configuration |
run --profile standard | quick + mutate | Sources and LLM enabled in the configuration |
run --profile deep | standard + pbt, prove | Sources and LLM enabled in the configuration |
replay | the stages of the recorded run | None |
--offline makes Veritas itself send no network request: no GitHub or web sources and no LLM. It does not restrict the project's own tests, which mutation testing runs; to keep those off the network, see Untrusted repositories.
Only commands with the report stage (run, prove, and replay of such a run) write report files to the run directory. veritas report renders a report from any run.
--since <ref> limits mutation testing to code changed since a git ref. --include-proposed also checks properties that are not accepted; findings from them are at most suspected.
prove --engine lean uses Lean 4 with Lake, which you install separately; the default engine is Z3. mutate --import <file> reads an existing mutation-testing-elements report instead of running mutator, and cannot be combined with --kill-matrix.
spec
spec accept and spec reject add a decision with the actor, time and reason to .veritas/approvals.json. The actor is --actor, else VERITAS_ACTOR, else the git user.name. A decision applies to the version of the property it was made for; if the property changes, decide again. Only a recorded decision makes a property accepted. See Specifications.
test
test generate writes Vitest and fast-check test files to .veritas/generated-tests/ and does not run them. test replay <pbt-id> re-runs a recorded property-based test with the same seed, number of runs and shrink path. It exits with 0 when it reproduces the recorded result and 4 when it does not.
improve
Without --apply, improve is a dry run that changes no project file and prints a plan id and an approval token. To apply the plan, run improve --apply --plan <id> --approve <token>. Applying is refused in CI (IMPROVE_APPLY_IN_CI).
| Exit code | Outcome |
|---|---|
0 | Plan ready (dry run), or tests improved (apply) |
1 | Blocked |
2 | Invalid plan id or token, or applying in CI |
3 | Tool error |
4 | No safe improvement, or a specification decision is needed first |
See Improving tests.
report, explain and replay
report prints the latest run, or the run given with --run, as text (the default), json, markdown, html or sarif. explain <finding-id> prints the evidence behind a finding: quoted sources, properties, tests, assessments, mutants and solver claims. replay <run-id> runs a recorded run again with the same stages and options, always offline.