CLI リファレンス
veritas のコマンドとオプション、終了コードと verdict、読み取る環境変数、JSON 出力をまとめます。パイプラインを実行するコマンド(discover、analyze、mutate、prove、run、replay)は、結果を .veritas/runs/<run-id>/ に書き出します。各ファイルについてはレポートと成果物を参照してください。
veritas [グローバルオプション] <command> [オプション]veritas init --yes
veritas run --profile standard
veritas report --format html > report.html
veritas explain F-0b43c88cc3a6終了コード
| コード | 意味 |
|---|---|
0 | 成功。verdict が pass_with_warnings の場合もあります |
1 | ポリシー違反。policy.confirmedViolation: fail で仕様違反が確定したか、policy.maxNewSurvivors または policy.minPropertyCoverage を満たさなかった |
2 | ユーザーのエラー。引数の誤り、設定ファイルがない・不正、存在しない ID、拒否された操作 |
3 | ツールのエラー。ステージの失敗、ソルバーや子プロセスの異常終了 |
4 | policy.inconclusiveBehavior: fail のもとで、判定できない結果があった |
終了コード 1 になる理由は 2 つあります。1 つは、policy.confirmedViolation が fail のときに仕様違反が確定した場合です(種類が spec_implementation_mismatch、counterexample、spec_violation_candidate のいずれかで、certainty が confirmed の finding)。もう 1 つは、policy.maxNewSurvivors か policy.minPropertyCoverage を満たさなかった場合です。suspected の finding や、生き残った mutant のようなほかの確定した finding は、報告されますが失敗にはなりません。
unknown、timeout、unsupported は成功として数えません。policy.inconclusiveBehavior が warn か ignore なら終了コードは 0 ですが、verdict は pass_with_warnings になり、理由の一覧にそれぞれの結果が載ります。
veritas improve と veritas test replay では、一部のコードの意味が変わります。コマンドごとの補足を参照してください。
verdict
ステージを実行するコマンド(discover、analyze、mutate、prove、run、replay)は、最後に verdict を出し、run.json にも記録します。
| verdict | 終了コード | 条件 |
|---|---|---|
pass | 0 | 確認が必要な finding も、判定できない結果もない |
pass_with_warnings | 0 | 確認が必要な finding がある、確定した違反を警告として扱った(confirmedViolation: warn)、または warn / ignore で判定できない結果がある |
policy_failure | 1 | confirmedViolation: fail で違反が確定した、またはポリシーの基準を満たさなかった |
tool_error | 3 | ステージが error または failed で終わった |
inconclusive | 4 | inconclusiveBehavior: fail で、判定できないステージや主張がある |
複数に当てはまるときは、policy_failure、tool_error、inconclusive の順に優先します。
JSON 出力
グローバルオプション --json を付けると、stdout には JSON の値が 1 つだけ出力され、進捗メッセージやログは stderr に出ます。ヘルプとバージョン({"status":"ok","help":"..."}、{"status":"ok","version":"..."})も、エラーも JSON です。
{
"status": "error",
"category": "user",
"code": "USAGE",
"message": "unknown option '--frobnicate'",
"hint": "run `veritas --help`",
"exitCode": 2
}code はエラーの種類(CONFIG_MISSING、NO_RUN、ROOT_NOT_FOUND など)を、hint は対処方法を示します。--log-format json を付けると、stderr のログが 1 行に 1 つの JSON オブジェクトになります。stdout は変わりません。
veritas report --json は veritas report --format json と同じです。--json と json 以外の --format を一緒に指定すると、ユーザーのエラー(FORMAT_CONFLICT)になります。
環境変数
| 変数 | 効果 |
|---|---|
VERITAS_DEBUG=1 | --debug と同じです |
VERITAS_ACTOR | --actor を指定しないときに、仕様の判断や承認に記録する名前です。ないときは git の user.name を使います |
VERITAS_SANDBOX_NODE | ネットワークを遮断してプロジェクトのコードを実行するための、Node.js 25 以上のパスです |
VERITAS_CACHE_KEY_FILE | キャッシュに署名する鍵のファイルです(既定は ~/.cache/veritas/cache-key、Windows では %LOCALAPPDATA%\veritas\cache-key) |
CI | false を表す値以外が設定されていると、improve --apply は実行を拒否します |
ANTHROPIC_API_KEY、OPENAI_API_KEY | LLM プロバイダー claude と openai の認証情報です(LLM プロバイダーを参照) |
コマンドとオプション
次の一覧は CLI のヘルプから生成しているため、英語のままです。
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 |
コマンドごとの補足
init と doctor
init はパッケージマネージャー、tsconfig.json、ソースとテストの glob を検出して、.veritas/config.json を書き出します。既存の設定は --force を付けない限り上書きしません。プロジェクトが Vitest を使っていなければ、VITEST_NOT_FOUND で失敗します。
doctor は、各ケイパビリティ(node、git、package_manager、typescript、vitest、mutator、fast_check、z3、lean、llm、network、sandbox)の状態と、それが影響する機能を一覧にします。mutator、fast-check、Z3 は、プロジェクトにインストールされていればそれを使い、なければ Veritas と一緒にインストールされたものを使います。どちらを使うかも doctor に表示されます。LLM の CLI については、ログインしているかどうかだけを確かめます。
ステージを実行するコマンド
| コマンド | ステージ | ネットワークの利用 |
|---|---|---|
discover | discover | 設定で有効にしたソースと LLM |
analyze | index, discover, spec, map, assess | なし |
mutate | index, discover, spec, map, mutate, assess | なし |
prove | index, discover, spec, map, prove, assess, report | なし |
run --profile quick | index, discover, spec, map, assess, report | 設定で有効にしたソースと LLM |
run --profile standard | quick + mutate | 設定で有効にしたソースと LLM |
run --profile deep | standard + pbt, prove | 設定で有効にしたソースと LLM |
replay | 記録された実行と同じステージ | なし |
--offline を付けると、Veritas 自身はネットワークにアクセスしません。GitHub や Web のソースも LLM も使いません。ただし、mutation testing で実行するプロジェクト自身のテストは制限しません。テストもネットワークから切り離す方法は、信頼できないリポジトリを参照してください。
レポートのファイルを実行ディレクトリに書くのは、report ステージを含む run と prove、およびそれらを replay したときだけです。veritas report を使えば、どの実行からでもレポートを作れます。
--since <ref> を付けると、mutation testing の対象を、その git の ref から変更されたコードに絞ります。--include-proposed を付けると、accepted でない Property も検査します。それらから出た finding は suspected 以下になります。
prove --engine lean は、別途インストールした Lean 4 と Lake を使います。既定のエンジンは Z3 です。mutate --import <file> は、mutator を実行せずに既存の mutation-testing-elements のレポートを読み込みます。--kill-matrix とは一緒に使えません。
spec
spec accept と spec reject は、判断した人、日時、理由を .veritas/approvals.json に追記します。判断した人の名前は --actor、VERITAS_ACTOR、git の user.name の順に決まります。判断は、そのときの Property のバージョンにだけ効きます。Property の内容が変わったら、もう一度判断してください。Property が accepted になるのは、判断を記録したときだけです。仕様の確定を参照してください。
test
test generate は Vitest と fast-check のテストファイルを .veritas/generated-tests/ に書き出します。実行はしません。test replay <pbt-id> は、記録された property-based テストを、同じ seed、実行回数、shrink の経路で実行し直します。記録どおりの結果が出れば 0、出なければ 4 で終了します。
improve
--apply を付けなければドライランになり、プロジェクトのファイルは変更せずに、計画 ID と承認トークンを表示します。計画を適用するには improve --apply --plan <id> --approve <token> を実行します。CI の中では適用を拒否します(IMPROVE_APPLY_IN_CI)。
| 終了コード | 結果 |
|---|---|
0 | 計画ができた(ドライラン)、またはテストを改善した(適用) |
1 | ブロックされた |
2 | 計画 ID やトークンが正しくない、または CI の中で適用しようとした |
3 | ツールのエラー |
4 | 安全な改善がない、または先に仕様の判断が必要 |
テストの改善を参照してください。
report、explain、replay
report は、最新の実行(--run を付けたときはその実行)を、text(既定)、json、markdown、html、sarif のいずれかで表示します。explain <finding-id> は、finding の根拠(引用した出典、Property、テスト、評価、mutant、ソルバーの主張)を表示します。replay <run-id> は、記録された実行を同じステージとオプションで実行し直します。再実行は常にオフラインです。