Skip to content

CLI リファレンス ​

veritas のコマンドとオプション、終了コードと verdict、読み取る環境変数、JSON 出力をまとめます。パイプラインを実行するコマンド(discover、analyze、mutate、prove、run、replay)は、結果を .veritas/runs/<run-id>/ に書き出します。各ファイルについてはレポートと成果物を参照してください。

bash
veritas [グローバルオプション] <command> [オプション]
bash
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ツールのエラー。ステージの失敗、ソルバーや子プロセスの異常終了
4policy.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終了コード条件
pass0確認が必要な finding も、判定できない結果もない
pass_with_warnings0確認が必要な finding がある、確定した違反を警告として扱った(confirmedViolation: warn)、または warn / ignore で判定できない結果がある
policy_failure1confirmedViolation: fail で違反が確定した、またはポリシーの基準を満たさなかった
tool_error3ステージが error または failed で終わった
inconclusive4inconclusiveBehavior: fail で、判定できないステージや主張がある

複数に当てはまるときは、policy_failure、tool_error、inconclusive の順に優先します。

JSON 出力 ​

グローバルオプション --json を付けると、stdout には JSON の値が 1 つだけ出力され、進捗メッセージやログは stderr に出ます。ヘルプとバージョン({"status":"ok","help":"..."}、{"status":"ok","version":"..."})も、エラーも JSON です。

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)
CIfalse を表す値以外が設定されていると、improve --apply は実行を拒否します
ANTHROPIC_API_KEY、OPENAI_API_KEYLLM プロバイダー 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.

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

コマンドごとの補足 ​

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 については、ログインしているかどうかだけを確かめます。

ステージを実行するコマンド ​

コマンドステージネットワークの利用
discoverdiscover設定で有効にしたソースと LLM
analyzeindex, discover, spec, map, assessなし
mutateindex, discover, spec, map, mutate, assessなし
proveindex, discover, spec, map, prove, assess, reportなし
run --profile quickindex, discover, spec, map, assess, report設定で有効にしたソースと LLM
run --profile standardquick + mutate設定で有効にしたソースと LLM
run --profile deepstandard + 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> は、記録された実行を同じステージとオプションで実行し直します。再実行は常にオフラインです。

Apache-2.0 ライセンスで公開しています。