traceroot-cli repo.
Set up a repository
Run this from the root of the repository you want to trace:Run without prompts
Setup never prompts when it isn’t attached to a terminal, whenCI is set to anything but empty or false, or with --no-input or --json. Pass what it would otherwise ask for:
npx -y traceroot-cli@latest login first, then run setup without --api-key. Login prints a URL and a code for a person to confirm in a browser, and waits, so a coding agent has to show them to you. If setup exits 10, it can’t choose for you, usually because you have several projects or none: follow the remedy it prints. With several projects, you can pass --project.
Without prompts, setup notes uncommitted changes instead of asking, and writes the instrumentation task to .traceroot/prompts/setup-instrument.md rather than running a coding agent. Pass --agent claude or --agent codex to run one. After the task is done and the application has run, rerun the same setup command with --resume, such as npx -y traceroot-cli@latest setup --no-input --resume, to get a link to the first trace. Coding agents has these steps as a prompt.
Install
Every command also runs throughnpx, as above. To keep the traceroot command, install the CLI globally:
traceroot. Without a global install, replace it with npx -y traceroot-cli@latest.
The CLI needs Node.js 20.3 or later, and setup needs 20.12 or later.
Authenticate
The CLI authenticates with either a browser login (the default interactive device flow) or a project API key (for CI environments and scripts).Browser login (default)
Runtraceroot login to sign in through your browser:
~/.config/traceroot/credentials.json. If no browser opens, open the URL yourself.
API key login (CI & scripts)
For CI pipelines, automated scripts, or headless environments, use a project API key (tr-...):
./.traceroot/config.json.
.env
--api-keyflag--env-file <path>TRACEROOT_TOKENenvironment variable- Credentials file (
~/.config/traceroot/credentials.json) TRACEROOT_API_KEYenvironment variable- Config file (
./.traceroot/config.json) - Auto-discovered
./.env— aTRACEROOT_API_KEYhere selects key mode when nothing above it is set
Verify credentials
Confirm your active identity:- Browser login: Displays your authenticated email address, host URL, active project (or a hint to select one), and accessible workspaces.
- API key login: Displays your workspace, project, host URL, and a masked key hint (e.g.
tr-d0a3-57e3).
Scope to a project
A browser login identifies you across your workspaces rather than binding to one project, and commands such astraces and evals are project-scoped, so pick a project first. An API key is already scoped to its project, so a key login can skip this step.
List the projects you can access to find your project ID:
TRACEROOT_PROJECT_ID so later commands need no extra flags, or pass --project <id> to individual commands:
Inspect and export traces
Once authenticated and scoped to a project, list, inspect, and export traces:Trace projections and field groups (--fields)
By default, traceroot traces get prints the trace header, an optional detector finding block, the span tree, and the web app URL.
When emitting JSON (--json), traceroot traces get defaults to the lightweight skeleton projection, leaving span input, output, and metadata as null to minimize payload size. Pass --fields to include specific data groups:
- Field groups:
core,usage,io,metadata - Aliases:
skeleton(core,usage) andfull(core,usage,io,metadata)
--fields full, or --fields io,metadata, includes span I/O in the JSON payload.
traceroot traces export instead defaults to the full projection, writing trace.json, spans.json, git_context.json, manifest.json, and finding.json (if flagged by a detector) into the destination directory. Pass --fields <groups> to narrow what is exported.
Read evaluations
The CLI also reads your offline evaluations: the datasets you run against and the runs that scored them.Command reference
Add--json to any command for machine-readable output, or run traceroot <command> --help for the full flag list.
The sql commands are documented in Read-only SQL.
Output and exit codes
With--json, a command writes one JSON document to stdout. If it fails, stdout is empty and stderr gets {"error":{"code":"...","message":"..."}}. doctor and setup doctor instead write their report to stdout and exit 1 if a check fails, and setup writes one JSON event per line, ending in a result event with ok and data.trace_url. Without --json, setup writes everything to stderr, including the link to your first trace.
Next steps
Tracing
Set up tracing with one command, or instrument by hand.
Evaluations from the Terminal
Read datasets, evaluations, and past runs.
traceroot Cloud
Create API keys and open traces in the web app.