Skip to content

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.

bash
veritas [global options] <command> [options]
bash
veritas init --yes
veritas run --profile standard
veritas report --format html > report.html
veritas explain F-0b43c88cc3a6

Exit codes ​

CodeMeaning
0Success. The verdict can still be pass_with_warnings
1Policy failure: a confirmed specification violation with policy.confirmedViolation: fail, or a missed policy.maxNewSurvivors or policy.minPropertyCoverage
2User error: invalid arguments, a missing or invalid configuration, an unknown id, or a refused operation
3Tool error: a stage failed, or a solver or child process crashed
4Inconclusive 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.

VerdictExit codeWhen
pass0No findings to review and no inconclusive results
pass_with_warnings0Findings to review, confirmed violations reported as warnings (confirmedViolation: warn), or inconclusive results under warn or ignore
policy_failure1A confirmed violation with confirmedViolation: fail, or a missed policy threshold
tool_error3A stage ended with error or failed
inconclusive4Inconclusive 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:

json
{
  "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 ​

VariableEffect
VERITAS_DEBUG=1Same as --debug
VERITAS_ACTORName recorded for spec decisions and approvals when --actor is not given; without it, the git user.name is used
VERITAS_SANDBOX_NODEPath of a Node.js 25 or later used to run project code with network access blocked
VERITAS_CACHE_KEY_FILEKey file that signs cache entries (default ~/.cache/veritas/cache-key, or %LOCALAPPDATA%\veritas\cache-key on Windows)
CIWhen set to anything other than a false value, improve --apply refuses to run
ANTHROPIC_API_KEY, OPENAI_API_KEYCredentials 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.

OptionDescriptionValuesDefault
-V, --versionoutput the version number
--jsonprint machine-readable JSON on stdout; logs go to stderr
-C, --root <dir>project rootcurrent directory
--allow-code-configallow loading veritas.config.{ts,js,mjs}, which executes project code
--debuglog 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, jsontext

Commands ​

CommandDescription
veritas initdetect the project and write .veritas/config.json
veritas doctorcheck tools, credentials and the restricted runner for project code; report disabled/degraded features
veritas discovercollect specification evidence
veritas specreview the property registry
veritas analyzeindex code and tests, map them to properties and assess tests (only [path], if given)
veritas mutaterun mutation testing and relate mutants to properties
veritas testproperty-based tests
veritas proveverify formalized properties with an SMT solver (bounded)
veritas improveplan 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 reportprint the latest results
veritas runrun the full pipeline
veritas replayre-run a previous run with the same stages and options
veritas explainshow the evidence chain of a finding

veritas init ​

detect the project and write .veritas/config.json

text
veritas init [options]
OptionDescriptionValuesDefault
-y, --yesnon-interactive: accept the detected configuration
--forceoverwrite an existing configuration
--dry-runprint the configuration without writing

veritas doctor ​

check tools, credentials and the restricted runner for project code; report disabled/degraded features

text
veritas doctor

veritas discover ​

collect specification evidence

text
veritas discover [options]
OptionDescriptionValuesDefault
--offlinemake no network requests: local sources only, no LLM
--sources <list>comma-separated: local,github,web,alllocal
--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

text
veritas spec <command>
SubcommandDescription
veritas spec listlist properties of the latest run
veritas spec showshow a property, its sources and the decisions recorded for it
veritas spec acceptaccept a property as the specification (recorded in .veritas/approvals.json)
veritas spec rejectreject a property (recorded in .veritas/approvals.json)
veritas spec diffcompare properties of the last two runs
veritas spec exportprint the registry as JSON

veritas spec list ​

list properties of the latest run

text
veritas spec list

veritas spec show ​

show a property, its sources and the decisions recorded for it

text
veritas spec show <id>
ArgumentRequiredDescription
<id>yes

veritas spec accept ​

accept a property as the specification (recorded in .veritas/approvals.json)

text
veritas spec accept <id> [options]
ArgumentRequiredDescription
<id>yes
OptionDescriptionValuesDefault
--reason <text>reason recorded with the decisionrequired
--actor <name>who decides (default: VERITAS_ACTOR, then git user.name)

veritas spec reject ​

reject a property (recorded in .veritas/approvals.json)

text
veritas spec reject <id> [options]
ArgumentRequiredDescription
<id>yes
OptionDescriptionValuesDefault
--reason <text>reason recorded with the decisionrequired
--actor <name>who decides (default: VERITAS_ACTOR, then git user.name)

veritas spec diff ​

compare properties of the last two runs

text
veritas spec diff

veritas spec export ​

print the registry as JSON

text
veritas spec export

veritas analyze ​

index code and tests, map them to properties and assess tests (only [path], if given)

text
veritas analyze [path] [options]
ArgumentRequiredDescription
[path]no
OptionDescriptionValuesDefault
--since <ref>mark candidates in code changed since this git ref

veritas mutate ​

run mutation testing and relate mutants to properties

text
veritas mutate [options]
OptionDescriptionValuesDefault
--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-matrixrun every covering test for every mutant and report the kill matrix (slower)

veritas test ​

property-based tests

text
veritas test <command>
SubcommandDescription
veritas test replayreplay 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 generategenerate 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

text
veritas test replay <pbt-id> [options]
ArgumentRequiredDescription
<pbt-id>yes
OptionDescriptionValuesDefault
--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)

text
veritas test generate [options]
OptionDescriptionValuesDefault
--property <id>generate a test for this property only
--dry-runprint instead of writing
--forcereplace generated files that were changed since they were written

veritas prove ​

verify formalized properties with an SMT solver (bounded)

text
veritas prove [options]
OptionDescriptionValuesDefault
--property <id>verify this property only
--include-proposedalso check properties that are not accepted (experimental)
--engine <engine>z3 (bounded checks) or lean (kernel-checked proofs)z3, leanz3

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

text
veritas improve [options]
OptionDescriptionValuesDefault
--include-proposedalso use proposed (not yet accepted) properties as the oracle
--dry-runplan and print the plan and its approval token; never writes project files
--applyapply 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

text
veritas report [options]
OptionDescriptionValuesDefault
--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

text
veritas run [options]
OptionDescriptionValuesDefault
--profile <profile>quick (no project code), standard (+ mutation) or deep (+ property tests and proofs)quick, standard, deepstandard
--offlineVeritas 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-proposedalso verify properties that are not accepted (experimental)

veritas replay ​

re-run a previous run with the same stages and options

text
veritas replay <run-id>
ArgumentRequiredDescription
<run-id>yes

veritas explain ​

show the evidence chain of a finding

text
veritas explain <finding-id>
ArgumentRequiredDescription
<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 ​

CommandStagesNetwork access
discoverdiscoverSources and LLM enabled in the configuration
analyzeindex, discover, spec, map, assessNone
mutateindex, discover, spec, map, mutate, assessNone
proveindex, discover, spec, map, prove, assess, reportNone
run --profile quickindex, discover, spec, map, assess, reportSources and LLM enabled in the configuration
run --profile standardquick + mutateSources and LLM enabled in the configuration
run --profile deepstandard + pbt, proveSources and LLM enabled in the configuration
replaythe stages of the recorded runNone

--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 codeOutcome
0Plan ready (dry run), or tests improved (apply)
1Blocked
2Invalid plan id or token, or applying in CI
3Tool error
4No 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.

Released under the Apache-2.0 License.