Commands

Reference for the current 0.3 opentraces CLI.

Root Command

opentraces [--json] <command> ...

Use --json on any command when you want machine-readable output instead of the TTY view.

The current public root commands are:

Three more commands are available but intentionally omitted from the default --help listing because they are advanced or typically driven by other surfaces: backfill (called by watcher and init --import-existing), git-backfill (retroactively correlates inbox traces to past commits after first install of the post-commit hook), and watcher (managed by setup watcher). All three are documented under Advanced Commands below.

Authentication

opentraces auth

opentraces auth whoami
opentraces auth login
opentraces auth logout

Subcommands:

• login starts the browser device flow by default
• login --token switches to the CI / headless flow and prompts for a PAT (the flag is a boolean, not a value)
• whoami reports the active HuggingFace identity
• logout clears the stored Hugging Face credential

opentraces auth login

opentraces auth login
opentraces auth login --token

Project Commands

opentraces init

opentraces init
opentraces init --review-policy review
opentraces init --review-policy auto
opentraces init --remote owner/my-traces --public
opentraces init --import-existing

Initializes the current repo, writes .opentraces.json, registers machine-local state under ~/.opentraces/projects/<slug>/, and installs the capture hook unless you pass --no-hook.

opentraces remove

opentraces remove
opentraces remove --all

Uninstalls the capture hook, deletes the .opentraces.json marker, unregisters the repo from the global registry, and removes the machine-local ~/.opentraces/projects/<slug>/ directory. Pushed datasets on Hugging Face are left untouched.

opentraces status

opentraces status
opentraces status --limit 0

Shows stage counts, the active remote, and recent traces (default limit 10).

Review And Inbox Commands

opentraces list

opentraces list
opentraces list --stage inbox
opentraces list --remote origin
opentraces list --projects
opentraces list --by-commit

Visible stages are inbox, staged, pushed, rejected, and blocked.

opentraces show

opentraces show <trace-id>
opentraces show <trace-id> --verbose
opentraces show <trace-id> --markdown

show prints the trace prompt, steps, tool calls, observations, and outcome. Human output truncates long step content unless you pass --verbose.

opentraces add

opentraces add <trace-id>
opentraces add abc12 def34
opentraces add --all

Stages Inbox traces for the next push.

add refuses blocked and rejected traces.

opentraces reject

opentraces reject <trace-id>

Marks a trace local-only so it will not be pushed.

opentraces reset

opentraces reset <trace-id>

Moves a trace back to Inbox.

opentraces redact

opentraces redact <trace-id> <pattern>
opentraces redact <trace-id> "ACME_INTERNAL_TOKEN"
opentraces redact <trace-id> "sk-[A-Za-z0-9]+" --regex
opentraces redact <trace-id> "secret" --field observations --step 3

Find and replace text in a stored trace. PATTERN is a required positional argument; without --regex it is treated as a literal string.

opentraces discard

opentraces discard <trace-id>
opentraces discard <trace-id> --yes

Permanently deletes the local trace.

opentraces web

opentraces web
opentraces web --port 6060 --no-open

opentraces tui

opentraces tui
opentraces tui --fullscreen
opentraces tui --limit 0

Push And Import

opentraces push

opentraces push
opentraces push --private
opentraces push --llm-review
opentraces push --repo owner/team-traces
opentraces push --no-assess

Uploads staged traces to Hugging Face Hub as a new shard.

opentraces pull

opentraces pull owner/dataset --parser hermes
opentraces pull owner/dataset --parser hermes --limit 10 --dry-run
opentraces pull owner/dataset --parser hermes --auto

Imports traces from a Hugging Face dataset.

opentraces export

opentraces export --format agent-trace
opentraces export --format atif
opentraces export --format atif --output /tmp/traces.jsonl

Exports staged traces to another format. If no traces are staged the command exits 0 with a notice and does not create the output file.

Quality And Security

opentraces assess

opentraces assess
opentraces assess --judge --judge-model sonnet
opentraces assess --dataset owner/team-traces
opentraces assess --explain

Local mode assesses staged traces, falling back to all local traces if nothing is staged yet.

opentraces llm-review

opentraces llm-review
opentraces llm-review --scope staged
opentraces llm-review --trace 8a3f1c
opentraces llm-review --dry-run

Runs Tier 2 semantic review using the provider configured by opentraces setup llm-review, unless you override it on the command line.

opentraces doctor

opentraces doctor
opentraces doctor --security

Checks configured integrations, versions, and security tiers. It exits non-zero when a required integration is broken.

For the LLM trace review tier, doctor also surfaces the active setup: backend and model, endpoint URL, API format, whether the configured api_key_env variable is set, and the probe result (e.g. model count, unreachable reason, or not found when the configured model is missing from the endpoint's catalog). Use this to confirm that opentraces setup llm-review wrote the expected values before running opentraces llm-review.

Remote Management

opentraces remote

opentraces remote list
opentraces remote list -v
opentraces remote add owner/dataset
opentraces remote create owner/team-traces --private
opentraces remote visibility owner/dataset --public
opentraces remote remove owner/dataset
opentraces remote remove owner/dataset --delete-remote --yes
opentraces remote delete owner/dataset --yes

Subcommands:

• add connects an existing dataset
• create creates a new dataset and connects it
• list shows connected remotes
• remove disconnects a remote locally
• delete deletes the remote dataset and disconnects it
• visibility flips a remote between private and public

Positional REPO is optional on remove and delete when exactly one remote is connected.

opentraces remote list

opentraces remote create

opentraces remote visibility

opentraces remote remove

opentraces remote delete

Configuration And Setup

opentraces config show

opentraces config show
opentraces --json config show

Shows the effective config with secrets masked.

opentraces config set

opentraces config set classifier_sensitivity high
opentraces config set custom_redact_strings ACME_INTERNAL_TOKEN --append
opentraces config set excluded_projects /path/to/repo --append
opentraces config set review_policy auto --project

Default scope is global.

opentraces setup

opentraces setup
opentraces setup claude-code
opentraces setup git
opentraces setup trufflehog
opentraces setup llm-review
opentraces setup review-policy --auto
opentraces setup upgrade

Current setup subcommands:

• claude-code installs the capture hooks
• entity-parser downloads and verifies the ot-entities binary
• git installs the post-commit correlator hook
• llm-review configures the Tier 2 reviewer
• review-policy changes the repo's review policy
• skill installs the opentraces skill globally
• trufflehog enables Tier 1.5 TruffleHog
• upgrade upgrades the CLI and refreshes project files
• watcher installs or removes the background attribution watcher

opentraces setup trufflehog

opentraces setup trufflehog
opentraces setup trufflehog --enable
opentraces setup trufflehog --disable

Tier 1.5 findings are redacted in place and force human review before push.

opentraces setup llm-review

opentraces setup llm-review
opentraces setup llm-review --api-format openai-compat --base-url http://localhost:11434/v1 --model gemma3n:e4b
opentraces setup llm-review --disable
opentraces setup llm-review --print

opentraces setup review-policy

opentraces setup review-policy --review
opentraces setup review-policy --auto
opentraces setup review-policy --print

--auto auto-approves safe traces into staged. Push remains explicit.

opentraces setup claude-code

opentraces setup claude-code
opentraces setup claude-code --dry-run
opentraces setup claude-code --remove

Installs (or removes) the Claude Code capture hooks into your Claude Code settings file.

opentraces setup entity-parser

opentraces setup entity-parser
opentraces setup entity-parser --force

Downloads and verifies the ot-entities binary used to expand function/class changes in blame and graph.

opentraces setup git

opentraces setup git
opentraces setup git --remove

Installs the post-commit correlator hook that attributes commits to traces.

opentraces setup skill

opentraces setup skill
opentraces setup skill --harness claude-code
opentraces setup skill --remove

Installs the opentraces skill so Claude Code (and compatible harnesses) can drive the CLI.

opentraces setup watcher

opentraces setup watcher
opentraces setup watcher --interval 600
opentraces setup watcher --no-install
opentraces setup watcher --uninstall

Installs (or removes) the background attribution watcher service. The watcher polls enlisted projects and runs backfill when new commits or Claude Code sessions appear.

opentraces setup upgrade

opentraces setup upgrade
opentraces setup upgrade --skill-only

Upgrades the opentraces CLI and refreshes project-side files (skill, hooks) where relevant.

Advanced Commands

The first commands in this section (blame, graph, resume, stats, log, completions) are part of the default --help listing. backfill, git-backfill, and watcher are not: they are real commands but are intentionally hidden from the default listing because they are usually driven by watcher, setup git, and setup watcher respectively.

opentraces blame

opentraces blame abc1234                          # Commit-mode (bare SHA)
opentraces blame c:abc1234 src/main.py            # Commit-mode, single file
opentraces blame abc1234 --lines                  # Per-line view
opentraces blame t:4dccb032                       # Trace-mode (canonical)
opentraces blame s:92437382 --include-overlapping # Trace-mode (upstream session)
opentraces blame abc1234 --json                   # Structured output

Two modes, one argument:

• Commit-mode (c:<sha> or bare SHA): which traces contributed to this commit. Uses the attribution cache for per-line detail and merges refs/notes/opentraces so hook-linked traces surface even when the attribution cache has no per-line data for that commit.
• Trace-mode (t:<trace-id>, s:<session-id>, or a bare hyphenated UUID): which commits carry this trace's output. Merges attribution-cache rows (fine-grained) with the trace's git_links (hook-linked). Hook-linked rows carry only a tier badge, not per-line counts.

Commit-mode requires a populated attribution cache — run opentraces backfill if empty. Trace-mode works from git_links alone, so it surfaces hook-linked commits even when per-line attribution hasn't been computed yet.

opentraces graph

opentraces graph
opentraces graph --limit 50
opentraces graph --trace abc12
opentraces graph --since HEAD~20 --until HEAD

Renders commit + trace history. Commit-primary by default: the git log is the spine and each commit shows the traces that touched it. Pass --trace <id> to pivot to trace-primary mode. Requires a populated attribution cache.

opentraces backfill

opentraces backfill
opentraces backfill --rebuild
opentraces backfill --dry-run

Backfills per-commit attribution into the local cache. Walks new commits since the last bookmark, correlates them to traces, and populates entity data when the ot-entities binary is available.

opentraces git-backfill

opentraces git-backfill
opentraces git-backfill --max-commits 2000 --window-hours 48
opentraces git-backfill --json

Retroactively correlates inbox traces to past commits. Useful after a first-time install of the post-commit hook (the hook only sees commits after install) or after a period where the hook failed silently. Walks first-parent history, re-runs the live correlator, writes refs/notes/opentraces, and persists git_links onto each trace's JSONL file. Safe to re-run: notes dedupe on append and git_links dedupe before rewrite.

opentraces watcher

opentraces watcher start
opentraces watcher start --interval 600 --no-install
opentraces watcher status
opentraces watcher status --json
opentraces watcher tick
opentraces watcher tick --project /path/to/repo --json
opentraces watcher stop
opentraces watcher restart
opentraces watcher uninstall

Manages the background attribution watcher service (installed by opentraces setup watcher). The watcher polls enlisted projects and runs incremental backfill when new commits or Claude Code sessions appear.

Subcommands: start, stop, restart, status, tick (one diagnostic pass), uninstall.

opentraces watcher start

opentraces watcher status

opentraces watcher tick

stop, restart, and uninstall take no flags beyond --help.

opentraces resume

opentraces resume <trace-id>
opentraces resume <trace-id> --dry-run
opentraces resume <trace-id> --at-step s42

Resumes the upstream agent session behind a trace. Accepts a full trace_id or a t:XX / XX prefix (2+ chars). For claude-code the command execs claude --resume <session_id>; other agents print the native resume command instead.

opentraces stats

opentraces stats

Rolls up every local trace into counts, token totals, cost estimates, and a model breakdown.

opentraces log

opentraces log
opentraces log --verbose
opentraces log --limit 0

Lists the recent traces that have been pushed, grouped by date. Only the pushed stage is walked, so in-progress Inbox or staged work is ignored.

Default output is one row per day with the push count, the destination remote(s), and the local time range of pushes:

2026-04-16  6 pushed   → origin   10:36–17:44
2026-04-15  1 pushed   → origin   11:42

--verbose / -v expands each day into per-trace rows with a short trace id, push time, model, and the first line of the task description, with total tokens and an estimated cost per day. The verbose view reads each trace file so it is slower on large inboxes:

2026-04-16  6 pushed   → origin   10:36–17:44   (430.7k tokens, ~$225.90)
  785ddc93  10:36  opus-4-6            fix(cli): restore opentraces log…   [62.6k tokens]
  2cfe7e14  10:36  opus-4-6            docs: audit commands reference      [203.0k tokens]
  …

opentraces completions

opentraces completions install
opentraces completions install zsh --alias otd
opentraces completions install zsh --alias otd --alias ot --quiet
opentraces completions uninstall
opentraces completions uninstall zsh --quiet

Prints or installs shell completion scripts. Both install and uninstall take an optional positional shell name (bash, zsh, or fish); if omitted, the current shell is detected automatically.

opentraces completions install

opentraces completions uninstall