CLI Reference

chio check

Evaluate a single tool call against a policy without spawning a subprocess. Useful for dry-running policy changes or testing guard behavior.

chio check --policy <PATH> --tool <NAME> [--mode <preflight|full>] [--params <JSON>] [--server <ID>] [--output-fixture <PATH>]

$ chio check --policy ./policy.yaml \
    --tool read_file \
    --params '{"path": "./workspace/README.md"}'

verdict:  ALLOW
tool:     read_file
server:   *
guards:   8/8 passed

chio run

Spawn an agent subprocess and enforce policy via the kernel. The kernel mediates every tool call the agent makes, applying guard rules and signing receipts.

chio run --policy <PATH> -- <COMMAND> [ARGS...]

$ chio run --policy ./policy.yaml -- node agent.js
INFO  kernel ready, spawning agent subprocess
INFO  agent exited with code 0
INFO  session complete: 47 receipts (45 allow, 2 deny)

chio init

Scaffold a runnable Chio example project with a governed demo flow.

chio init <PATH>

$ chio init my-governed-agent
Created project at ./my-governed-agent
  policy.yaml   · starter HushSpec policy
  agent.js      · demo agent script
  README.md     · getting started guide

chio mcp wrap

Wrap a stdio MCP server with verdict gating and emit paste-ready IDE configs. wrap spawns the child, pulls tools/list once on warmup, and gates each tools/call through a manifest-scaffold allowlist. Any tool not yet promoted to allow: true in the file passed via --manifest is denied with a urn:chio:error:capability:scope-exceeded JSON-RPC error. This is a lighter-weight workflow than chio mcp serve and chio mcp serve-http, which run a full policy-driven, kernel-mediated edge over stdio or HTTP; wrap is aimed at manifest-scaffold bootstrapping and IDE onboarding.

chio mcp wrap [--server-id <ID>] [--manifest <PATH>] [--print-scopes] \
    [--emit-config <cursor|claude-desktop|continue|zed>] [--display-name <NAME>] \
    [--strict-execution-nonce] -- <COMMAND> [ARGS...]

# Print the inferred capability-scope scaffold, then emit a Cursor config:
$ chio mcp wrap --print-scopes \
    -- npx -y @modelcontextprotocol/server-filesystem ./workspace
$ chio mcp wrap --emit-config cursor --display-name "Files (governed)" \
    -- npx -y @modelcontextprotocol/server-filesystem ./workspace

# Run the gated wrap loop against a promoted manifest scaffold:
$ chio mcp wrap --manifest ./scopes.yaml --server-id srv-files \
    -- npx -y @modelcontextprotocol/server-filesystem ./workspace

chio mcp serve

Wrap an MCP server subprocess and expose a secured MCP edge over stdio. The Chio kernel intercepts every tool call, applies policy, and signs receipts before forwarding to the wrapped server.

chio mcp serve (--policy <PATH> | --preset <NAME>) [--server-id <ID>] [OPTIONS] -- <COMMAND> [ARGS...]

$ chio mcp serve --policy ./policy.yaml --server-id srv-files \
    -- npx -y @modelcontextprotocol/server-filesystem ./workspace

# Or use the bundled code-agent preset instead of a policy file:
$ chio mcp serve --preset code-agent --server-id srv-files \
    -- npx -y @modelcontextprotocol/server-filesystem ./workspace

chio mcp serve-http

Wrap an MCP server subprocess and expose a secured MCP edge over Streamable HTTP. Supports multiple concurrent remote sessions, OAuth2 and JWT authentication, and optional shared subprocess mode.

chio mcp serve-http --policy <PATH> --server-id <ID> [OPTIONS] -- <COMMAND> [ARGS...]

$ chio mcp serve-http \
    --policy ./policy.yaml \
    --server-id srv-files \
    --listen 0.0.0.0:8931 \
    --auth-token my-secret-token \
    -- npx -y @modelcontextprotocol/server-filesystem ./workspace

INFO  remote MCP edge listening on 0.0.0.0:8931
INFO  authentication: static bearer token

chio trust serve

Serve the shared trust-control plane over HTTP. The trust-control service provides centralized revocation, reputation scoring, federation policy, passport lifecycle management, and certification registry.

chio trust serve --service-token <TOKEN> [OPTIONS]

$ chio trust serve \
    --service-token my-control-token \
    --listen 0.0.0.0:8940 \
    --passport-statuses-file ./data/passports.json \
    --certification-registry-file ./data/certs.json

INFO  trust-control service listening on 0.0.0.0:8940

chio trust revoke

Persist a capability revocation into the configured revocation database.

chio trust revoke --capability-id <ID>

chio trust status

Query whether a capability ID is currently revoked.

chio trust status --capability-id <ID>

chio trust federation and economics

Beyond serve, revoke, and status, TrustCommands hosts a large enterprise-federation and economics command groups, each backed by dedicated schema families under the Chio federation, risk, and transaction schema namespaces. Most take a JSON or YAML input file and honor the global --control-url/--control-token flags to target a running trust-control service, falling back to a local registry file otherwise.

Federation and delegation:

• chio trust provider (list/get/upsert/delete): enterprise federation provider-admin records
• chio trust federation-policy (list/get/upsert/delete/evaluate): permissionless federation admission policies
• chio trust federated-issue: issue one local capability after verifying a challenge-bound portable presentation
• chio trust federated-delegation-policy-create: create a signed federated delegation policy from a single default capability
• chio trust evidence-share (list): inspect shared remote evidence references used by local delegated activity
• chio trust authorization-context (metadata/list/review-pack): derived external authorization context from governed receipts

Attestation and risk reporting:

• chio trust appraisal (export/export-result/import): signed runtime-attestation appraisal reports
• chio trust behavioral-feed (export): signed insurer-facing behavioral feed
• chio trust exposure-ledger (export): signed exposure ledger from canonical trust and underwriting data
• chio trust credit-scorecard (export): signed subject-scoped credit scorecard
• chio trust credit-backtest (export): deterministic credit backtests over historical evidence windows
• chio trust provider-risk-package (export): signed provider-facing risk package

Capital and credit lifecycle:

• chio trust capital-book (export): signed live capital book with source-of-funds attribution
• chio trust capital-instruction (issue): custody-neutral escrow or reserve instruction
• chio trust capital-allocation (issue): capital-allocation decision produced after simulation
• chio trust facility (evaluate/issue/list): bounded credit facilities
• chio trust bond (evaluate/issue/simulate/list): reserve-lock bonds
• chio trust loss (evaluate/issue/list): immutable bond-loss records

Liability market and underwriting:

• chio trust liability-provider (issue/list/resolve): curated liability-market provider registry entries
• chio trust liability-market: quote, placement, bound-coverage, and claim-workflow issuance plus list/claims-list
• chio trust underwriting-input (export): signed underwriting policy-input snapshot
• chio trust underwriting-decision (evaluate/simulate/issue/list): bounded underwriting decisions
• chio trust underwriting-appeal (create/resolve): appeals against persisted decisions

chio receipt

Inspect and maintain the local receipt store. ReceiptCommands has seven subcommands: list, health, flush, audit, retention, checkpoint, and explain. Receipt write, health, flush, and checkpoint operations are local SQLite operator commands in this release: they require --receipt-db and are not proxyable to a remote --control-url node.

receipt list

List receipts from the receipt store with optional filters. Output is one JSON receipt per line (JSON Lines format).

chio receipt list [OPTIONS]

# List recent denials
$ chio receipt list --outcome deny --limit 10 --tenant acme-corp

# List receipts for a specific tool in a time window
$ chio receipt list --tool-name read_file --since 1713000000 --until 1713100000

receipt health

Report receipt-store write health and durability status.

chio receipt health --receipt-db <PATH>

receipt flush

Flush pending receipt writes to durable storage, bounded by a timeout.

chio receipt flush [--timeout-ms <N>]

--timeout-ms is the maximum time to wait for the flush to complete, in milliseconds (default 5000, minimum 1).

receipt audit

Run the full receipt-log audit: claim-log projection validation plus a complete checkpoint-chain verification.

chio receipt audit [--repair]

--repair performs an offline on-disk repair that revalidates the receipt chain on a local connection. Run it with the kernel stopped: a running kernel keeps its verified head in memory in a separate process that the CLI cannot reach, so --repair does not clear a live poisoned writer. Restart the kernel to reseed a clean head from the validated on-disk state.

receipt retention repair

Repair a receipt store bricked by a retention rotation that left orphaned claim-log rows. The repair removes rows whose source receipts were archived and deleted, restoring a writable, reopenable store, and fails closed.

chio receipt retention repair --archive <PATH>

--archive is the archive file holding the co-archived claim-log rows the removal is validated against. The subcommand is nested as retention repair; the flat spelling retention-repair is rejected.

receipt checkpoint

Inspect or advance the receipt-checkpoint chain. Subcommands: status, create, verify.

chio receipt checkpoint status  [--max-batch <N>]                            # report checkpoint-chain status
chio receipt checkpoint create  --kernel-seed-file <PATH> [--max-batch <N>]  # create the next signed checkpoint
chio receipt checkpoint verify                                              # verify checkpoint-chain integrity

--max-batch caps the number of receipts considered per checkpoint batch (default 1024, minimum 1). create signs the checkpoint with the kernel keypair loaded from --kernel-seed-file.

receipt explain

Explain why a receipt was allowed or denied and render its parent lineage.

chio receipt explain <RECEIPT_ID> [--input-file <PATH>] [--depth <N>] \
    [--fanout-limit <N>] [--inspect-bilateral] [--tenant <ID> | --admin-all]

--depth bounds the parent depth rendered (default 8) and --fanout-limit the siblings per level (default 32). When --input-file points at a BilateralCoSignArtifacts document, the renderer auto-detects the bilateral shape and prints both the dual-signed receipt and the DSSE signature-slice sections. --inspect-bilateral (alias --explain-bilateral) additionally emits a structural, schema-only inspection trace of the envelope; that trace performs no Ed25519 signature verification and makes no cryptographic-verification claim. Like the other reading paths, the explanation fails closed unless --tenant or --admin-all is supplied.

chio evidence

Export, verify, and import offline evidence packages from the local receipt database for cross-organizational sharing and federation, and author the signed bilateral federation policies that constrain those exports.

evidence export

chio evidence export --output <DIR> [OPTIONS]

evidence verify

Verify every receipt signature, parameter hash, and checkpoint inclusion proof in an evidence package without importing it.

chio evidence verify --input <DIR>

Essential flag: --input <DIR> (required). Path to the evidence package directory.

evidence import

Import a verified evidence package into the local receipt database, merging receipts and checkpoints.

chio evidence import --input <DIR>

Essential flag: --input <DIR> (required). Path to the evidence package directory.

evidence federation-policy create

Create a signed bilateral federation policy document that constrains receipt sharing between two organizations. The resulting document is passed to chio evidence export --federation-policy to bound an export's scope.

chio evidence federation-policy create \
    --output <PATH> \
    --signing-seed-file <PATH> \
    --issuer <ORG> \
    --partner <ORG> \
    --expires-at <UNIX_SECONDS> \
    [--capability <ID>] [--agent-subject <HEX>] \
    [--since <UNIX_SECONDS>] [--until <UNIX_SECONDS>] \
    [--tenant <ID> | --admin-all] [--require-proofs]

Required flags: --output (signed policy JSON path), --signing-seed-file (persistent signing seed), --issuer and --partner (issuing and receiving organization identifiers), and --expires-at (policy expiry, Unix seconds). The optional flags scope the shared export by capability, agent subject, time window, tenant, and checkpoint-coverage requirement.

chio passport

Manage Agent Passport bundles. Passports are portable, signed bundles of reputation credentials that agents carry across trust boundaries. chio passport spans ten subcommand groups: the core lifecycle documented below (generate, create, verify, evaluate, present), plus verifier-policy management (policy), challenge/response presentation (challenge), lifecycle status (status), OID4VCI-style credential issuance (issuance), and the OID4VP verifier/holder interop flow (oid4vp).

passport generate

Synthesize a trust-tier-enriched passport for a named agent. Computes the agent's compliance score and behavioral anomaly, collapses them into a TrustTier, and emits a minimal passport JSON document with that tier populated. Distinct from create, which builds a single-issuer passport from local receipt and lineage data.

passport create

chio passport create --subject-public-key <HEX> --output <PATH> --signing-seed-file <PATH> [OPTIONS]

passport verify

Verify the signatures, validity window, and (optionally) lifecycle status of a passport bundle.

chio passport verify --input <PATH> [--at <UNIX_SECONDS>] [--passport-statuses-file <PATH>]

Essential flags: --input (required, passport JSON path), --at (evaluate validity at this Unix seconds timestamp), --passport-statuses-file (local lifecycle registry for revocation checks).

passport evaluate

Evaluate a passport against a policy's reputation and acceptance rules, producing a tier assignment and accept/reject verdict.

chio passport evaluate --input <PATH> --policy <PATH> [--at <UNIX_SECONDS>]

Essential flags: --input (required, passport JSON path), --policy (required, policy YAML with reputation rules), --at (evaluate at this Unix seconds timestamp).

passport present

Produce a minimal presentation from a passport, filtering credentials by accepted issuer list and a maximum count.

chio passport present --input <PATH> --output <PATH> [--issuer <DID>...] [--max-credentials <N>]

Essential flags: --input (required, passport JSON path), --output (required, output path for the presentation), --issuer (repeatable, restrict to these issuer DIDs), --max-credentials (integer cap on included credentials).

passport policy

Create, verify, and manage signed relying-party verifier policies. Subcommands: create, verify, list, get, upsert, delete. The list, get, upsert, and delete operations honor --control-url to target a running trust-control service, or a local registry file otherwise.

passport challenge

Create and consume challenge-bound passport presentations for replay-safe verification. Subcommands: create (mint a presentation challenge for a relying party), respond (answer a challenge with the passport subject key), submit (send a signed response to a public verifier transport URL), and verify (verify a challenge-bound response).

passport status

Publish, resolve, and revoke passport lifecycle state. Subcommands: publish, list, get, resolve, revoke. These operate against the passport lifecycle registry served by chio trust serve.

passport issuance

Deliver passports through an OID4VCI-style pre-authorized issuance flow. Subcommands: metadata (issuer metadata document), offer (credential offer), token (pre-authorized-code token exchange), and credential (credential issuance).

passport oid4vp

Create and consume Chio's narrow OID4VP verifier and holder interop flow. Subcommands: create (replay-safe verifier request on the running trust-control service), respond (build a holder response from a verifier request or launch URL), submit (submit a response JWT), and metadata (fetch the public verifier metadata document).

chio did resolve

Resolve a did:chio identifier or Ed25519 public key into a DID Document.

chio did resolve [--did <DID> | --public-key <HEX>] [OPTIONS]

$ chio did resolve --public-key 9c7b3f...a1b2c3

chio certify

Evaluate conformance evidence and emit a signed certification record. Certify manages the full lifecycle: check, verify, and registry operations.

certify check

chio certify check \
    --scenarios-dir <DIR> \
    --results-dir <DIR> \
    --output <PATH> \
    --tool-server-id <ID> \
    --signing-seed-file <PATH> \
    [OPTIONS]

certify verify

Verify the signature and criteria-profile evaluation of a certification record.

chio certify verify --input <PATH>

Essential flag: --input <PATH> (required). Path to the signed certification JSON.

certify registry

Manage the certification registry served by chio trust serve: publish a certification (to a local registry, or across a discovery network), list entries, fetch one by certification ID, resolve the current certification for a tool server, discover and search certifications across configured operators, render the public transparency feed, consume public listings against a local import policy, and revoke or dispute a published certification.

chio certify registry publish         --input <PATH>              # publish signed artifact to registry
chio certify registry publish-network --input <PATH> [--operator-id <ID>...]  # publish across discovery-network operators
chio certify registry list                                        # list certifications in the registry
chio certify registry get             --artifact-id <CERT_ID>     # fetch a certification by artifact ID
chio certify registry resolve         --tool-server-id <ID>       # resolve current certification for a tool server
chio certify registry discover        --tool-server-id <ID>       # discovery status across configured operators
chio certify registry search          [--tool-server-id <ID>] [--criteria-profile <P>] [--status <S>]  # search public listings
chio certify registry transparency    [--tool-server-id <ID>] [--operator-id <ID>...]  # render the public certification transparency feed
chio certify registry consume         --tool-server-id <ID> [--criteria-profile <P>...] [--evidence-profile <P>...]  # evaluate public listings against a local import policy
chio certify registry revoke          --artifact-id <CERT_ID> [--reason <TEXT>] [--revoked-at <UNIX_SECONDS>]  # revoke a certification
chio certify registry dispute         --artifact-id <CERT_ID> --state <open|under-review|resolved-no-change|resolved-revoked> [--note <TEXT>]  # open or resolve a dispute

Registry subcommands honor the global --control-url and --control-token flags to target a running trust-control service; without them they read or update a local registry or discovery-network file.

chio reputation

Inspect local reputation scorecards from persisted receipts and lineage state.

reputation local

chio reputation local --subject-public-key <HEX> [OPTIONS]

reputation compare

Compare the live local reputation corpus against a portable passport.

chio reputation compare --subject-public-key <HEX> --passport <PATH> [OPTIONS]

Additional Commands

The remaining top-level subcommands cover HTTP-API protection, guard development, proof and commerce evidence, workflow preflight, conformance, federation, attestation, live-runtime admission, pheromones, replay, settlement, lineage, diagnostics, the adversarial arena, and provider binding.

chio api protect

Start the Chio HTTP sidecar as a reverse proxy that enforces policy over an upstream HTTP API and derives tool definitions from an OpenAPI spec.Protect is the sole ApiCommands variant.

chio api protect --upstream <URL> [--spec <PATH>] [--listen <ADDR>] \
    [--receipt-store <PATH>] [--allow-ephemeral-receipts] [--upstream-timeout-secs <N>]

chio start

Zero-config convenience alias for chio api protect aimed at SDK quickstart and chio-hermes users. It runs the same sidecar router but with no upstream proxy (the catch-all path returns 502) and durable receipts by default. chio api protect is the production command for deployments that need --upstream, --spec, and persistent stores.

chio start [--listen 127.0.0.1:9090] [--receipt-store <PATH>] [--allow-ephemeral-receipts] [--print-config]

chio cert

Generate, verify, and inspect ACP session compliance certificates. This is a different command from chio certify, which produces conformance-corpus certification artifacts; chio cert attests that a specific ACP session ran within its budget and policy.

chio cert generate --session-id <ID> --receipt-db <PATH> [--budget-limit <N>] [--output <PATH>]
chio cert verify   --certificate <PATH> --trusted-kernel-pubkey <PATH> [--full] [--receipt-db <PATH>]
chio cert inspect  --certificate <PATH>

--budget-limit defaults to 0 (unlimited). verify --full re-verifies every receipt signature in the bundle and requires --receipt-db.

chio guard

WASM guard development lifecycle. Subcommands: new (scaffold a guard crate with Cargo.toml, src/lib.rs, and guard-manifest.yaml), build (compile to wasm32-unknown-unknown), inspect, test, bench, pack (produce a .arcguard archive), and publish/pull (push and fetch a three-layer OCI guard artifact; the registry password is read from CHIO_GUARD_REGISTRY_PASSWORD).

chio proof

Assemble, collect, and verify proof bundles and Transaction Passport records, and serve a static, read-only Proof Room for a verified proof bundle (chio proof serve). The Proof Room renders verified evidence and does not authorize actions.

chio commerce

Verify commerce proof bundles and payment evidence, including agent-web envelopes, buyer packages, transaction passports, and settlement records.

chio workflow

Validate read-only workflow planning evidence before dispatch via chio workflow preflight. The CLI command validates preflight evidence; it does not execute the workflow.

chio conformance

Run the cross-language conformance harness against a peer adapter. chio conformance fetch-peers pulls peer adapters pinned in the conformance lockfile; supports --check, --out, and --language.

chio federation

Produce and verify cross-kernel federation records (subcommands authority and treaty).

chio attest

Verify offline attestation evidence and buyer proof packages. Subcommands: buyer, supply-chain, runtime-quote.

chio runtime

Evaluate local live-runtime admission records and run live-runtime operator commands (admission, signed trust inputs, policy signing, peer weights, orchestration, and ops).

chio pheromone

Receive, query, and relay pheromone records (subcommands receive, query, relay).

chio replay

Re-evaluate a captured receipt log against the current build. Reads a directory of signed receipts (or an NDJSON tee stream), re-verifies every signature, recomputes the Merkle root incrementally, and reports the first divergence by byte offset and JSON pointer. The exit code is the reported outcome:

chio settle

Inspect local settlement lifecycle records: pending IOU envelopes, settled reconciliations, and dead-lettered settlements.

chio lineage

Query, diff, or list anchored roots in the lineage DAG. Subcommands: query (walk forward or reverse from a seed node over a lineage dump), diff (symmetric edge diff between two dumps), and roots (list pinned-frontier records).

chio doctor

Diagnose toolchain, guard-registry, OTEL, and chio.yaml health. Probes run in order: toolchain version vs. workspace MSRV, OCI guard registry reachability, cosign guard-bundle freshness, OTEL exporter resolution, kernel /metrics, and chio.yaml schema validity. The exit code follows the worst observed severity: 0 for ok/info/warning, 1 for error, and 2 for fatal. --fix runs idempotent repairs only.

chio arena

The chio-arena coliseum: run scenarios, replay bundles, and evolve adversaries. run scenarios/<name>.toml drives the kernel and writes a replay-compatible receipt bundle under target/arena/<scenario-id>/; replay delegates to chio replay; and evolve ... --generations N runs the co-evolution driver under a bounded-budget gate.

chio bind

Bind a provider under a signed model card. Loads the canonical-JSON model card, validates its shape, and prints the resolved weights_hash and allowed_capability_set for operator review before promotion.

chio bind <PROVIDER> --card <PATH> \
    [--bundle <PATH> --issuer-san-regex <REGEX> --issuer-oidc <URL>] \
    [--weights-binding-mode not_required|required|required_with_pin]

When --bundle is supplied the cosign bundle is verified before the binding summary prints; required and required_with_pin weights-binding modes require a bundle so card verification cannot be silently skipped.