Commands

Complete reference for the current opentraces CLI surface.

Public Commands

Authentication

opentraces login

Authenticate with Hugging Face Hub.

opentraces login --token
opentraces login

Recommended: Use opentraces login --token with a write-access PAT from huggingface.co/settings/tokens. The browser OAuth flow (opentraces login without --token) authenticates your identity but cannot create or push to dataset repos.

opentraces logout

Clear stored Hugging Face credentials.

opentraces auth

Authentication subcommands:

opentraces auth status
opentraces auth login
opentraces auth logout

Project Setup

opentraces init

Initialize opentraces in the current project directory. Creates .opentraces/config.json, .opentraces/staging/, and the Claude Code hook. If Claude Code already has session files for this repo, the interactive flow can import that backlog into the inbox immediately.

opentraces init
opentraces init --review-policy review --start-fresh
opentraces init --review-policy auto --import-existing
opentraces init --review-policy review --remote your-name/opentraces --start-fresh

--mode is a legacy alias kept for compatibility.

init also installs the opentraces skill into .agents/skills/opentraces/ and symlinks it into the selected agent's skill directory (e.g., .claude/commands/opentraces/ for Claude Code).

opentraces remove

Remove the local .opentraces/ inbox and Claude Code hook from the current project.

opentraces upgrade

Upgrade the CLI and refresh the skill file and session hook in the current project.

opentraces upgrade              # upgrade CLI + refresh skill and hook
opentraces upgrade --skill-only # just refresh the skill file and hook

Detects the install method (pipx, brew, pip, source) and runs the appropriate upgrade command. Then re-copies the latest skill file into .agents/skills/opentraces/ and updates the session hook.

opentraces config show

Display the current user config with secrets masked.

opentraces config set

Update configuration values.

opentraces config set --exclude /path/to/client-project
opentraces config set --redact "INTERNAL_API_KEY"

Inbox and Review

opentraces web

Open the browser inbox UI. This serves the React viewer from web/viewer/ through the local Flask app.

opentraces web
opentraces web --port 8080
opentraces web --no-open

opentraces tui

Open the terminal inbox UI.

opentraces tui
opentraces tui --fullscreen

opentraces session

Fine-grained review commands for staged traces.

opentraces session list
opentraces session show <trace-id>
opentraces session show <trace-id> --verbose
opentraces session commit <trace-id>
opentraces session reject <trace-id>
opentraces session reset <trace-id>
opentraces session redact <trace-id> --step 3
opentraces session discard <trace-id> --yes

session list accepts --stage inbox|committed|pushed|rejected, --model, --agent, and --limit.

session show truncates step content to 500 chars in human output by default to protect context windows. Pass --verbose to see full content, or use opentraces --json session show <id> to get the complete record as JSON (never truncated).

Upload

opentraces commit

Commit inbox traces into a commit group for upload.

opentraces commit --all
opentraces commit -m "Fix parser and update schema"

opentraces push

Upload committed traces to Hugging Face Hub as sharded JSONL files.

opentraces push
opentraces push --private
opentraces push --public
opentraces push --publish
opentraces push --gated
opentraces push --assess
opentraces push --repo user/custom-dataset

--approved-only is not part of the current CLI. The public path is commit -> push.

opentraces assess

Run quality assessment on committed traces or a full remote dataset.

opentraces assess
opentraces assess --judge
opentraces assess --judge --judge-model sonnet
opentraces assess --limit 50
opentraces assess --all-staged
opentraces assess --compare-remote
opentraces assess --dataset user/my-traces

By default, assess targets only committed traces, matching the population that push would upload. Use --all-staged to include traces that are staged but not yet committed.

--dataset is independent of the local inbox. It downloads shards from the specified HF dataset repo and updates that repo's dataset card and quality.json sidecar in place, without requiring a new push.

opentraces import-hf

Import traces from a HuggingFace dataset into your local inbox.

opentraces import-hf DATASET_ID [OPTIONS]

Exit codes: 0 success, 1 partial failure (some traces rejected by quality gate).

opentraces hooks install

Install Claude Code session capture hooks into the current project. Hooks run automatically at session end (on_stop) and after context compaction (on_compact) to enrich traces with session metadata.

opentraces hooks install

Run this once per project after opentraces init.

opentraces remote

Manage the configured dataset remote.

opentraces remote
opentraces remote set owner/dataset
opentraces remote set owner/dataset --private
opentraces remote set owner/dataset --public
opentraces remote remove

opentraces status

Show the current project inbox, counts, review policy, agents, and remote.

opentraces log

List uploaded traces grouped by date. Shows trace IDs, timestamps, models used, and step counts for traces that have been pushed to the remote.

opentraces log

opentraces stats

Show aggregate counts, token totals, estimated cost, model distribution, and stage counts for the current inbox. Useful for understanding your contribution volume and cost breakdown.

opentraces stats

opentraces context

The agent's "what should I do next?" command. Returns project config, auth status, counts per stage, and a suggested_next command. Start here when resuming work or when uncertain about state.

opentraces context
opentraces --json context

Machine-Readable Output

Add --json to any command to suppress human-readable text and get structured JSON only:

opentraces --json context
opentraces --json session list --stage inbox
opentraces --json push

JSON is emitted after the sentinel line ---OPENTRACES_JSON---. When parsing programmatically, split on this sentinel and parse the text that follows.

Every JSON response includes:

CI / headless / agent mode

When stdout is not a TTY, bare opentraces prints help text instead of launching the TUI. You can also force this explicitly:

OPENTRACES_NO_TUI=1 opentraces    # always prints help, never opens TUI

HF_TOKEN is also respected as the highest-priority credential source, so CI pipelines can authenticate without running opentraces login.

Hidden and Internal Commands

These commands exist for automation, compatibility, or diagnostics and are hidden from normal help output:

Exit Codes