Commands¶
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>).
| 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.
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:
shell¶
Your terminal, recorded: every command is a run. Linux and macOS, bash 4.4+ or zsh. See Recorded shell.
autolog¶
Find results in output and metric files when a run prints no KV lines. No argument: show the setting. See Autolog.
checkpoint¶
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¶
Put the files back. Newer files are left alone. Unsaved changes are first kept in an automatic checkpoint.
branch¶
No name: list branches. With a name: start it, or switch to it.
set-aside¶
Move a run out of the main results. It stays in the report. --undo brings it back.
log¶
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¶
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.
| 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¶
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¶
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¶
| 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¶
| 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¶
Compares a claims file with the report. See Extra checks.
generate-claims¶
Makes a claims file template from a report.
Sharing files¶
prove¶
| 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¶
checkout¶
| Flag | |
|---|---|
--report |
First check the bundle matches the report. |
AI agents¶
agent¶
Record any agent from outside. Starts an agent session if none (Linux).
| 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.
| 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¶
| 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¶
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. |