CLI reference

Every herkos command and its flags. The binary is a single Go executable; run any command with no arguments to see its usage.

Commands at a glance

keygen

Create the local ed25519 signing key. It is written 0600 and stays on your machine. Every receipt is signed with it.

$ herkos keygen

register

Wire Herkos into an MCP config. Three modes. Wrap an existing server with --server <name>: Herkos rewrites that entry in place to launch through the broker, preserving its env, and leaves no direct entry the agent could still call - so there is no bypass. Add a new brokered server by passing the upstream command after --. Broker everything with --all: it wraps every local stdio server in the config, discovering each server's tools and pinning them as its allowlist.

$ herkos register --config <mcp.json> --server <name> --allow-tool <tool>

unregister

Remove Herkos from an MCP config and restore the original launch line.

$ herkos unregister --config <mcp.json>

serve

Run the in-path broker. Herkos sits in front of the upstream server and passes only the tools/call whose tool name you allowed. A call to any other tool is blocked in-path and answered with a JSON-RPC error; the session keeps running.

$ herkos serve --allow-tool read_file --allow-tool list_dir -- npx -y @some/mcp-server

$ herkos serve --allow-tool read_file --receipts ~/.herkos/audit --isolate -- npx -y @some/mcp-server

$ herkos serve --allow-tool post_message --index .herkos/index --served-span auth.go:1-40 -- npx -y @some/mcp-server

index

Build the code-graph index for a repo. This is the tree-sitter parse that select and the content gate read; it stays on disk and is rebuilt when you re-run it.

$ herkos index --out .herkos/index <dir>

select

Print the minimal span set for a query against a prebuilt index - the served set. These are the same spans that, on the egress path, become the deny-by-default allowlist. Pure-Go; it reads the index, it does not parse source.

$ herkos select --index .herkos/index --anchor Authenticate --budget 200

Each printed span has the form FILE:START-END (end exclusive) - the exact form serve --served-span expects.

scan

Audit an MCP config and emit a security receipt: over-scoped tools, poisoned tool descriptions, and servers with unrestricted egress. Pass a baseline to diff against a known-good state.

$ herkos scan --config <mcp.json> --baseline <b.json>

  [unbrokered] codegraph: launched directly, not through the herkos broker
  [remote] bank: remote http server at an external URL; the stdio broker cannot mediate it
herkos scan: 0 over-scoped, 0 poisoned, 0 unrestricted-egress, 1 unbrokered, 0 unpinned-install, 1 remote - your code never left this machine

status

Show the current state. Add --json for machine-readable output.

$ herkos status --json

receipt

Summarize a saved receipt file. Prints its Merkle root, enforcement mode, and span count without contacting any service. To cryptographically re-check the signature and root, use herkos verify --pubkey.

$ herkos receipt --file <r.json>

verify

Verify a receipt against an explicit public key, fully offline. It auto-detects the file: a single Merkle receipt verifies its signature and root; an audit-log chain (from serve --receipts) verifies the whole hash-chain and reports whether it was cleanly sealed. A truncated log - one missing its signed close record - is reported as INCOMPLETE with a non-zero exit, so silent tail-dropping is detectable.

$ herkos verify --file <receipt-or-chain.jsonl> --pubkey <hex>

init

Initialize Herkos in the current setup.

$ herkos init