---
title: CLI Commands
description: Command reference for the Agent Receipts CLI tools — mcp-proxy audit commands and agent-receipts-hook.
---

This page covers the `mcp-proxy` audit subcommands and the `agent-receipts-hook` PostToolUse hook binary.

> The default `-db` and `-receipt-db` paths shown below resolve via Go's `os.UserHomeDir()`. On Unix and macOS this is `$HOME`; on Windows this uses the OS user home directory, typically `%USERPROFILE%`.

## `mcp-proxy -version`

Print the version and exit.

```bash
mcp-proxy -version
# mcp-proxy vX.Y.Z
```

## `mcp-proxy list`

List receipts from the audit store. Results are sorted **newest first** — the most recent receipts appear at the top. Default limit is 50.

```bash
mcp-proxy list                            # latest 50 receipts, newest first
mcp-proxy list -risk high                 # filter by risk level
mcp-proxy list -action data.api.read      # filter by action type (taxonomy value)
mcp-proxy list -chain <chain-id>          # filter by chain
mcp-proxy list -limit 100                 # limit results
mcp-proxy list -json                      # JSON output
mcp-proxy list -f                         # tail-like: stream new receipts live
mcp-proxy list --follow --interval 1s     # custom poll interval
```

| Flag | Description |
|------|-------------|
| `-risk` | Filter by risk level: `low`, `medium`, `high`, `critical` |
| `-action` | Filter by action type |
| `-chain` | Filter by chain ID |
| `-limit` | Maximum number of receipts to return (default: `50`) |
| `-json` | Output as JSON (NDJSON — one object per line — in `--follow` mode) |
| `-follow`, `-f` | After the initial listing, keep polling and stream new receipts as they are inserted (`tail -f`-style). Exit with `Ctrl-C`. In `--follow` mode, the startup batch is printed in chronological order (oldest → newest) so it reads continuously with the streamed tail. |
| `-interval` | Poll interval in `--follow` mode (default: `500ms`) |
| `-receipt-db` | Receipt store path (default: `$HOME/.local/share/agent-receipts/receipts.db`) |

### Example output

```
$ mcp-proxy list
ID                     SERVER         TOOL                           ACTION                 RISK     STATUS   TIMESTAMP
---
urn:receipt:b4b430f9... atlassian      getJiraIssue                   data.api.read          low      success  2026-04-24T02:05:19Z
urn:receipt:32506b71... atlassian      searchJiraIssuesUsingJql       data.api.read          low      success  2026-04-24T01:56:12Z
urn:receipt:f5da030f... atlassian      getAccessibleAtlassianResou... data.api.read          low      success  2026-04-24T01:56:06Z
urn:receipt:a125fd30... github         list_pull_requests             data.api.read          low      success  2026-04-24T01:44:20Z
urn:receipt:67fede57... github         add_reply_to_pull_reques...    data.api.write         medium   success  2026-04-24T00:51:57Z
urn:receipt:013bfc43... github         request_copilot_review         data.api.write         medium   success  2026-04-24T00:43:40Z
urn:receipt:7ae4f1b2... github         issue_write                    data.api.write         medium   success  2026-04-24T00:19:35Z
urn:receipt:d52ba1fd... github         issue_write                    data.api.write         medium   success  2026-04-24T00:19:25Z

8 receipts
```

SERVER identifies which MCP server handled the call. It comes from the `-name` flag, defaulting to the wrapped command's basename if `-name` is omitted. TOOL is the raw tool name (truncated at 30 characters). When running multiple proxied servers simultaneously — for example GitHub and Atlassian — the SERVER column is how you tell their receipts apart at a glance.

The `-action` filter matches the ACTION column (taxonomy type, e.g. `data.api.read`), not the TOOL column. Issuer and operator identity isn't shown in the tabular view — use `mcp-proxy list -json` to see it.

## `mcp-proxy inspect`

Show details for a single receipt.

```bash
mcp-proxy inspect <receipt-id>
mcp-proxy inspect -key public.pem <receipt-id>   # verify signature
```

| Flag | Description |
|------|-------------|
| `-key` | Public key PEM file to verify the receipt signature |
| `-receipt-db` | Receipt store path (default: `$HOME/.local/share/agent-receipts/receipts.db`) |

## `mcp-proxy verify`

Verify the integrity of a receipt chain -- checks signatures, hash linkage, and sequence numbers.

```bash
mcp-proxy verify -key public.pem <chain-id>
```

| Flag | Description |
|------|-------------|
| `-key` | Public key PEM file (required) |
| `-receipt-db` | Receipt store path (default: `$HOME/.local/share/agent-receipts/receipts.db`) |

## `mcp-proxy export`

Export a receipt chain as JSON.

```bash
mcp-proxy export <chain-id>
mcp-proxy export <chain-id> > chain.json
```

| Flag | Description |
|------|-------------|
| `-receipt-db` | Receipt store path (default: `$HOME/.local/share/agent-receipts/receipts.db`) |

## `mcp-proxy stats`

Show aggregate statistics about the audit store.

```bash
mcp-proxy stats
mcp-proxy stats -json
```

| Flag | Description |
|------|-------------|
| `-json` | Output as JSON |
| `-receipt-db` | Receipt store path (default: `$HOME/.local/share/agent-receipts/receipts.db`) |

## `mcp-proxy timing`

Show per-tool timing breakdown from the audit database. Reports average phase durations (policy evaluation, approval wait, upstream call, receipt signing) and p50/p95/p99 percentiles.

```bash
mcp-proxy timing                              # all sessions
mcp-proxy timing -session <session-id>        # filter by session
mcp-proxy timing -json                        # JSON output
mcp-proxy timing -limit 10                    # top 10 tools
```

| Flag | Description |
|------|-------------|
| `-db` | Audit database path (default: `$HOME/.local/share/agent-receipts/audit.db`) |
| `-session` | Filter by session ID |
| `-limit` | Maximum number of tools to show (default: `20`) |
| `-json` | Output as JSON |

### Example output

```
$ mcp-proxy timing
Tool call timing (73 calls)

Per-tool averages:
TOOL                            COUNT UPSTREAM(us) POLICY(us) RECEIPT(us)  APPROVAL(us)  TOTAL(ms)
get_file_contents                  21            -          -           -             -        679
create_or_update_file              15            -          -           -             -       1162
search_issues                       6       747952          2         468             -        790
create_issue                        5            -          -           -             -       3742
create_branch                       5            -          -           -             -       1123

Percentiles:
PHASE                  p50        p95        p99
upstream            715744     946737     946737 (us)
policy_eval              2          5          5 (us)
receipt_sign           830       2420       2420 (us)
duration_ms            708       2489      16230 (ms)
```

Columns with `-` indicate tool calls recorded before timing instrumentation was added. New calls will populate all phase columns automatically.

The data shows that for a GitHub MCP server, upstream API latency dominates (about 716-947ms based on the upstream percentiles shown), while policy evaluation (2-5us) and receipt signing (0.8-2.4ms) add negligible overhead.

## `mcp-proxy doctor`

Diagnose proxy configuration: load and validate the policy rules file, summarise enabled rules by action (`pause`, `block`, `flag`), and optionally probe an approver URL for reachability.

```bash
mcp-proxy doctor                                    # validate built-in defaults
mcp-proxy doctor -rules /path/to/rules.yaml         # validate a custom rules file
mcp-proxy doctor -approver http://127.0.0.1:7778    # probe an approver URL
mcp-proxy doctor -json                              # JSON output
```

| Flag | Description |
|------|-------------|
| `-rules` | Policy rules YAML to validate (default: built-in) |
| `-approver` | Approver URL to probe for reachability (default: none) |
| `-json` | Output as JSON |

**Exit codes:** `0` if the configuration is healthy; `1` if any issues are reported; `2` on flag/usage errors.

## `mcp-proxy init`

One-command setup: creates `~/.local/share/agent-receipts/`, generates an Ed25519 signing keypair with correct permissions (private key `0600`, public key `0644`), initialises the receipt database, and prints a `claude_desktop_config.json` snippet to stdout.

Safe to re-run — warns and skips key generation if files already exist (use `-force` to overwrite).

```bash
mcp-proxy init                              # generate keys for the "default" instance
mcp-proxy init -name github                 # custom instance name
mcp-proxy init -no-approval                 # omit -http from the printed snippet
mcp-proxy init -http-port 9000              # custom approval listener port in snippet
mcp-proxy init -force                       # overwrite existing key files
```

| Flag | Description |
|------|-------------|
| `-name` | Name for this proxy instance, used in filenames and the config snippet (default: `default`) |
| `-no-approval` | Omit `-http` from the printed config snippet (no approval server) |
| `-http-port` | Approval listener port written into the config snippet (default: `7778`) |
| `-force` | Overwrite existing key files |

**Exit codes:** `0` on success; `1` on setup errors (home directory resolve, key write, DB init); `2` on invalid arguments (out-of-range `-http-port`, invalid `-name`) or flag/usage errors.

## `mcp-proxy audit-secrets`

Scan the audit database for values that match any built-in or custom redaction pattern. Useful after upgrading the proxy, adding new patterns, or as a periodic check that redaction is working as intended.

```bash
mcp-proxy audit-secrets                                       # scan with built-in patterns
mcp-proxy audit-secrets -redact-patterns custom.yaml          # also scan custom patterns
mcp-proxy audit-secrets -db /path/to/audit.db                 # specify audit DB path
```

| Flag | Description |
|------|-------------|
| `-db` | Audit database path (default: `$HOME/.local/share/agent-receipts/audit.db`) |
| `-redact-patterns` | YAML file with additional patterns to scan for |

If the database was encrypted at rest (proxy launched with `BEACON_ENCRYPTION_KEY`), set the same env var before running so the scanner can decrypt. Without the key, encrypted rows are reported as `encrypted-no-key` and counted as hits.

Output format — one line per match:

```
messages col=raw row=42 pattern=github_token
tool_calls col=arguments row=51 json-key=password
tool_calls col=result row=78 decrypt-error
```

The scanner reads `messages.raw` (full JSON-RPC payloads) and `tool_calls.arguments` / `tool_calls.result` / `tool_calls.error` — the columns where redaction is applied at write time.

**Exit codes:** `0` if no matches found; `1` if one or more matches found; `2` on error.

If matches are found, the raw token values are already in the database. Because the audit log is append-only, the recommended action is to **rotate the secret** and consider the old value compromised.

## `agent-receipts-hook`

Short-lived PostToolUse hook binary that captures native host tool calls and forwards them to `agent-receipts-daemon`. Invoked automatically by agent runtimes that support PostToolUse hooks — not meant to be run interactively.

```bash
agent-receipts-hook [--format=<name>]
```

| Flag | Description |
|---|---|
| `--format` | Force a specific input format (default: auto-detected from environment variables). Currently supported: `claude-code`. |

**Exit behaviour:** Always exits 0. Emit failures (daemon not running, socket missing, malformed frame) are dropped silently — the hook never blocks the agent.

**Auto-detection:** When `--format` is omitted, the binary inspects environment variables to identify the calling runtime. `CLAUDE_SESSION_ID` set → `claude-code` format.

See [Hook: Claude Code](/hook/claude-code/) for wiring instructions.
