> ## Documentation Index
> Fetch the complete documentation index at: https://swayamg20-agentrelay-44.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Auditing agent activity and rotating your API key

> Use agentrelay audit to query the audit ledger for forensics and incident response, and agentrelay rotate-key to atomically replace your API key on the relay.

Two operational commands round out the CLI: `audit` gives you a full view of what actions occurred under your agent identity, and `rotate-key` lets you replace a compromised or expired API key without losing access.

## agentrelay audit

`audit` fetches events from the relay-side audit log where you are a participant — either as the actor or as a sender/recipient of the associated handoff. It also reads any local audit ledger written by your MCP server for actions your agent took in response to incoming handoffs.

```bash theme={null}
npx -y -p agentrelay-mcp agentrelay audit \
  [--since <ISO timestamp>] \
  [--from <handle>] \
  [--action <symbol>] \
  [--limit 100]
```

### Flags

| Flag       | Type               | Default | Description                                                                     |
| ---------- | ------------------ | ------- | ------------------------------------------------------------------------------- |
| `--since`  | ISO 8601 timestamp | —       | Return only events at or after this time, e.g. `2026-04-26T00:00:00Z`           |
| `--from`   | handle             | —       | Filter to events where the sender or actor is this handle                       |
| `--action` | string             | —       | Filter by action symbol, e.g. `handoff.create`, `handoff.accept`                |
| `--limit`  | number             | `100`   | Maximum number of events to return. Hard cap at 1000                            |
| `--format` | `tsv` or `jsonl`   | auto    | Output format. Defaults to `tsv` when stdout is a terminal, `jsonl` when piped. |

### Output format

When stdout is a terminal, `audit` renders a tab-separated table. When piped, it emits JSON-lines — one JSON object per event — suitable for log shippers or `jq` pipelines.

**TSV format columns:**

| Column       | Description                                           |
| ------------ | ----------------------------------------------------- |
| `timestamp`  | ISO 8601 event time                                   |
| `handoff_id` | The handoff UUID this event belongs to, if applicable |
| `from`       | The actor's handle                                    |
| `action`     | Action symbol                                         |
| `details`    | Human-readable summary of what changed                |

**Example output** showing a complete propose-action sequence:

```
timestamp                handoff_id    from         action          details
2026-04-26T10:01:23Z     01HXY...      bob@acme     edit_drafted    src/api/users.client.ts (12 ins / 4 del)
2026-04-26T10:01:25Z     01HXY...      bob@acme     edit_applied    src/api/users.client.ts (approved by frank)
2026-04-26T10:02:11Z     01HXY...      bob@acme     test_run        pytest tests/users/  → pass
```

### Use cases

`audit` is Layer 4 of the trust model. Common queries:

**Review everything Bob's agent triggered this week:**

```bash theme={null}
npx -y -p agentrelay-mcp agentrelay audit \
  --from bob@acme \
  --since 2026-04-21T00:00:00Z
```

**Incident response — what happened in the last hour:**

```bash theme={null}
npx -y -p agentrelay-mcp agentrelay audit \
  --since $(date -u -v-1H +"%Y-%m-%dT%H:%M:%SZ") \
  --limit 500
```

**Find all file edits:**

```bash theme={null}
npx -y -p agentrelay-mcp agentrelay audit --action edit_applied
```

**Pipe to jq for structured analysis:**

```bash theme={null}
npx -y -p agentrelay-mcp agentrelay audit --limit 1000 \
  | jq 'select(.action == "edit_applied") | .metadata'
```

<Tip>
  If you suspect a teammate's account was compromised, run `audit --from <handle>` to see everything their agent triggered, then run `block <handle>` to revoke access. The audit log is append-only and cannot be altered.
</Tip>

***

## agentrelay rotate-key

`rotate-key` replaces your current API key with a new one. It uses your existing key to authenticate the rotation request — you do not need the admin token. Once the relay confirms the rotation, the local config file is rewritten atomically.

```bash theme={null}
npx -y -p agentrelay-mcp agentrelay rotate-key
```

### What it does

<Steps>
  <Step title="Read current config">
    Loads `~/.agentrelay/config.json` and extracts the current `api_key` and `relay_url`.
  </Step>

  <Step title="Request rotation from the relay">
    Calls `POST /agents/me/keys/rotate` with the current key as the `Authorization: Bearer` header. The relay atomically revokes the old key and generates a new one.
  </Step>

  <Step title="Rewrite config atomically">
    Writes the new key to `~/.agentrelay/config.json` via a tempfile-then-rename sequence with permissions `0600`. If this step fails after the relay has already rotated, the command surfaces the new key in the error message so you can save it manually.
  </Step>
</Steps>

### When to rotate

* **Stolen or leaked key** — rotate immediately. The old key is revoked the moment the relay processes the rotation request.
* **Regular hygiene** — rotate on a schedule that matches your team's security policy.
* **After a relay pepper change** — if the relay operator regenerated `RELAY_PEPPER`, your existing key can no longer be verified. Re-run `agentrelay register` to get a fresh key, or ask the operator to rotate your key via the admin endpoint.

<Warning>
  The relay revokes the old key atomically when it processes the rotation. Any MCP server instances using the old key will fail immediately after rotation. Restart Claude Code or Codex CLI after running `rotate-key` to pick up the new credentials from `~/.agentrelay/config.json`.
</Warning>