CLI

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

chmod +x retrace && sudo mv retrace /usr/local/bin/

retrace version

retrace auth login --key rt_live_your_key_here

retrace auth login

export RETRACE_API_KEY=rt_live_your_key_here
retrace traces list

retrace auth whoami    # Show authenticated user, email, plan
retrace auth status    # Show auth method, API URL, session expiry
retrace auth logout    # Clear all stored credentials

# List recent traces
retrace traces list
retrace traces list --limit 50 --status completed
retrace traces list --project <project_id> --json

# Inspect a trace
retrace traces get <trace_id>
retrace traces get <trace_id> --spans    # Include span details
retrace traces get <trace_id> --json     # Machine-readable output

# Delete a trace
retrace traces delete <trace_id> --force

# Create a fork from a specific span
retrace forks create --trace <trace_id> --span <span_id> --input "modified prompt"

# Replay a fork (re-execute the agent)
retrace forks replay <fork_id>
retrace forks replay <fork_id> --wait    # Wait for completion

# Compare original vs fork
retrace forks diff <fork_id>
retrace forks diff <fork_id> --json

# Run an evaluation on one or more traces
retrace eval run --evaluation <eval_id> --traces <trace_id_1>,<trace_id_2>

# CI/CD quality gate
# Exits with code 0 if score >= threshold, code 1 if below
retrace eval gate --evaluation <eval_id> --trace <trace_id> --threshold 0.8

# GitHub Actions example
- name: Quality Gate
  run: retrace eval gate --evaluation $EVAL_ID --trace $TRACE_ID --threshold 0.8
  env:
    RETRACE_API_KEY: ${{ secrets.RETRACE_API_KEY }}

# List your published tapes
retrace tapes list
retrace tapes list --json

# Publish a trace as a shareable tape
retrace tapes publish --trace <trace_id>
retrace tapes publish --trace <trace_id> --title "My Agent Run"

# Semantic search across all traces and spans
retrace search "error in payment processing"
retrace search "timeout" --limit 20
retrace search "user authentication" --json

# Show current configuration
retrace config show

# Set configuration values
retrace config set api_url https://api.retraceai.tech
retrace config set output json      # table | json | plain
retrace config set project_id <id>

# Update to the latest version
retrace update

# Check for updates without installing
retrace update --check

# Stream spans in real-time (WebSocket)
retrace traces tail

# Filter by span type
retrace traces tail --span-type llm_call

# Filter by trace name
retrace traces tail --name "my-agent"

# Auto-refresh traces list every 5 seconds
retrace traces list --watch 5

# Watch mode works on all list commands
retrace tapes list --watch 10
retrace sessions list --watch 5
retrace guardrails list --watch 30

# Browse trace spans in a full-screen terminal UI
retrace traces get <id> --interactive

# Navigate with arrow keys, q to quit

# Preview traces matching filters
retrace traces bulk-delete --status failed

# Delete all failed traces (requires --force)
retrace traces bulk-delete --status failed --force

# Filter by name pattern
retrace traces bulk-delete --name "test-" --force

# Pretty table (default)
retrace traces list

# JSON output (for scripting)
retrace traces list --json | jq '.[].name'