CLI Reference: Replay Debugger
Commands for replaying and rolling back an agent's execution timeline.
The replay debugger merges an agent's audit log, observation log, and workspace snapshot history into a unified chronological timeline. See Replay Debugger for background.
ash replay timeline
Show the full merged execution timeline for an agent.
ash replay timeline <agent-id> \
[--since <rfc3339>] \
[--until <rfc3339>]
| Argument/Flag | Description |
|---|---|
agent-id | Target agent |
--since | Only show events at or after this RFC3339 timestamp |
--until | Only show events at or before this RFC3339 timestamp |
Example:
ash replay timeline <agent-id>
ash replay timeline <agent-id> \
--since 2026-01-15T10:00:00Z \
--until 2026-01-15T11:00:00Z
Timeline entry fields:
| Field | Description |
|---|---|
timestamp | RFC3339 UTC |
source | audit, observation, or snapshot |
event | Event type |
detail | Event-specific detail |
The timeline interleaves all three sources in strict chronological order, giving a complete picture of what the agent did, what it observed, and what its workspace looked like at each point.
ash replay rollback
Roll back an agent's workspace to a previous snapshot (replay-debugger shorthand).
ash replay rollback <agent-id> <index>
This is equivalent to ash workspace rollback but accessed through the replay interface. Use ash replay timeline to identify the snapshot index you want to restore.
Example workflow:
# 1. Review the timeline to find where things went wrong
ash replay timeline <agent-id>
# 2. Identify the snapshot index just before the bad action
# (snapshot entries appear inline in the timeline)
# 3. Roll back to that snapshot
ash replay rollback <agent-id> 3
Use cases
- Root cause analysis: trace exactly what sequence of tool calls led to an undesired outcome.
- Time-travel debugging: restore workspace state to any point and re-run with different inputs.
- Compliance review: produce a complete audit-quality record of an agent's actions for a given time window.