CLI Reference

CLI Reference

Every ironvise subcommand and flag in 0.8.0. From a clone, run cargo run -p ectoledger -- <subcommand>; with an installed binary, ironvise <subcommand>. ironvise <subcommand> --help prints the same information. The full reference with background is docs/guides/cli.md.

Support status. Commands marked preview work but sit outside the 0.8 support contract: their behaviour and output may change without a deprecation period. prove-audit is unavailable in 0.8. Everything else is supported.

Overview

Command	What it does	Status
serve	Start the Observer dashboard and REST API	supported
health	Probe the local Observer	supported
audit	Run an agent audit through the cognitive loop	supported
report	Export a report or .elc certificate	supported
verify-session	Verify one session's chain and signatures	supported
verify-ledger	Read-only survey of every session	supported
verify-certificate	Verify an .elc certificate offline	supported
data-receipts	List receipts or check files against them	supported
issuer-key	Manage the installation's certificate issuer key	supported
hook	Claude Code, Codex and Antigravity CLI hook	supported
mcp-proxy	Enforcing proxy for a stdio MCP server	supported
proxy	OpenAI-compatible recording proxy	supported
import-openshell	Signed receipts for NVIDIA OpenShell decisions	supported
webhook-key	Print one receiver's webhook signing key	supported
replay	Replay a session	supported
verify-vc	Verify a W3C VC-JWT	preview
anchor-session	OpenTimestamps timestamp for a session	preview
orchestrate	Multi-agent audit (PostgreSQL)	preview
diff-audit	Compare two sessions (PostgreSQL)	preview
red-team	Adversarial defence testing (PostgreSQL)	preview
prove-audit	Withdrawn; explains why	unavailable

Global flags: --version / -V prints the version (ironvise 0.8.0); --help / -h prints usage.

serve

ironvise serve
ironvise serve --verify-full   # verify the whole chain from genesis at startup (default: last 1000 events)

Prints an access token; open http://localhost:3000?token=<token>. API calls use Authorization: Bearer <token>. Binds to 127.0.0.1:3000 unless ECTO_BIND_HOST / ECTO_BIND_PORT say otherwise.

health

ironvise health

Exits 0 when GET http://127.0.0.1:$ECTO_BIND_PORT/api/status (port 3000 if unset) returns 200, otherwise 1. Used by the container health check.

audit

ironvise audit "Read server_config.txt"
ironvise audit "Audit Cargo.toml dependencies" --policy crates/host/policies/soc2-audit.toml
ironvise audit "Run nmap scan" --policy gate_policy.toml --interactive
ironvise audit "Full-chain audit" --verify-full
ironvise audit "..." --key-password-fd 3  3< <(pass show ironvise)
ironvise audit "Quick read" --no-guard --no-guard-confirmed   # development only

Flag	Effect
--policy <FILE>	Apply a TOML policy
--interactive	Answer approval gates on the terminal instead of the dashboard
--verify-full	Verify the whole chain from genesis before running
--key-password-fd <FD>	Read the session key password from a file descriptor (Unix). Without it, audit asks on the terminal, or saves no key when stdin is not a terminal.
--no-guard with --no-guard-confirmed	Disable the semantic guard. Both are required.

report

ironvise report <session_id> --format sarif --output report.sarif
ironvise report <session_id> --format certificate --output audit.elc
ironvise report <session_id> --format certificate --no-ots --output audit.elc

Flag	Effect
--format	json (default), sarif, html, certificate, github_actions, gitlab_codequality
--output, -o	Output file
--no-ots	Do not submit the tip hash to OpenTimestamps
--key-password-fd <FD>	Password for the session key, to sign the certificate

Exits 1 when any finding is high or critical, so it works as a CI gate. A certificate is signed when the session has a saved key and its password is supplied (--key-password-fd, ECTO_KEY_PASSWORD or the prompt).

verify-session

ironvise verify-session <session_id>
ironvise verify-session <session_id> --against audit.elc --expected-key <hex from the issuer>

Recomputes each event's hash and verifies each signature. Fails on the first bad event and says what went wrong (altered after signing, or signature does not verify). --against compares the session with a certificate you kept, which also catches removed events behind a rewritten seal and a session re-signed with another key. --expected-key requires --against.

verify-ledger

ironvise verify-ledger            # only the failures
ironvise verify-ledger --all      # every session
ironvise verify-ledger --strict   # exit 1 if any session fails

Never writes and opens the ledger read-only. Exit 0 by default whatever it finds, 1 with --strict when a session fails, 2 when the survey cannot run at all. Run it after upgrading: 0.8.0 verification is stricter than earlier releases.

verify-certificate

ironvise verify-certificate audit.elc
verify-cert --strict --expected-key <hex> audit.elc

verify-cert is the standalone binary with the same checks and flags. See Verification and Certificates for what each mode proves.

Flag	Effect
--strict	Require a signature that verifies
--expected-key <hex>	Require the signature to be by this Ed25519 key; implies --strict
--issuer <hex>	Require a countersignature by this installation issuer key
--require-anchor	Require a Bitcoin attestation in the OpenTimestamps stamp
--export-ots <FILE>	Write the stamp as a standard .ots file
--ots <FILE>	Read the stamp from an upgraded .ots file instead

data-receipts

ironvise data-receipts <session_id>                     # list the receipts
ironvise data-receipts <session_id> --file config.ini   # check a file (repeatable)

Exits 1 when a file matches no receipt, and refuses a session that does not verify.

issuer-key

ironvise issuer-key init             # create it and print its public key
ironvise issuer-key show             # print the public key
ironvise issuer-key init --replace   # make a new one

Stored as issuer.key in ECTO_DATA_DIR, owner-only. Every exported certificate is countersigned by it. Replacing it does not invalidate certificates it already signed.

hook

ironvise hook install [--shared | --user] [--codex | --antigravity] [--project DIR] [--command CMD]
ironvise hook        # what the agent runs: reads the hook JSON on stdin, writes the decision

Reads ECTOLEDGER_TOKEN and ECTOLEDGER_URL (default http://127.0.0.1:3000). Exits 2 on any failure. See Agent Integrations.

mcp-proxy

ironvise mcp-proxy --name files -- npx -y @modelcontextprotocol/server-filesystem ~/work

Runs the MCP server after -- and judges every tools/call before relaying it. Fails closed and exits with the server's exit code. Needs ECTOLEDGER_TOKEN with the agent role.

proxy

ironvise proxy --bind 127.0.0.1:3100 --upstream https://api.openai.com

Records only. --bind defaults to 127.0.0.1:3100, --upstream to https://api.openai.com. A non-loopback bind needs --allow-remote. Needs a running Observer and DATABASE_URL.

import-openshell

ironvise import-openshell ocsf.log [more.log ...] [--out openshell-receipts]

One sealed session and signed .elc receipt per sandbox, written to --out (default openshell-receipts). Needs DATABASE_URL.

webhook-key

WEBHOOK_HMAC_SECRET=... ironvise webhook-key --url https://siem.example/ironvise

Prints the 64-hex key that one receiver uses to verify X-EctoLedger-Signature-V1. Offline, no database.

replay

ironvise replay <session_id>
ironvise replay <session_id> --to-step 5
ironvise replay <session_id> --inject-observation "seq=3:injected content"

For debugging and adversarial testing.

verify-vc

ironvise verify-vc "eyJhbGci..."
ironvise verify-vc "eyJhbGci..." --issuer-hex <verifying key hex>
ironvise verify-vc "eyJhbGci..." --issuer-hex <key> --audience https://auditor.example

Checks structure and expiry, and the Ed25519 signature when --issuer-hex is given. Offline.

anchor-session

ironvise anchor-session <session_id>

Submits the ledger tip hash to the OpenTimestamps calendars and appends an Anchor event with the pending stamp. Only the hash leaves the machine. --chain bitcoin is accepted and is the only value.

orchestrate

ironvise orchestrate "Audit the Rust dependency tree for known vulnerabilities"
ironvise orchestrate "Audit Nginx config" --policy shared_policy.toml --max-steps 25

Three sequential sub-agents (Recon, Analysis, Verify), each in its own session, bound together by a CrossLedgerSeal. Per-role policies: ECTO_RECON_POLICY, ECTO_ANALYSIS_POLICY, ECTO_VERIFY_POLICY. Needs PostgreSQL.

diff-audit

ironvise diff-audit --baseline <session_id> --current <session_id> [--output diff.json]

Needs PostgreSQL.

red-team

ironvise red-team --target-session <session_id> --attack-budget 100 --output red-team-report.json

Generates injection payloads with a model and tests each against the output scanner and tripwire. --attack-budget defaults to 50. Exits 1 when any payload passes every check. Needs PostgreSQL.

prove-audit

Unavailable in 0.8. SP1 proving was withdrawn because of an upstream security advisory (RUSTSEC-2026-0387). The command exits 1 with an explanation. Use ironvise report --format certificate --output audit.elc <session_id> instead.