K-Veritas CLI Documentation

K-Veritas CLI

Single static binary for Linux, macOS, and Windows. Zero runtime dependencies. Monitors experiments, captures metrics, and seals signed PDF reports.

Attestation Server

Hosted at kveritas-api-production.up.railway.app. The CLI connects to it automatically. No local server setup needed.

Install

Download and install in one command.

Linux / macOS

curl -fsSL https://github.com/27-GROUP/kveritas-releases/raw/main/bin/kveritas-linux-amd64 -o kveritas
chmod +x kveritas
sudo mv kveritas /usr/local/bin/

Windows (PowerShell)

Invoke-WebRequest -Uri "https://github.com/27-GROUP/kveritas-releases/raw/main/bin/kveritas-windows-amd64.exe" -OutFile "kveritas.exe"

See the Download page for all platforms (ARM64, Apple Silicon) and architecture-specific binaries.

Usage

Three commands to go from experiment to signed report.

# 1. Initialize a session (connects to hosted attestation server)
kveritas init

# 2. Run your experiment under kveritas
kveritas run -- python train.py --epochs 50

# 3. Seal the session into a signed PDF
kveritas seal --output report.pdf

Metric Capture

The CLI captures metrics from stdout in any language. Print the format below from your training script and K-Veritas records it automatically.

# Format:
KVERITAS_METRIC name=<id> value=<float> [step=<label>]

# Python example:
print(f"KVERITAS_METRIC name=accuracy value={acc:.4f}")

# Bash example:
echo "KVERITAS_METRIC name=loss value=0.24"

# R example:
cat(sprintf("KVERITAS_METRIC name=rmse value=%f", rmse))

The CLI also applies heuristic parsing for common output formats (e.g. "accuracy: 0.95", "loss = 0.24").

Protocol Lines

Beyond metrics, K-Veritas recognizes three additional protocol lines that enrich the signed record.

# Phase boundaries (hardware snapshot at each boundary)
KVERITAS_PHASE training
KVERITAS_PHASE evaluation

# Inline claims (committed to hash at specific line)
KVERITAS_CLAIM accuracy >= 0.95
KVERITAS_CLAIM loss < 0.1

# Seed commitments (prove seed was declared before results)
KVERITAS_INPUT src=seed:42

Phases capture hardware counters (CPU, memory, GPU) at each boundary. Claims and seeds are included in the signed data for independent verification.

Hardware Analysis (HMCA)

The CLI runs a Hardware-Metric Consistency Analyzer at seal time. HMCA applies deterministic rules to detect implausible results: zero-cost metrics, low-activity high-gain, GPU claims on CPU-only machines, idle runs, and phase mismatches. The HMCA score (0-100%), verdict (PASS/WARN/FAIL), and triggered flags are baked into the signed record.

Verification

Verify any K-Veritas report locally or on the web.

# Local verification (no internet needed)
kveritas verify report.pdf

# Cross-reference claims from a paper
kveritas generate-claims --report report.pdf > claims.json
kveritas check --claims claims.json --report report.pdf

Reports can also be verified at kveritas.org/verify, where you can upload the report PDF, source bundle ZIP, and manuscript PDF for a full AI-powered audit including code analysis and paper crosscheck.

Session Lifecycle

Each session tracks one or more experiment runs. Failed runs (non-zero exit code) are automatically excluded from the signed report. After sealing, the session cache is cleaned up.

kveritas init                          # start session
kveritas run -- python train.py        # run 1 (succeeds)
kveritas run -- python broken.py       # run 2 (fails, excluded)
kveritas seal --output report.pdf      # seal (only run 1 included)
# Session cache is automatically deleted after seal
kveritas clean                         # manual cleanup if needed