retrace

Your AI agent traces,straight from the terminal.

Install once and drive Retrace without leaving your shell — list and inspect traces, fork and replay runs, gate deploys on evaluations, and publish shareable tapes.

$
curl -fsSL https://retraceai.tech/install.sh | sh
Read the docs

What it does

Traces & sessions

List, filter, and inspect every recorded run with full span detail — table or JSON, piped straight into your tools. Group related runs into sessions and walk their multi-agent execution graph.

$ retrace traces get tr_8a2 --spans

Fork & replay

Branch from any span, change the input, and re-execute the agent. Diff the original against the new path.

Eval gates

Score a trace against an evaluation and fail the command below your threshold — a CI quality gate in one line.

Live streaming

Tail spans in real time over WebSocket, filter by type or name, and auto-refresh any list command.

Guardrails & tapes

Manage runtime guardrails, review what they caught, and publish any trace as a shareable tape.

Semantic search

Search across every trace and span by meaning, not just keywords — find the run you remember in seconds.

From zero to first trace

  1. 01

    Install

    One command — auto-detects your OS and architecture.

    $ curl -fsSL https://retraceai.tech/install.sh | sh
  2. 02

    Authenticate

    Sign in with an API key, or run it bare for a browser login.

    $ retrace auth login --key rt_...
  3. 03

    Inspect

    List your most recent runs and open one in full detail.

    $ retrace traces list --limit 10

Common commands

Search commands⌘K
$ retrace traces list --limit 20

Recent traces, newest first

$ retrace traces get <id> --spans

Full trace with span detail

$ retrace forks replay <id> --wait

Re-execute a fork, wait for the result

$ retrace eval gate --trace <id> --threshold 0.8

Block a deploy on quality

$ retrace search "payment timeout"

Semantic search across runs

$ retrace tapes publish --trace <id>

Share a run as a tape

6 commands⏎ run⌘C copy

Run retrace --help for the full reference, or read the documentation.

Built for CI

retrace eval gate exits non-zero when a trace scores below your threshold, so a regression fails the job. Drop it straight into a workflow.

.github/workflows/eval.yml
name: Eval gate
on: [pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - name: Gate on evaluation score
        run: retrace eval gate --evaluation $EVAL_ID --trace $TRACE_ID --threshold 0.8
        env:
          RETRACE_API_KEY: ${{ secrets.RETRACE_API_KEY }}

Prefer offline checks? retrace ci replay diffs a golden cassette with no live model calls — see CI/CD.

FAQ

Which platforms are supported?

macOS (Apple Silicon and Intel), Linux (x86_64 and ARM64), and Windows (x86_64). The install script picks the right binary for your OS and architecture automatically.

How do I authenticate in CI?

Set the RETRACE_API_KEY environment variable. It takes priority over stored credentials, so no interactive login is needed in a pipeline.

Where are my credentials stored?

In your operating system keyring — macOS Keychain, Windows Credential Manager, or the Linux Secret Service. Browser login and API-key login both use it.

Is the output scriptable?

Yes. Every list and get command supports --json, so you can pipe results straight into jq and other tools.

How do I keep the CLI up to date?

Run retrace update to upgrade in place, or retrace update --check to see whether a newer version is available without installing it.

Where is configuration stored?

In ~/.retrace/config.toml. Use retrace config set to change the API URL, the default output format, or the active project.

Install in one line. Stay in your terminal.

The Retrace CLI brings tracing, forking, evaluation gates, and tapes to the command line — scriptable, pipeable, and built for CI.

$
curl -fsSL https://retraceai.tech/install.sh | sh
Visit retrace