CLI Reference
Both nova and novafabric refer to the same binary. NovaFabric is a
self-hosted, Apache-2.0 command-line toolkit that captures, replays, diffs,
and audits AI-agent and model runs. Every command works locally, without a
server, without accounts, and without network access to any NovaFabric-operated
service.
Reference pages
- nova capture, setup and adapter commands — Reference for nova init and nova capture: wrap a command without code changes, API and MCP proxies, framework adapters, the warm daemon, distributed runs.
- nova replay, diff and diagnose commands — Reference for nova replay and its modes, nova diff between two run capsules, and nova diagnose, which attributes a failed run to its most likely step.
- Offline query, search and drift commands — Reference for offline analysis over local run capsules: nova query, view and trend metrics, full-text nova search, and drift and replay-equivalence checks.
- Lineage and execution-graph commands — Reference for nova lineage (provenance, blast radius, replay chain), nova graph agent, lineage-store migration and metadata database recovery.
- Trust, secret-scan and assurance commands — Reference for trust-layer commands: nova scan-secrets, nova assure, nova redact, annotations and scores, and read-only trust and assurance views.
- Registry, prompt and promotion commands — Reference for the asset registry: nova register, promote and rollback, prompt versions, deployment labels and two-person maker-checker sealing.
- Compliance and audit export commands — Reference for evidence exports (EU AI Act Annex IV, NIS2, NIST AI RMF, sector reports), nova audit, nova classify and examiner archives.
- Incident forensics, DSAR and event commands — Reference for nova forensics timeline, nova dsar for subject-rights requests, and opt-in lifecycle events and webhooks with nova events.
- Policy, approval and retention commands — Reference for nova policy (Rego tests and decision explanations), approvals and legal holds, and the audited retention scheduler, nova retention.
- Server, storage and backup commands — Reference for nova doctor, capsule ingest and migrations, signed backups with verified restore, support bundles, and audit-log export for SIEM tools.
- Dashboard commands — Reference for nova dashboard (widgets and dashboards as portable JSON files) and nova serve --experimental, the experimental local web dashboard.
- Collector binaries and HPC runners — Reference for the Go collector tier (novafabric-collector, verifier and HPC hub, built from source), Slurm integration, and the PBS and LSF runners.
- Evidence Fabric: schema, cost and storage commands — Reference for Evidence Fabric v1.0 commands: nova schema, cost estimates and attribution, pricing tables, storage inspection and capture-level policy.
- nova kg: the capsule knowledge graph — Reference for nova kg, the capsule knowledge graph over local run capsules: initialising, ingesting, building provenance and running detections.
- MCP supply-chain risk scanner (nova mcp) — Reference for nova mcp: OWASP LLM Top 10 supply-chain checks for MCP server manifests, risk reports, server cards and conformance checks.
- Accountability spine and energy commands — Reference for the experimental accountability spine: LlamaIndex, Pydantic AI and Haystack adapters, and the nova energy probe, attest and verify commands.
- Environment variables — The environment variables NovaFabric reads, with defaults: home and capsule paths, object storage, the distributed-run contract and capture settings.
What you will learn
This page is the complete reference for the nova CLI: every command, every
flag, every exit code, and the environment variables that configure them. It is
organized around the five NovaFabric primitives, so you can find the command by
knowing what you are trying to do:
- Capture a run into a portable, secret-scanned Run Capsule — see Capture commands.
- Replay that capsule in one of five modes, or diff two runs as a CI gate — see Replay commands.
- Trace Lineage (provenance, blast-radius, replay-chain, time-travel) and emit OpenLineage — see Lineage commands.
- Build a signed Evidence Bundle an auditor can verify offline with only
sha256sumand an ed25519 verifier — see Trust layer commands. - Manage the Asset Registry and its eval-gated, maker-checker promotion lifecycle — see Registry commands and Policy and governance.
Getting the help you need at the terminal
Every command self-documents. When a detail here is ambiguous, the terminal is the source of truth:
nova --help # top-level command list
nova capture --help # any sub-command's flags, defaults, and examples
nova <group> <cmd> --help
nova --version # installed NovaFabric version
nova --install-completion # shell tab-completion for commands, flags, and enumsMaturity legend
NovaFabric has shipped v0.1–v0.9 (and point releases beyond). Most surfaces are experimental in the sense that they work today and are covered by tests, but their interfaces may change before the v1.0 on-disk schema freeze. This reference labels each capability so you never mistake intent for implementation:
| Label | Meaning |
|---|---|
| works today | Implemented in main; tests pass; usable now |
| experimental | Implemented and tested, but the interface may change before v1.0 |
| planned / future | Documented design intent only — not implemented. Never invoke as if it exists. |
A handful of sections below describe planned cluster-scale surfaces (for example, the NovaSeal signing service and the live topology dashboard). They are included so the reference is complete about direction, and are marked accordingly. Local capture, replay, diff, lineage, and Evidence Bundles never require any of them.
Command index
Commands grouped by primitive and task. Each entry links to its full section.
Capture and proxies
| Command | Purpose |
|---|---|
nova init |
Set up a local installation and signing keypair |
nova capture |
Wrap any command; record it as a Run Capsule |
nova session |
Group N independent runs into one multi-turn session: new, add, list, reindex, show, export/verify-bundle/import (experimental); replay them in order, whole or a --from/--to slice (experimental, ADR-0123) |
nova validate |
Validate a capsule or an asset spec |
nova api-proxy |
Transparent LLM API proxy for non-Python clients |
nova mcp-proxy |
Transparent MCP stdio capture proxy |
nova suggest-register |
Suggest assets to register from captured evidence |
Replay, diff, and diagnose
| Command | Purpose |
|---|---|
nova replay |
Inspect or re-run a capsule (forensic / mocked / semantic / exact; intervention experimental) |
nova diff |
Structurally compare two capsules; CI regression gate |
nova diagnose |
Attribute a failed run to its responsible step |
nova query |
Aggregate metrics across local capsules, offline (experimental) |
nova search |
Full-text search over redacted capsule content (experimental) |
nova view |
Saved views: save, list, show, run, delete named query definitions (experimental) |
nova trend |
Score/cost/latency trend report over local capsules: JSON + optional static HTML (experimental) |
nova cost estimate |
Offline per-capsule cost: recorded vs catalog-estimated (experimental) |
nova cost attribute |
Attribute recorded spend to productive vs wasted outcomes — descriptive (experimental) |
nova cost fairness |
Per-agent cost/energy/calls fairness ledger: share, Gini, max/mean — descriptive (experimental) |
nova cost rollup |
Roll per-agent cost up the acted-as delegation chain: self/subtree cost + exact conservation — report-only (experimental) |
nova cost usage-breakdown |
Token usage-type composition of a capsule — descriptive (experimental) |
nova pricing |
Local model-pricing catalog: list, show, add (experimental) |
nova drift |
Collects samples from sealed capsules, then runs the offline drift, silent-failure, root-cause and behavioral-fingerprint detectors over them (experimental) |
nova capture-ui |
Computer-use GUI actions and observations; typed text is a salted digest, never raw (experimental) |
nova provenance |
Bind C2PA manifests to captured media hashes; read watermark-presence claims (experimental) |
nova toolschema impact |
Which historical runs break under a new tool schema (experimental) |
Lineage
| Command | Purpose |
|---|---|
nova lineage provenance |
What a node depends on (forward) |
nova lineage blast-radius |
What depends on a node (backward) |
nova lineage replay-chain |
Trace a run back to its original capture |
nova lineage time-travel |
Lineage state as of a timestamp |
nova lineage emit-openlineage |
Emit OpenLineage 2.0.2 events |
nova lineage metrics |
Hubs + single points of failure (experimental, ADR-0212) |
nova lineage root-cause |
Rank upstream root-cause suspects (experimental, ADR-0213) |
nova lineage export-graph |
GraphML/GEXF/Cypher export (experimental, ADR-0214) |
nova lineage consume |
Run the NATS JetStream LineageConsumer daemon (experimental, cluster-scale, ADR-0061/0066/0219) |
nova insights |
Synthesized graph-intelligence report (experimental, ADR-0215) |
nova graph agent |
Reconstruct one run's execution DAG from its capsule (experimental) |
Trust layer and evidence
| Command | Purpose |
|---|---|
nova scan-secrets |
Report secrets/PII in a capsule's redaction proof |
nova redact |
Re-scan and update a capsule's redaction proof |
nova export-evidence |
Build a signed Evidence Bundle ZIP |
nova export --html |
Shareable single-file offline HTML capsule viewer (experimental) |
nova verify-envelope |
Verify a DSSE envelope's Ed25519 signature |
nova assure |
OWASP LLM Top 10 evidence checks |
nova verify |
Verify a capsule's NovaSeal seal (experimental) |
nova export-blob |
Batch capsule export with a signed completeness manifest (experimental) |
nova import |
Verified batch import of a blob export — DR restore, air-gap transfer, migration (experimental) |
nova comment |
Append-only human annotations on capsule evidence |
nova annotate |
Human annotation queues — route subjects to reviewers, emit HUMAN scores |
nova score submit |
Submit an externally-computed score into a capsule's append-only scores.jsonl |
nova merkle-tree |
Render an Evidence Provenance Merkle proof tree from a sealed capsule's hashes (experimental) |
nova trust-radar |
Trust Attestation Radar over a capsule's verification output (experimental) |
nova trust-path |
Show / offline-verify a transitive cross-org trust path against anchors you pin (experimental, NF-363) |
nova redaction-xray |
Redaction / secret-scan X-Ray of a capsule's protection metadata (experimental) |
nova assure-case |
Inspect an assurance-case document: validity, currency, conformance, defeaters (experimental) |
nova assure-coverage |
Structural coverage of an assurance case — counts and gaps, never a grade (experimental) |
nova passport |
Portable agent passport: issue + offline verify (experimental) |
nova embodied |
Embodied-agent evidence: ODD record (verdict always null) + perception→actuation trajectory chain verify, offline (experimental); sim2real show/verify, teleop list, timing show (P3) |
nova hitl |
Human-agent accountability: conversation thread, decision-context receipt re-check, overrides, surfaced rationale; handoffs and acted-on-behalf bindings — read-only (experimental) |
nova consent |
ISO/IEC TS 27560-shaped consent receipts: record into a capsule, record a withdrawal, show, offline re-check — never asserts legal validity (experimental) |
nova memstore |
Shared-store governance evidence: access ledger (contained:false = evidence, not enforcement), cross-run read → seeding-write back-trace, source → write → runs fan-out — offline over explicit capsules (experimental) |
Registry, promotion, and evaluation
| Command | Purpose |
|---|---|
nova register / nova list / nova inspect |
Register and browse assets |
nova promote |
Direct or maker-checker promotion through the lifecycle |
nova rollback / nova unregister |
Roll back or remove asset versions |
nova prompt |
Immutable, content-addressed prompt versions: register, get, list, history, diff + composition: compose, tree (experimental) |
nova label |
Deployment labels: movable named pointers to immutable asset versions; protected labels move via maker-checker (experimental) |
nova eval |
Run and compare evaluation suites |
nova experiment |
Dataset-experiment harness: per-item runs + A/B regression gate (experimental) |
nova approve |
Approve a pending_approval asset |
Compliance and governance exports
| Command | Regulation |
|---|---|
nova export-annex-iv |
EU AI Act Annex IV |
nova export-nis2 |
NIS2 Directive Art. 23 |
nova export-ropa |
GDPR Art. 30 RoPA |
nova export-nist-rmf |
NIST AI RMF 1.0 |
nova classify run |
EU AI Act / NIST RMF / OMB risk tier |
nova audit map / nova audit report |
Multi-profile control coverage |
nova retention |
WORM-aware, audited retention sweep (plan/apply/status/explain) |
nova forensics timeline |
Incident forensic timeline over sealed evidence (experimental) |
nova dsar |
Subject-rights (DSAR) package assembly + SLA clock (experimental) |
| Sector & transparency exports | 13 nova export-* renderers (experimental): SR 11-7 model risk, 21 CFR Part 11, RAI scorecard, EU AI Act Annex VIII, algorithm registers, public-sector disclosure, FOIA, whistleblower, citizen explanation, public incident, election disclosure, accessibility claim, control attestation |
The compliance surfaces above produce evidence that supports compliance workflows. They do not certify or guarantee compliance with any regulation. See the disclaimers on each command.
Provenance marking — evidence_source (ADR-0197, experimental)
Field-group–structured exporters (export-annex-iv, export-nis2, and the
incident-store AIM/DORA projections) tag every field-group with an
evidence_source marker so a regulated consumer can tell how NovaFabric
established each value — never blurring an operator assertion into a
capsule-verified fact:
| Value | Meaning |
|---|---|
operator_asserted |
The value came from operator-authored input; NovaFabric did not check it. |
capsule_verified |
NovaFabric resolved this from a capsule and re-performed the binding. Carries an evidence_ref (capsule_id + content_digest [+ optional seal_envelope_path]) a third party can re-check offline. |
unverifiable |
NovaFabric attempted verification and could not complete it (missing capsule, unresolvable digest, absent seal) — reported, never downgraded to an assertion. |
The marker is additive and optional on the wire (a pre-ADR-0197 document
deserializes with evidence_source: null). As of v0.66.0 it is applied across
the whole compliance-export layer — the field-group exporters (v0.65.0) plus
all thirteen pure-projection families (Part 11, SR 11-7 model risk, DSAR, FOIA,
whistleblower, transparency register, Annex VIII, public-sector disclosure, RAI
scorecard, control attestation, citizen explanation, accessibility claim,
election/public-incident disclosure). Each pure projection is operator_asserted
with checked gaps marked unverifiable; a supplied capsule ref is never reported
as capsule_verified until a collector actually re-performs the sealed binding.
Status: experimental.
Lifecycle events (experimental)
| Command | Purpose |
|---|---|
nova events tail |
Read the local append-only lifecycle-event log |
nova events emit |
Manually emit a lifecycle event (test a wired CI hook) |
Server mode and storage
| Command | Purpose |
|---|---|
nova dashboard |
Manage dashboards and widgets as portable JSON files (ADR-0235) |
nova serve --experimental |
Local dashboard (loopback, single-user; not read-only — Layer B mutations ship) |
nova server start |
Multi-user REST API (Postgres/SQLite, OIDC, RBAC) |
nova server saml-metadata |
Emit the SAML SP metadata XML for IdP registration (experimental) |
nova server scim-map-group |
Declare IdP-group → RBAC-role mappings for SCIM provisioning (experimental) |
nova server list-scim-events |
Read-only SCIM provisioning audit trail (experimental) |
nova server api-key |
First-class API keys: create, list, revoke, rotate (experimental) |
nova server usage |
Usage-ledger drift reconciliation and chargeback CSV/NDJSON export (experimental) |
nova login / nova logout |
Log in through a server's demo device grant (testing only) / remove stored credentials |
nova doctor |
Installation, storage, scheduler/env-var, and token-at-rest diagnostics |
nova migrate-to-postgres |
Migrate the local SQLite registry to Postgres |
nova migrate-format |
Record a format-migration hop in a preservation facet; verify the chain offline (experimental) |
nova preservation |
Record/verify crypto re-seal events and LTV timestamp-renewal chains in a preservation facet (experimental, record-only) |
nova settlement |
Walk the A2A payment-provenance chain in a settlement facet offline (experimental, record-only; moves no money) |
nova backup / nova restore |
Evidence-grade backup sets: create, verify offline, restore (local + automated pg restore, experimental) |
nova support-bundle |
Secret-safe diagnostics tarball for support (experimental) |
nova audit-log |
Export local audit logs for SIEM ingestion (OCSF / CEF / native JSONL, experimental) |
For everything else — the knowledge graph, energy receipts, the accountability ledger, HPC collector binaries, and the full environment-variable table — use your browser's find, or jump to Environment variables.
Summary and next steps
The nova CLI is a complete, self-hosted toolkit: capture a run, replay it,
diff two runs, trace lineage, and export signed evidence — all locally, offline,
with no accounts. A typical first pass through the five primitives looks like:
# 1. Capture — turn any command into a Run Capsule
nova capture python agent.py
# 2. Validate — confirm the capsule is schema-valid
nova validate .novafabric/runs/<ulid>/
# 3. Replay — re-run against the recorded LLM/tool calls (default: mocked)
nova replay .novafabric/runs/<ulid>/
# 4. Diff — structurally compare two runs; fail CI on any regression
nova diff .novafabric/runs/<ulid-a>/ .novafabric/runs/<ulid-b>/ --assert-no-regressions
# 5. Trace — see what a run consumed and what it would impact
nova lineage provenance <ulid>
nova lineage blast-radius <ulid>
# 6. Prove — build a signed Evidence Bundle an auditor can verify offline
nova export-evidence ~/.novafabric/capsules/<ulid>/ --key ~/.novafabric/keys/signing_key.pem \
--output evidence.zipThe resulting evidence.zip verifies with only sha256sum and an ed25519
verifier — no NovaFabric runtime required. The vendored schemas make it a time
capsule: it still verifies years later against the same schemas it was built
with.
Where to go from here
- Concepts and the five-primitive model — see the project README and
docs/guides. - Writing a capture hook plugin —
docs/integrations/writing-a-hook-plugin.md. - NovaSeal configuration (signature + RFC 3161 timestamp + Merkle log) —
docs/novaseal-configuration.md. - Server deployment (Postgres, OIDC, RBAC) —
docs/ops/server-deployment.md. - Dashboard capabilities and CLI-parity matrix —
docs/dashboard.md.
A note on what is planned versus shipped
Several sections above (the NovaSeal signing service, the cluster-scale collector binaries, parent/child capsules, the production RLS MetadataStore, the object capsule store, lineage-at-scale, and the live topology dashboard) describe planned or experimental cluster-scale direction. They are documented here for completeness, but the local-first core — capture, validate, replay, diff, lineage, signed Evidence Bundles, the SQLite registry, and OPA/Rego promotion gates — is what works today and never depends on any of them.
When in doubt, run nova <command> --help: the terminal is always the
authoritative description of the installed version.