CLI Reference

The agenttape command manages and inspects cassettes — all on local files, no network, no server.

agenttape <command> [args] [options]
agenttape --version
agenttape -v <command> ...   # -v / --verbose: show full tracebacks

Command	Does
init	Scaffold agenttape.toml + a cassettes/ directory
record	Run an entrypoint and record it
replay	Replay a cassette and print the reconstructed timeline
inspect	Pretty-print interactions, latency, tokens, cost
timeline	Render the run as an ASCII waterfall
diff	Structured diff of two cassettes
redact	Re-run redaction over a cassette
validate	Schema + determinism + leaked-secret lint
export	Export to JSON or OpenTelemetry
view	Generate a self-contained HTML viewer
rm	Delete a cassette and its assets

Resolving cassette arguments

Most commands accept either a path (cassettes/x.yaml) or a bare name (x) — bare names are resolved against your configured cassette_dir.

---

init

Scaffold a project: writes a commented agenttape.toml (if absent) and creates the cassettes/ directory.

agenttape init [--dir DIR]

Option	Default	Description
--dir	.	Project directory to scaffold

---

record

Import a module:function entrypoint and run it inside a recording session.

agenttape record my_app.agents:run_demo checkout [--mode MODE]

Argument / Option	Default	Description
entrypoint	—	module:function to call (no args)
cassette	—	Cassette name to write
--mode	record	Recording mode

---

replay

Replay a cassette and print its reconstructed timeline. Confirms what would be served — no external calls are made.

agenttape replay checkout

---

inspect

Pretty-print a cassette: metadata, each interaction's request/response, and totals (latency, tokens, cost).

agenttape inspect cassettes/weather.yaml [--full]

Option	Description
--full	Don't truncate large payloads

Cassette: cassettes/weather.yaml
version=1 run_id=de5dc0ac-…
meta: {"agenttape_version": "0.1.5", "mode": "record"}
freeze: clock, random, uuid

#0 [tool] get_weather  (0.0ms)
  request:  {"name": "get_weather", "args": {"city": "London"}}
  response: {"temp": 15, "condition": "rainy"}

------------------------------------------------------------
1 interactions · 0.0ms · 0+0=0 tokens · cost n/a

---

timeline

Render the run as an ASCII waterfall — great for seeing execution order and where time went.

agenttape timeline cassettes/weather.yaml

Timeline: cassettes/weather.yaml
run de5dc0ac · 1 interactions

User
  → Tool      get_weather            |████████████████████████████████████████|      0.0ms
Done

Σ latency 0.0ms · tokens 0 · cost n/a

---

diff

Structured diff of two cassettes. Indispensable with Partial Replay for comparing a derived run against its original.

agenttape diff cassettes/checkout.yaml cassettes/checkout.derived.yaml [--type TYPE]

Option	Choices	Default	Shows
--type	run, prompt, state, output, all	run	Which view of the diff to render

---

redact

Re-apply your current agenttape.toml redaction rules to an existing cassette, in place. Use it after recording a cassette before a new rule was configured.

agenttape redact cassettes/login.yaml

No --secret flag

redact applies the configured rules — it doesn't take an arbitrary secret string. Add the secret's pattern to [redact].regexes or its field name to [redact].denylist, then run redact. See Redaction.

---

validate

Lint a cassette: validate the schema, flag determinism risks, and scan for leaked secrets. Exit code is non-zero on errors — wire it into CI or a pre-commit hook.

agenttape validate cassettes/login.yaml

Validating cassettes/login.yaml
  ✓ valid — no issues found

---

export

Export a cassette to another format.

agenttape export cassettes/checkout.yaml --format otel -o trace.json

Option	Choices	Default	Description
--format	json, otel	json	Output format (otel = OpenTelemetry trace)
-o, --output	—	stdout	Write to a file instead of stdout

---

view

Generate a self-contained static HTML viewer — easier than reading long prompts in raw YAML. Pass a second cassette to render a side-by-side diff view.

agenttape view cassettes/checkout.yaml [second] [-o OUTPUT]

Argument / Option	Default	Description
second	—	Optional second cassette for a diff view
-o, --output	<cassette>.html	Output HTML path

---

rm

Delete a cassette and its sidecar assets (and any .derived companion).

agenttape rm cassettes/old.yaml [-f]

Option	Description
-f, --force	Skip the confirmation prompt

---

Summary

• init scaffolds; record/replay capture and reconstruct.
• inspect, timeline, diff, view help you understand a run.
• redact and validate keep cassettes secret-free; export feeds observability tools.
• All commands are local-only — no network, no server.

Next: Configuration Reference →