Skip to main content
The traceroot CLI sets up tracing in your repository with one command, then lets you work with your project from the terminal — traces, detector findings, alerts, dashboards, evaluations, and SQL — and pipe the JSON into whatever comes next. It is built for AI coding agents and power users who prefer the command line. Full source and reference live in the traceroot-cli repo.

Set up a repository

Run this from the root of the repository you want to trace:
Setup signs you in, has your coding agent add the traceroot SDK, and waits for your first trace; no install or sign-in needed first. Tracing covers each step, self-hosting, and troubleshooting.

Run without prompts

Setup never prompts when it isn’t attached to a terminal, when CI is set to anything but empty or false, or with --no-input or --json. Pass what it would otherwise ask for:
A project API key also sets the project. Without a key, run 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 through npx, as above. To keep the traceroot command, install the CLI globally:
The examples below use 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)

Run traceroot login to sign in through your browser:
It prints a URL and a code, tries to open your browser, and saves a session to ~/.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-...):
This validates the key against the API and saves it to ./.traceroot/config.json.
.env
The CLI resolves credentials in this order:
  1. --api-key flag
  2. --env-file <path>
  3. TRACEROOT_TOKEN environment variable
  4. Credentials file (~/.config/traceroot/credentials.json)
  5. TRACEROOT_API_KEY environment variable
  6. Config file (./.traceroot/config.json)
  7. Auto-discovered ./.env — a TRACEROOT_API_KEY here selects key mode when nothing above it is set
Create API keys in traceroot Cloud or your self-hosted dashboard.

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 as traces 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:
Set 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) and full (core,usage,io,metadata)
So --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.
See From the terminal for what each read shows, and for the dataset commands.

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.