Skip to content

Commands

kveritas <command> [flags]
kveritas <command> --help

Basics

init

Start a session in the project folder. Only needed to change options: run starts one for you. One open session per machine: refused while another is open (seal it, or kveritas clean <id>).

kveritas init [flags]
Flag Default
--disclosure redacted redacted, names, or open.
--show-names Same as --disclosure names.
--local Sign locally, no server. Report shows SELF-ATTESTED.
--server K-Veritas server Use another signing server.
--harness Record an agent session.
--agent unknown-agent Name of the agent (agent sessions).
--operator current user Who runs the agent (agent sessions).
--designate all important actions File listing which agent actions to record.
--no-hooks Agent sessions: don't install Claude Code hooks.
--autolog Find results when a run prints no KV lines.

run

Run a command.

kveritas run [flags] -- <command> [args...]
kveritas <command> [args...]          # same, for any program on PATH
Flag
--seal [path] After the run, sign and write the report. Default report.pdf.
--files Extra files to hash before and after the run, comma separated.
--node-rank This machine's node in a multi-node run. Default: from the launcher or Slurm.

Multi-node: same command on every node.

srun kveritas run -- torchrun --nnodes=2 --nproc_per_node=4 ... train.py

Node 0 records the run. Other nodes measure themselves and hand their record over through the project folder, which must be shared.

Notebook, start to end:

kveritas jupyter nbconvert --to notebook --execute analysis.ipynb

shell

Your terminal, recorded: every command is a run. Linux and macOS, bash 4.4+ or zsh. See Recorded shell.

kveritas shell

autolog

kveritas autolog [on|off]

Find results in output and metric files when a run prints no KV lines. No argument: show the setting. See Autolog.

checkpoint

kveritas checkpoint [-m message] [--files f1,f2]

Save every project file as a point to come back to, like git add -A (data and weights included). Left out: caches, virtual environments, .gitignore'd paths. Copies stay on this machine; only a salted fingerprint goes to the server. See Checkpoints and branches.

Flag
-m, --message What this point is.
--files Also save these, even if ignored.

restore

kveritas restore <checkpoint>

Put the files back. Newer files are left alone. Unsaved changes are first kept in an automatic checkpoint.

branch

kveritas branch [name]

No name: list branches. With a name: start it, or switch to it.

set-aside

kveritas set-aside <run> [-m reason] [--undo]

Move a run out of the main results. It stays in the report. --undo brings it back.

log

kveritas log [-v]

The session as a tree, newest first. @ is where you are, x a failed run. -v shows every result and changed file.

  @  226388bf  2 minutes ago  run  41.2 seconds  dropout*
  │  python train.py  acc=0.86 loss=0.39
  │
  o  a40f0394  3 minutes ago  branch
╭─╯  started dropout from main
│
o  2b858404  Today at 14:02  run  40.8 seconds  main
│  python train.py  acc=0.85 loss=0.4
│
o  5f685eca  Today at 13:40  checkpoint
   "baseline"  1 file

One entry per run or step. Branch names at their newest entry (* marks yours). NO_COLOR=1 turns colors off.

web

kveritas web [--port 7701] [--no-open]

The history in your browser, on 127.0.0.1 with a secret link. Same actions as the commands above. --no-open prints the link only.

seal

Write the signed report.

kveritas seal [-o report.pdf]
Flag Default
-o, --output kveritas-report-<id>.pdf Where to save the report. Agent sessions: kveritas-session-<id>.pdf, or a .json name for the log alone.
--local-key Sign with your own key file, offline.
--claim Claim a result at its latest value. Repeat or comma separate.
--json Print the result as JSON.

Refuses if the code changed since the latest run (re-run or restore first). Waits up to 30 s for runs not yet on the server, then refuses until they arrive.

status

kveritas status [-v]
dropout*  based on 4686f85a "baseline"
M train.py
A eval.py

session de23b10f · open · 7 runs · 1 set aside

Branch and base checkpoint, changed files (M modified, A added, R removed), then a session summary. -v adds session details and every run. --json for JSON.

clean

kveritas clean [session-id]

Removes the session completely: its .kveritas folder and its data on the server (only bare hashes stay in the ledger). No report lists it. Offline, the folder is still removed; run kveritas clean <id> later to tell the server. With an id (8 characters are enough): a session whose folder is gone.

key

kveritas key
kveritas key link [code]
kveritas key revoke [fingerprint]
kveritas key export
Command
key This machine's signer key and its sessions.
key link New machine: get a code.
key link <code> Machine with your history: join the new machine to it.
key revoke <fingerprint> Revoke a linked key (lost machine). 16 characters are enough.
key revoke Replace this machine's key. History kept, old key revoked.
key export Print the key, for the KVERITAS_SIGNER_KEY secret in CI.

key, clean: --server for another signing server.

Checking

verify

kveritas verify <report.pdf | session.pdf | proof.json> [flags]
Flag Default
--bundle Checkout bundle (.kvbundle.zip): checks it matches, then runs the AI code audit.
--paper Paper PDF: checks its numbers against the report.
--offline Local checks only, no server.
--public-key K-Veritas keys Trust another signing key.
--server https://kveritas.org Server to check with.
--json Print the result as JSON.

Result: VERIFIED (signed by K-Veritas), SELF-ATTESTED (valid signature, other key), TAMPERED (contents changed) or INVALID (bad signature). The AI audit and paper check are advisory, not part of the signature check.

check

kveritas check --claims claims.json --report report.pdf

Compares a claims file with the report. See Extra checks.

generate-claims

kveritas generate-claims --report report.pdf > claims.json

Makes a claims file template from a report.

Sharing files

prove

kveritas prove <report.pdf> <file> [file...] [flags]
Flag Default
-o, --output kveritas-proof.json Where to save the proof.
--project current folder Folder holding the files.

Needs report.pdf.provkey.json next to the report.

verify-proof

kveritas verify-proof <proof.json>
kveritas verify-proof <report.pdf> <proof.json>

checkout

kveritas checkout <bundle.zip> <[run:]phase | index> <outdir> [--report report.pdf]
Flag
--report First check the bundle matches the report.

AI agents

agent

Record any agent from outside. Starts an agent session if none (Linux).

kveritas agent [flags] -- <command> [args...]
Flag Default
--reads true Record names of files read in the project and home folder.
--hooks Also install Claude Code hooks (labels).
--disclosure redacted redacted, names, or open.
--agent command name Name of the agent.
--local Sign locally. Report shows SELF-ATTESTED.
--server K-Veritas server Use another signing server.

Processes still running 3 s after the agent exits are stopped. Setuid programs (sudo) do not gain privileges inside.

record

Record one agent action. Usually called by hooks.

kveritas record --type <type> [flags]
Flag Default
--type tool_call, file_effect, model_turn, spawn, self_claim.
--actor agent Which agent acted.
--parent The agent that started it, for sub-agents.
--input, --input-file What went in. Only its fingerprint is kept.
--output, --output-file What came out. Only its fingerprint is kept.
--hook Claude Code hook mode: pre, post, prompt (payload on stdin).
--json Print the entry as JSON.

harness-prove

kveritas harness-prove <session.pdf> <index | --tool-use-id ID> [flags]
Flag Default
--input File with the prompt to reveal.
--output-content File with the answer to reveal.
--tool-use-id Pick the entry by its tool call ID.
-o, --out harness-proof-<index>.json Where to save the proof.

verify-harness-proof

kveritas verify-harness-proof <proof.json>

More

Command
kveritas update Get the latest version.
kveritas version [--json] Show the version.
kveritas hardware [--json] Show the CPU, memory and GPUs detected (NVIDIA, AMD, Apple).
kveritas completion <shell> Tab completion for your shell.
kveritas help [command] Help.