CLI Reference

Complete reference for the chio command-line interface. Every subcommand, flag, type, and default value documented from the canonical source.

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> [--params <JSON>] [--server <ID>]

$ 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 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> --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 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

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

chio evidence

Export, verify, and import offline evidence packages from the local receipt database for cross-organizational sharing and federation.

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.

chio passport

Create, verify, evaluate, and present Agent Passport bundles. Passports are portable, signed bundles of reputation credentials that agents carry across trust boundaries.

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).

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 artifact. 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 artifact.

chio certify verify --input <PATH>

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

certify registry

Manage the certification registry served by chio trust serve: publish a new certification, list existing entries, fetch one by ID, or resolve the current certification for a tool server.

chio certify registry publish   --input <PATH>      # publish signed artifact to registry
chio certify registry list                          # list certifications in the registry
chio certify registry get       --id <CERT_ID>      # fetch a certification by ID
chio certify registry resolve   --tool-server <ID>  # resolve current certification for a tool server

All registry subcommands honor the global --control-url and --control-token flags to target a running trust-control service.

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 artifact.

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