CLI Reference

This page documents the CLI surface that currently ships in this repo.

All examples here match the command shapes exercised in tests/framework.test.mjs. Most commands print JSON to stdout. The agent-facing exception is veritas shadow run, which defaults to lint-style feedback; use --format json when you need the previous machine-readable orchestration object.

Entry Points

• npx @kontourai/veritas ...
• npx @kontourai/veritas --help
• npx @kontourai/veritas report --help
• npx @kontourai/veritas budget --help
• npx @kontourai/veritas <subcommand> --help
• node bin/veritas-report.mjs ...

The convenience veritas-report binary defaults to repo-local starter paths:

• .veritas/repo.adapter.json
• .veritas/policy-packs/default.policy-pack.json

Core Workflow

The shortest end-user path is:

npm install -D @kontourai/veritas
npx @kontourai/veritas init
npx @kontourai/veritas budget --working-tree
npx @kontourai/veritas shadow run --working-tree

Use budget when you want the concise “what are we checking and what should be reviewed?” view. Use shadow run when you want proof, evidence, eval-draft orchestration, and agent-readable feedback in one command. Use report when you want evidence only. Treat print and apply as optional installer helpers, not the main product path.

Breaking proof-command migration notes live in ../MIGRATING.md.

Commands

init

Bootstraps the starter kit for a target repo.

npx @kontourai/veritas init [--root <path>] [--project-name <name>] [--proof-lane <cmd>] [--force]
npx @kontourai/veritas init --explore [--root <path>] [--project-name <name>] [--proof-lane <cmd>] [--output .veritas/init-plans/<name>.json]
npx @kontourai/veritas init --guided --answers <answers.json> [--root <path>] [--project-name <name>] [--output .veritas/init-plans/<name>.json]
npx @kontourai/veritas init --apply --plan <path> [--root <path>] [--force]

Writes:

• .veritas/GOVERNANCE.md
• .veritas/README.md
• .veritas/repo.adapter.json
• .veritas/policy-packs/default.policy-pack.json
• .veritas/team/default.team-profile.json
• .veritas/evidence/
• AGENTS.md and CLAUDE.md governance blocks

init keeps stdout machine-readable JSON and prints the suggested CODEOWNERS block to stderr as informational text.

The bootstrap logic infers:

• repo kind: application, workspace, or docs
• likely source roots
• likely test roots
• whether workflows exist
• an initial proof lane from common npm scripts

Guided initialization splits setup into a reviewed artifact flow:

• --explore inspects the repo and emits a recommendation JSON without writing starter files.
• --guided --answers <answers.json> folds owner-provided boundaries, style, proof-lane, and instruction-target choices into the recommendation.
• --output is intentionally constrained to .veritas/init-plans/ so reviewed setup plans stay repo-local and obvious.
• --apply --plan <path> is the only guided write path. It validates the plan schema, target root, payload hashes, and overwrite rules before writing.
• Brownfield repos with legacy guidance or convergence scripts also receive a legacy_verification inventory and recommended_proof_family_inventory. Unknown catch evidence stays candidate/advisory until a maintainer supplies owner and review evidence.
• Unknown init flags fail before any files are written.

Answers are JSON and may include:

{
  "proofLane": "npm run verify",
  "selectedInstructionTargets": ["AGENTS.md", "CLAUDE.md"],
  "boundaries": ["Do not edit generated snapshots without approval."],
  "codingStyle": "Prefer small ESM modules.",
  "releaseExpectations": "Run npm test and npm run verify before merge."
}

selectedInstructionTargets controls the AI instruction files that --apply mutates and the governance-block rule that the starter policy pack enforces.

report

Generates an evidence artifact for a set of files or a repo state slice.

npx @kontourai/veritas report [--root <path>] [--adapter <path>] [--policy-pack <path>] [--run-id <id>] [file ...]
npx @kontourai/veritas report --format feedback --working-tree
npx @kontourai/veritas report --working-tree
npx @kontourai/veritas report --staged
npx @kontourai/veritas report --unstaged --untracked
npx @kontourai/veritas report --changed-from <ref> --changed-to <ref>

Important behaviors:

• explicit files produce source_kind: "explicit-files"
• branch comparisons produce source_kind: "branch-diff"
• working-tree modes produce source_kind: "working-tree"
• the adapter selects proof commands through explicit proofLanes, requiredProofLaneIds, defaultProofLaneIds, and optional surfaceProofRoutes
• the artifact is written to the adapter-defined artifactDir
• every artifact includes surface.input, a Surface TrustInput projection with claims, evidence, policies, and events
• JSON is the default output; --format feedback prints the same lint-style findings used by hooks

To turn a Veritas artifact into a Surface trust report:

artifact_path="$(npx @kontourai/veritas report --working-tree --format json | node -e 'let data=""; process.stdin.on("data", c => data += c); process.stdin.on("end", () => { const parsed = JSON.parse(data); if (!parsed.artifactPath) throw new Error("missing artifactPath"); console.log(parsed.artifactPath); });')"
surface report --adapter veritas --input "$artifact_path" --format summary

Surface generates report-only fields such as id, generatedAt, summary, faultLines, and proofRequirementsByClaimId. Veritas emits the input evidence; Surface owns the report.

budget

Prints the verification budget without requiring operators to read the full report artifact.

npx @kontourai/veritas budget [--root <path>] [--adapter <path>] [--policy-pack <path>] [--run-id <id>] [file ...]
npx @kontourai/veritas budget --working-tree
npx @kontourai/veritas budget --format feedback --working-tree
npx @kontourai/veritas budget --format json --working-tree

Important behaviors:

• default output is a short human-readable budget summary
• --format json returns verification_budget and proof_family_results
• --format feedback reuses the same lint-style summary as report --format feedback
• the command uses the same adapter, policy-pack, and source-scope flags as report
• malformed declared proof-family manifests fail with the manifest path and family id

shadow run

Runs proof first, then creates a report, then creates an eval draft, and optionally finishes the eval record if the missing judgment fields are supplied.

npx @kontourai/veritas shadow run [--root <path>] [--adapter <path>] [--policy-pack <path>] [--team-profile <path>]
  [--format feedback|json]
  [--proof-command <cmd>] [--skip-proof]
  [--working-tree | --changed-from <ref> --changed-to <ref>]
  [--run-id <id>]
  [--reviewer-confidence <scale-entry|unknown>]
  [--time-to-green-minutes <number>]
  [--override-count <number>]
  [--false-positive-rule <rule-id>]
  [--missed-issue <text>]
  [--note <text>]
  [--accepted-without-major-rewrite <true|false>]
  [--required-followup <true|false>]
  [--force]

If accepted_without_major_rewrite, required_followup, and time_to_green_minutes are not all present, the command stops after report plus draft. Feedback mode prints the report path, eval-draft path, and run id in the footer. JSON mode returns the previous orchestration object with the suggested eval record command.

Proof commands are executed as tokenized argv, not through an implicit shell. Keep each proof lane to one executable plus arguments, or move compound shell logic into a real script.

Exit codes:

• 0: no blocking failures
• 1: proof or blocking policy failure
• 2: config/runtime error

eval draft

Builds a repo-local draft artifact from a repo-local evidence artifact.

npx @kontourai/veritas eval draft --evidence <path> [--team-profile <path>] [--output <path>] [--force]
  [--reviewer-confidence <scale-entry|unknown>]
  [--time-to-green-minutes <number>]
  [--override-count <number>]
  [--false-positive-rule <rule-id>]
  [--missed-issue <text>]
  [--note <text>]

Guardrail:

• evidence input must be under .veritas/evidence/
• the generated draft now includes a derived governance object that records whether the evidence touched the governance surface and whether constitutional review is required

eval record

Completes a live-eval record from either evidence directly or a previously created draft.

npx @kontourai/veritas eval record --evidence <path> [--team-profile <path>] [--output <path>] [--force]
  --accepted-without-major-rewrite <true|false>
  --required-followup <true|false>
  --reviewer-confidence <scale-entry|unknown>
  --time-to-green-minutes <number>
  --override-count <number>

npx @kontourai/veritas eval record --draft <path> [--team-profile <path>] [--output <path>] [--force]
  --accepted-without-major-rewrite <true|false>
  --required-followup <true|false>
  --reviewer-confidence <scale-entry|unknown>
  --time-to-green-minutes <number>
  --override-count <number>

Guardrails:

• evidence input must stay under .veritas/evidence/
• draft input must stay under .veritas/eval-drafts/
• a draft must be completed with the same team profile that created it
• the completed record keeps the same derived governance object so governance-touching evals can be measured later
• existing output is not overwritten without --force

eval marker

Scores a deterministic marker-surfacing benchmark by comparing one without Veritas transcript to one with Veritas transcript against the same benchmark scenario.

npx @kontourai/veritas eval marker \
  --scenario examples/benchmarks/migration-marker-scenario.json \
  --without-veritas-transcript examples/benchmarks/migration-marker-without-veritas.json \
  --with-veritas-transcript examples/benchmarks/migration-marker-with-veritas.json

Important behaviors:

• the command is read-only and prints JSON to stdout
• the scenario defines the required marker phrases and the scoring window
• transcripts must declare the matching benchmark_id plus the expected without-veritas or with-veritas condition id
• transcripts must include a trigger tag, and may include a response-window tag when the tagged assistant turn is the response that must carry the marker
• this command scores one benchmark pair; repeat it across multiple runs when you want pass^k-style evidence, or use marker-suite for the aggregated pass_pow_k metric

eval marker-suite

Scores a suite of marker benchmarks and reports aggregate reliability metrics across multiple scenario groups and trials.

npx @kontourai/veritas eval marker-suite \
  --suite examples/benchmarks/marker-suite.json

Important behaviors:

• the suite artifact references scenario files plus one or more trial transcript pairs per benchmark
• each benchmark_id and trial_id in the suite must be unique
• aggregate metrics include per-trial rates and grouped reliability summaries
• improvement_rate counts trials where Veritas improves outcome quality or delivers the same correct outcome faster
• pass_at_1 is computed from the first listed trial in each benchmark group
• pass_at_k means a benchmark has at least one passing with Veritas trial across its recorded trials
• pass_pow_k is the suite report name for pass^k: every recorded with Veritas trial in a benchmark group passes
• the command validates every referenced scenario and transcript before producing a suite summary

eval summary

Reads .veritas/evals/history.jsonl and prints recent local outcome metrics.

npx @kontourai/veritas eval summary [--root <path>]

The summary includes acceptance count, required rewrites, average time to green, average overrides, confidence distribution, and the most flagged false-positive rule.

print

Print-only helpers return suggested content without changing the repo.

npx @kontourai/veritas print package-scripts [--root <path>] [--proof-lane <cmd>]
npx @kontourai/veritas print ci-snippet [--root <path>] [--proof-lane <cmd>]
npx @kontourai/veritas print git-hook [--root <path>] [--hook post-commit]
npx @kontourai/veritas print runtime-hook [--root <path>]
npx @kontourai/veritas print stop-hook [--root <path>] [--tool generic|claude-code|cursor]
npx @kontourai/veritas print governance-block
npx @kontourai/veritas print codex-hook [--root <path>] [--target-hooks-file <path>] [--codex-home <path>]

Printed helper surfaces:

• suggested package.json scripts
• a CI snippet
• a tracked git hook body
• a tracked runtime hook body
• a generic stop-hook body and thin tool-specific wrapper configs
• the canonical Veritas governance block
• a tracked Codex hooks config plus optional target inspection status

apply

Write the suggested assets into the repo.

npx @kontourai/veritas apply package-scripts [--root <path>] [--proof-lane <cmd>] [--force]
npx @kontourai/veritas apply ci-snippet [--root <path>] [--output <path>] [--proof-lane <cmd>] [--force]
npx @kontourai/veritas apply git-hook [--root <path>] [--hook post-commit] [--output <path>] [--configure-git] [--force]
npx @kontourai/veritas apply runtime-hook [--root <path>] [--output <path>] [--force]
npx @kontourai/veritas apply stop-hook [--root <path>] [--tool generic|claude-code|cursor] [--output <path>] [--force]
npx @kontourai/veritas apply governance-blocks [--root <path>] [--force]
npx @kontourai/veritas apply codex-hook [--root <path>] [--output <path>] [--target-hooks-file <path> | --codex-home <path>] [--force]

Write restrictions are intentional:

• CI snippets must stay under .veritas/snippets/
• runtime hooks must stay under .veritas/hooks/
• stop hooks must stay under .veritas/hooks/
• Codex hook artifacts must stay under .veritas/runtime/
• eval artifacts must stay under .veritas/evals/
• git hooks must stay under .githooks/

runtime status

Inspects the installed state of the tracked adapter surfaces.

npx @kontourai/veritas runtime status [--root <path>] [--target-hooks-file <path>] [--codex-home <path>]

It reports:

• whether .githooks/post-commit exists and is executable
• whether core.hooksPath points at .githooks
• whether .veritas/hooks/agent-runtime.sh exists and is executable
• whether .veritas/runtime/codex-hooks.json exists
• whether the target Codex hooks file already contains the adapter command
• the next repair or install commands to run

Generated Hook Behavior

print git-hook and apply git-hook produce a post-commit hook that:

• skips itself when VERITAS_HOOK_SKIP=1
• also honors legacy AI_GUIDANCE_HOOK_SKIP=1
• compares HEAD~1..HEAD on normal commits
• uses the empty tree for the first commit
• calls veritas shadow run

print runtime-hook and apply runtime-hook produce a shell wrapper that:

• skips itself when VERITAS_HOOK_SKIP=1
• also honors legacy AI_GUIDANCE_HOOK_SKIP=1
• defaults to veritas shadow run --format json --working-tree
• forwards any explicit arguments through to shadow run --format json

print stop-hook and apply stop-hook produce .veritas/hooks/stop.sh, which:

• skips itself when VERITAS_HOOK_SKIP=1
• runs veritas shadow run --format feedback --working-tree
• prints failures back to the agent
• exits 0 so the AI session can continue and repair the findings

print codex-hook and apply codex-hook produce a tracked Codex config that installs the runtime hook as a Stop hook.

Environment Variables

• VERITAS_HOOK_SKIP=1: skips generated git/runtime hook execution
• AI_GUIDANCE_HOOK_SKIP=1: legacy alias still honored by generated hooks

Do not set either skip variable in CI if the CI lane is meant to enforce proof execution.

Output Shape

The exact JSON varies by command, but the operator-facing contract is stable:

• print/apply commands return machine-readable status objects
• report returns artifactPath, markdownSummary, and the full evidence record including policy_results
• eval draft returns artifactPath, suggestedRecordCommand, markdownSummary, and the full draft record
• eval record returns artifactPath, historyPath, markdownSummary, and the full eval record
• eval summary returns a plain-text local history summary
• eval marker returns a benchmark comparison object with per-condition timing, false-positive, and pass results
• eval marker-suite returns a suite report with per-benchmark rollups and aggregate reliability metrics
• shadow run defaults to feedback text; --format json returns orchestration status plus the artifact paths it created

For the artifact fields themselves, see Artifacts and Schemas.