Skip to content

CLI reference

The tracesage command-line tool ships with the package. It is a viewer + utilities — it does NOT ingest events. Ingestion only happens when your Python code calls TraceSage.create().

tracesage serve

Start a read-only viewer over an existing data directory.

tracesage serve [OPTIONS]

Options:

  • --data-dir, -d PATH — path to existing data dir (default: ~/.tracesage)
  • --host, -h HOST — bind address (default 127.0.0.1)
  • --port, -p PORT — bind port (default 7842). If it's busy, the next free port is bound automatically (the real URL is printed on startup). Set TRACESAGE_PORT_AUTO=false to use exactly this port instead, or --port 0 for an OS-assigned ephemeral port.
  • --auth-token TOKEN — bearer token (env: TRACESAGE_AUTH_TOKEN)
  • --open, -o — open the viewer in your browser once it's up

So you can run a viewer for several data dirs at once — each lands on 7842, 7843, … without clashing.

Use cases:

  • Inspect traces after the producer process exited.
  • Run the viewer on a different machine than the producer (sync data_dir first).
  • Restart only the UI without restarting the application.

tracesage demo

Seed a sample trace and open the UI — the fastest way to see tracesage working.

tracesage demo               # seed + serve + open browser
tracesage demo --check       # seed only, then exit (for smoke tests / CI)

Note: demo writes to its own dir (~/.tracesage-demo by default, override with -d), separate from the default ~/.tracesage, so it never mixes with your real runs.

tracesage show

Render a run's trace as an indented tree in the terminal (no server needed). Each element kind (chain, agent, tool, llm, retriever, …) is printed in its own colour, tools backed by an MCP server are tagged mcp:<server>, and siblings follow execution flow (oldest-first).

tracesage show <run_id> [--no-color] [--reverse]
  • --no-color — disable ANSI colour (auto-detected by default)
  • --reverse, -r — order siblings newest-first instead of execution order

tracesage watch

Live-tail a run's events in the terminal as they're written (Ctrl-C to stop).

tracesage watch <run_id> [--interval 1.0] [--once]

--once prints the current events and exits (no follow loop).

tracesage diff

Compare two runs side by side (status, steps, tokens, tools, errors).

tracesage diff <run_a> <run_b>

tracesage view

Open an exported JSONL trace directly in the UI (imports into a temp dir, serves it).

tracesage view trace.jsonl [--open]

tracesage export

Dump runs to JSONL.

tracesage export [RUN_ID] [OPTIONS]

Options:

  • RUN_ID (positional) — single run to export; alternative to --run-id
  • --data-dir, -d PATH
  • --run-id ID — single run to export
  • --all — export every run
  • --output, -o PATH — file path or - for stdout (default: -)
  • --format, -f FORMAT — jsonl only (for now)

Output format: first line per run is the Run row; subsequent lines are StoredEvent rows. Each line is JSON with a _kind discriminator (run or event).

tracesage export --run-id order-8821 -o trace.jsonl
tracesage export --all -o all_traces.jsonl

tracesage stats

Print summary stats.

tracesage stats [--data-dir PATH] [--json]

Options:

  • --data-dir, -d PATH
  • --json — emit a single JSON object instead of human-readable key/value lines

Output: - total_runs — count of root runs - running / completed / failed — counts by status - avg_duration_ms — average across completed runs - total_tokens_input / total_tokens_output — sums - db_size_bytes — SQLite file size

tracesage runs

List root runs.

tracesage runs [OPTIONS]

Options:

  • --data-dir, -d PATH
  • --status STATUS — all | running | completed | failed (default all)
  • --limit, -l N — max rows (default 50)
  • --offset N — pagination offset
  • --tag TEXT — only runs whose tags contain this substring (filtered in SQL, so it composes correctly with --limit/--offset and the reported total)
  • --json — emit one JSON object per line (NDJSON)
tracesage runs --status failed --limit 20
tracesage runs --json | jq -r .run_id | head

tracesage gc

Enforce retention. Deletes oldest runs (and their blobs) beyond the cap.

tracesage gc [OPTIONS]

Options:

  • --data-dir, -d PATH
  • --max-runs N — keep at most N most-recent root runs (default 10000)
  • --max-blob-size-gb GB — after the run-count pass, also delete oldest runs until total blob size is under this many GB
  • --dry-run — print what would be deleted; no changes

Schedule via cron / systemd timer:

# /etc/cron.daily/tracesage-gc
tracesage gc --data-dir /var/lib/tracesage --max-runs 50000 --max-blob-size-gb 5

tracesage import

Inverse of export: read a JSONL export back into a data directory (creating it if needed). Useful for backups and moving runs between machines.

tracesage import [INPUT] [OPTIONS]

Options:

  • INPUT (positional) — JSONL file; alternative to --input
  • --data-dir, -d PATH — target data dir
  • --input, -i PATH — JSONL file, or - for stdin (default -)
tracesage export --all -o backup.jsonl
tracesage import --data-dir ~/.tracesage-restore -i backup.jsonl
tracesage import backup.jsonl                       # positional form

One malformed line is skipped with a warning rather than aborting the import.

tracesage doctor

Read-only diagnostics for a data directory: schema version, run counts, and orphan/missing-blob checks.

tracesage doctor [--data-dir PATH]

tracesage version

Print version.

tracesage version
# tracesage 0.3.0   (prints your installed version)