CLI Reference: Audit
Commands for querying the tamper-evident audit log.
ash audit
Query the audit log, with optional filtering.
ash audit [--agent <agent-id>] [--limit <n>]
| Flag | Default | Description |
|---|---|---|
--agent, -a | (all agents) | Filter entries by agent ID |
--limit, -l | 20 | Maximum number of entries to show |
Example: show last 50 entries for a specific agent:
ash audit --agent 550e8400-e29b-41d4-a716-446655440000 --limit 50
Example: show the 20 most recent entries across all agents:
ash audit
Output format
Each audit entry includes:
| Field | Description |
|---|---|
timestamp | RFC3339 UTC timestamp |
agent_id | UUID of the agent that generated the entry |
event | Event type (e.g. ToolInvoke, StateTransition, CapabilityGrant, SecretUse) |
detail | Event-specific detail (tool name, old/new state, etc.) |
Secret values are never included in audit entries; they appear as [REDACTED:<name>].
Event types
| Event | Description |
|---|---|
Spawn | Agent was spawned |
StateTransition | Lifecycle state changed |
ToolInvoke | Tool was invoked (includes tool name, success/failure) |
CapabilityGrant | A capability grant was issued or revoked |
SecretUse | A secret handle was resolved (name only, never value) |
HumanApproval | An HITL request was approved or denied |
McpAttach | MCP server was attached |
McpDetach | MCP server was detached |
AnomalyDetected | Anomaly detector fired |
Terminate | Agent was terminated |
Audit log guarantees
- Entries are append-only and stored in an in-memory ring buffer (configurable size).
- Secret values are scrubbed before entries are written.
- All auto-approved secret uses include the matching policy ID for traceability.