Sharing from the CLI

Use traces share to upload sessions with control over visibility, agent filtering, and output format.

The traces share command uploads a local coding session and returns a shareable URL.

Quick start

# Share the most recent trace in the current directory
traces share --cwd .

# Share with an API key (no login required)
traces share --cwd . --key trk_your_api_key_here

# Or use the environment variable
TRACES_API_KEY=trk_your_api_key_here traces share --cwd .

Flag reference

Flag	Description
`--trace-id ID`	Share a specific trace by its ID
`--source-path PATH`	Share by source file path
`--cwd DIR`	Share the most recent trace in a directory
`--agent ID`	Filter by agent identifier, or `auto` to detect
`--visibility MODE`	`public`, `direct`, or `private`
`--key KEY`	Authenticate with an API key (`trk_*`)
`--json`	Output machine-readable JSON
`--follow`	Keep syncing after the initial upload
`--list`	List available traces instead of sharing

The selectors --trace-id, --source-path, and --cwd are mutually exclusive -- exactly one is required (unless using --list).

Visibility

Every trace has a visibility level set at share time.

Level	Who can view	Listed in feeds	Default for
`public`	Anyone	Yes	--
`direct`	Anyone with the link	No	Individual namespaces
`private`	Namespace members only	No	Organization namespaces

# Public -- discoverable in feeds and search
traces share --cwd . --visibility public

# Direct -- shareable link, not indexed
traces share --cwd . --visibility direct

# Private -- namespace members only
traces share --cwd . --visibility private

Choosing the right level:

public -- Open source work, tutorials, community sharing
direct -- Sharing a link in Slack, a PR comment, or with a teammate
private -- Proprietary code, internal debugging, CI on private repos

Session resolution

When you use --cwd, the CLI resolves which trace to share using this priority chain:

TRACES_CURRENT_TRACE_ID env var -- exact trace ID
TRACES_CURRENT_SOURCE_PATH env var -- exact source file
TRACES_CURRENT_AGENT env var -- agent hint
Directory matching -- most recent trace matching --cwd
Agent-latest fallback -- most recent trace for --agent

Examples

Filter by agent

traces share --cwd . --agent claude-code
traces share --cwd . --agent auto

Available agent IDs: claude-code, cursor, opencode, codex, gemini-cli, pi, amp, cline, copilot.

Machine-readable output

traces share --cwd . --json

{
  "ok": true,
  "data": {
    "traceId": "abc123",
    "sharedUrl": "https://www.traces.com/s/abc123",
    "visibility": "direct",
    "agentId": "claude-code"
  }
}

Follow mode

Keep the trace synced as the session continues:

traces share --cwd . --follow

Press Ctrl+C to stop. New messages appear in real time.

List available traces

traces share --list
traces share --list --cwd ~/my-project
traces share --list --agent claude-code

Authentication

# Auth precedence: --key > stored login > TRACES_API_KEY env var
traces share --cwd . --key trk_abc123
TRACES_API_KEY=trk_abc123 traces share --cwd .

Sharing from the CLI

On this page