CLI

CLI Discovery

Browse traces from your repo's git history without manual imports.

The CLI can discover traces linked to a repo through git notes and the API.

Reading trace notes

traces notes --json

Returns trace IDs and shared URLs from refs/notes/traces on recent commits. This is the starting point for any workflow that needs to find traces associated with a repo.

traces notes --json --limit 50    # scan more commits
traces notes --json --cwd /path   # different repo

Viewing trace content

traces show <id> --json           # from local store
traces show <id> --json --remote  # fetch from API
traces show <id> --markdown       # fenced markdown for agent context

The --remote flag fetches the trace from the API when it isn't available locally. The --markdown flag renders events wrapped in random boundary tags with a preamble marking the content as historical, designed for safe injection into AI agent context windows.

Syncing full content

traces sync <externalId>

Downloads messages and parts from the API and stores them locally. The trace then appears in the TUI with its complete conversation history.

URL normalization

Git remote URLs are normalized to a canonical HTTPS form before querying the API. SSH (git@github.com:org/repo.git) and HTTPS (https://github.com/org/repo.git) clones of the same repo will match correctly. This works across GitHub, GitLab, Bitbucket, and self-hosted instances.

Requirements

  • Git hooks installed in the repo (so notes are present) -- see Sharing via Git Hooks
  • Traces have been shared (so the API can return them)

On this page