Commands

Command overview

Command	Description
`traces`	Open the TUI to browse traces
`traces login`	Authenticate with GitHub
`traces logout`	Clear local credentials
`traces whoami`	Show current login status
`traces namespace list`	List your namespaces
`traces namespace use <slug>`	Switch active namespace
`traces namespace pin [slug]`	Pin a namespace for the current directory
`traces namespace unpin`	Remove the current directory namespace pin
`traces org new <name>`	Create an organization and switch to it
`traces org invite <slug> code`	Create an invite code for an organization
`traces <org-slug> invite code`	Shortcut for organization invites
`traces transfer <id> --to <slug>`	Move a trace to another namespace
`traces list`	List traces without the TUI
`traces search <pattern>`	Search local trace metadata and event text
`traces search-instructions`	Print list/search/show guidance for AI agents
`traces show <id>`	Show trace metadata or bounded event content
`traces sync <id>`	Download a remote trace into the local database
`traces notes`	Read trace IDs from git notes
`traces resume <id>`	Reopen a local trace in its native agent when available
`traces share`	Share a trace
`traces refresh --trace-id <id>`	Upload new events to an already-shared trace
`traces setup [skills]`	Install agent sharing setup for supported agents
`traces setup git`	Install git hooks for commit-to-trace links
`traces remove skills`	Remove installed agent sharing setup
`traces remove git`	Remove installed git hooks
`traces status`	Show local DB and auth status
`traces doctor`	Diagnose installation issues
`traces reset`	Delete local DB and optionally credentials
`traces upgrade`	Update to the latest version
`traces uninstall`	Remove the traces binary
`traces version`	Show version
`traces help`	Show CLI help

Authentication

traces login
traces login --no-browser  # prints URL for remote/SSH sessions

Opens your browser for GitHub OAuth device flow. The CLI stores a device token locally after authentication.

`traces logout`

traces logout

Revokes the server session and clears local credentials.

`traces whoami`

traces whoami

Shows your username, active namespace, and namespace type. Verifies credentials with the server.

Namespace management

`traces namespace list`

traces namespace list
traces ns ls  # alias

Lists all namespaces (personal and organizations) you belong to.

`traces namespace use <slug>`

traces namespace use my-org
traces namespace use @my-org

Switches the active namespace. All subsequent CLI operations target this namespace.

API keys are namespace-scoped, so namespace switching requires a user session from traces login.

`traces namespace pin [slug]`

traces namespace pin
traces namespace pin my-org
traces namespace pin @my-org

Writes a .tracesrc file in the current directory. Commands run in that directory tree use the pinned namespace automatically. Without a slug, the CLI pins your current active namespace.

`traces namespace unpin`

traces namespace unpin

Removes .tracesrc from the current directory. If the pin lives in a parent directory, run the command from that parent directory.

`traces transfer <id> --to <slug>`

traces transfer abc123 --to my-org

Moves a trace to another namespace you have access to.

Organization management

`traces org new <name>`

traces org new "Acme"
traces org new "Acme" --json

Creates a new organization namespace, makes you its first admin, and switches your active namespace to that org automatically.

`traces org invite <slug> code`

Shortcut: traces <org-slug> invite code

traces org invite acme code
traces org invite acme code --email jane@example.com --max-uses 1
traces org invite acme code --no-expiry
traces acme invite code --json

Creates an invite code for an organization you administer. The command prints the code, invite link, usage limit, and expiry timestamp.

Flag	Description
`--email EMAIL`	Attach an email hint to the invite
`--max-uses N`	Limit how many times the invite can be used (`0` = unlimited, `1` = single-use default)
`--no-expiry`	Create an invite that does not expire
`--json`	JSON output

You must be an org admin to create invite codes. Organization creation and invite creation require a logged-in user session and do not work with API keys.

Browsing, search, and discovery

`traces` (no arguments)

Opens the interactive TUI for browsing and viewing traces.

`traces list`

traces list
traces list @my-org
traces list --limit 20 --page 2
traces list --all
traces list --agent claude-code
traces list --dir .
traces list --since 1778000000000
traces list --json
traces list --diagnostics

Lists local traces by default. Pass @namespace to list/sync a remote namespace view.

Flag	Description
`@namespace`	List traces from a namespace view instead of only local traces
`--limit N`	Number of traces to return (default `100`)
`--page N`	Page through results when using `--limit`
`--all`	Return all matching traces (cannot be combined with `--page`)
`--agent ID`	Filter by agent
`--dir PATH`	Filter by project directory; sibling worktrees for the same repo also match
`--since MS`	Only return traces updated at or after a millisecond timestamp
`--json`	JSON output
`--diagnostics`	Include timing metadata

`traces search <pattern>`

traces search sidebar
traces search 'timeout|connection refused' --result-level event
traces search 'build failed' --event-type tool_result --tool bash
traces search database --scan-traces 1000 --scan-events-per-trace 100
traces search 'literal.*text' --literal --case-sensitive
traces search renderer --dir . --since 7d --json

Searches the local trace database. Patterns are case-insensitive regular expressions by default. Use --literal for fixed-string search.

Flag	Description
`--literal`	Treat the pattern as a fixed string instead of regex
`--case-sensitive`	Match case exactly
`--source trace,event`	Search trace metadata, saved event text, or both
`--event-type TYPES`	Filter event rows (`user_message`, `agent_text`, `agent_thinking`, `tool_call`, `tool_result`, `error`)
`--tool NAMES`	Filter `tool_call`/`tool_result` rows by tool name
`--result-level MODE`	Use `trace` to group matches or `event` to return event hits
`--trace-id ID`	Restrict search to one trace; comma-separated IDs are accepted
`--agent ID`	Restrict search to one local agent ID
`--dir PATH`	Restrict search to a directory/source path prefix
`--since 7d`	Relative time filter (`ms`, `s`, `m`, `h`, `d`, `w`; defaults to milliseconds)
`--after DATE`	Absolute lower time bound (date string or millisecond timestamp)
`--before DATE`	Absolute upper time bound (date string or millisecond timestamp)
`--limit N`	Limit returned matches
`--scan-traces N`	Search budget: number of candidate traces to scan
`--scan-events-per-trace N`	Search budget: number of event rows to scan per trace
`--json`	JSON output
`--diagnostics`	Include timing and output-size diagnostics
`--search-instructions`	Print the same guidance as `traces search-instructions`
`--help`, `-h`	Show search help

See Search Traces for workflow examples and guidance on keeping outputs small.

`traces search-instructions`

traces search-instructions
traces search --search-instructions

Prints agent-oriented guidance for using traces list, traces search, and traces show together. It is useful when you want an AI agent to inspect trace history without dumping large sessions into context.

`traces show <id>`

traces show abc123 --limit 40
traces show abc123 --around-event 63 --before 3 --after 4
traces show abc123 --event-type user_message,agent_text --offset 1 --limit 50
traces show abc123 --event-type tool_result --tool bash --offset 40 --limit 20
traces show abc123 --remote --json
traces show abc123 --markdown

Shows one trace. Plain output includes metadata; add a range/filter, --json, or --markdown to print event content.

Flag	Description
`--json`	JSON output
`--markdown`, `--md`	Render historical trace content as fenced markdown for agent context
`--remote`	Fetch from the API if the trace is missing locally or has no local events
`--offset N`	Start at event number `N`
`--limit N`	Limit returned events (default `40`, max `200` for bounded plain output)
`--around-event N`	Return events around event number `N`
`--before N`	Number of events before `--around-event` (default `5`)
`--after N`	Number of events after `--around-event` (default `10`)
`--event-type TYPES`	Filter event types
`--tool NAMES`	Filter tool calls/results by tool name
`--max-event-chars N`	Increase per-event truncation bound (max `10000`)

The --markdown output wraps the prior session in random boundary tags and marks it as historical context, not instructions.

`traces sync <id>`

traces sync abc123
traces sync abc123 --json

Downloads messages and parts for a remote trace from the API and stores them locally. Use this when a trace is visible on the web but not yet available in your local database.

`traces notes`

traces notes --json
traces notes --json --limit 50
traces notes --json --cwd /path/to/repo

Reads trace IDs and shared URLs from refs/notes/traces in git history. See CLI Discovery and Sharing via Git Hooks for the full workflow.

Flag	Description
`--json`	JSON output
`--limit N`	Number of recent commits to scan (default `20`)
`--cwd PATH`	Read notes from a different git repository

`traces resume <id>`

traces resume abc123
traces resume abc123 --json

Reopens a local trace in its native agent when an exact local session is available. Native resume is currently available in macOS builds only. Remote traces or traces without an exact native session return a continuation-required response instead of launching a new session.

traces share --cwd .
traces share --trace-id abc123
traces share --source-path ~/.claude/projects/session.jsonl
traces share --cwd . --agent claude-code --visibility public --json
traces share --cwd . --key trk_your_api_key --json
traces share --cwd . --follow
traces share --list

See Sharing via CLI for full details.

`traces refresh --trace-id <id>`

traces refresh --trace-id abc123
traces refresh --trace-id abc123 --json
traces refresh --trace-id abc123 --key trk_your_api_key

Uploads new events to a trace that has already been shared. Use traces share for the initial upload; use traces refresh to keep the same shared URL up to date after more agent activity.

Flag	Description
`--trace-id ID`	Local trace ID to refresh (required)
`--key TOKEN`	Authenticate with a bearer token/API key
`--json`	JSON output

Setup and maintenance

`traces setup [skills]`

traces setup
traces setup skills
traces setup skills --yes --agent claude-code --agent cursor
traces setup skills --global
traces setup skills --json

traces setup currently maps to traces setup skills.

Flag	Description
`--agent ID`, `--agents ID`	Install setup for one or more specific agents
`--yes`, `-y`	Skip confirmation prompts
`--global`, `-g`	Install in your home directory instead of the current project
`--json`	JSON output
`--help`, `-h`	Show setup help

`traces remove skills`

traces remove skills
traces remove skills --yes
traces remove skills --global
traces remove skills --json

Removes files and hook wiring installed by setup for the current project scope (default) or global scope (--global).

See Sharing via Agent Skills for full setup details.

`traces setup git`

traces setup git

Installs git hooks in the current repository so commits can link back to the traces that produced them. See Sharing via Git Hooks for details.

`traces remove git`

traces remove git

Removes git hooks installed by traces setup git from the current repository.

`traces doctor`

traces doctor

Checks authentication, database integrity, agent detection, agent hook installation, and API connectivity.

`traces status`

traces status

Shows local database location, authentication status, and active namespace.

`traces reset`

traces reset
traces reset --force     # skip confirmation
traces reset --all       # also clear credentials

Deletes the local database to force a full resync on next launch. With --all, also clears stored login credentials.

`traces upgrade`

traces upgrade
traces upgrade 0.5.0

Updates the CLI to the latest release or a specific version.

`traces uninstall`

traces uninstall

Removes the traces binary from your system.

`traces version`

traces version
traces --version
traces -v

Prints the installed CLI version.

`traces help`

traces help
traces --help
traces -h

Prints command help, global options, and environment variables.

Commands

On this page