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 transfer <id> --to <slug>`	Move a trace to another namespace
`traces share`	Share a trace
`traces setup`	Install agent sharing setup and hooks
`traces list`	List traces without the TUI
`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

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

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

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

traces transfer abc123 --to my-org

Moves a trace to another namespace you have access to.

Browsing

`traces` (no arguments)

Opens the interactive TUI for browsing and viewing traces.

`traces list`

traces list
traces list --limit 20
traces list --agent claude-code
traces list --json
traces list --diagnostics

Flag	Description
`--limit N`	Number of traces to return
`--agent ID`	Filter by agent
`--json`	JSON output
`--diagnostics`	Include diagnostic metadata

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 from the CLI for full details.

Setup and maintenance

`traces setup`

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

See Sharing from an Agent for full setup details.

`traces doctor`

traces doctor

Checks authentication, database integrity, agent detection, 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

`traces uninstall`

traces uninstall

Removes the traces binary from your system.

Commands

On this page