Get Started

The TraceRoot CLI wraps the TraceRoot API so you can work with your project directly from the terminal — list, inspect, and export traces, then 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.

Install

npm install -g traceroot-cli

Authenticate

traceroot login

This validates your project API key and saves it locally, so later commands need no flags. Create API keys in TraceRoot Cloud or your self-hosted dashboard. For CI or scripts, set environment variables instead — the same ones the SDKs use:

.env

TRACEROOT_API_KEY=tr_...
TRACEROOT_HOST_URL=https://app.traceroot.ai

Confirm the credentials resolve to the right place:

traceroot status

Inspect and export traces

# List recent traces, newest first
traceroot traces list --limit 10

# Inspect one: span tree, duration, I/O preview, and a link to open it in TraceRoot
traceroot traces get <trace-id>

# Write a full trace bundle to disk to share or feed into another tool
traceroot traces export <trace-id> --output ./my-trace

Read evaluations

The CLI also reads your offline evaluations — the datasets you run against and the runs that scored them, so a run id no longer has to come from the web app.

# Which evaluations exist, and how each one's latest run ended
traceroot evals list

# One evaluation's runs, newest first — the RUN ID column is what you read next
traceroot evals runs list --evaluation-id <evaluation-id>

# One run: its counts, per-scorer means, and per-case cost and duration
traceroot evals runs get <run-id>

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.

Command	What it does
`login`	Validate an API key and save credentials.
`status`	Show the identity your credentials resolve to — workspace, project, host, and key hint.
`traces list`	List traces for your project, newest first. Flag: `--limit <n>`.
`traces get <id>`	Show one trace: header, span tree, duration, and I/O preview. `--json` emits the full trace.
`traces export <id>`	Write `trace.json`, `spans.json`, `git_context.json`, and a `manifest.json` index to a directory. Flags: `--output <dir>`, `--force`.
`datasets list`	List the project’s evaluation datasets, newest first. Flags: `--limit <n>`, `--name <substring>`.
`datasets get <dataset-id>`	Show one dataset and the version its cases are read from.
`datasets versions list <dataset-id>`	List a dataset’s published versions with their case counts. Flag: `--limit <n>`.
`datasets versions get <version-id>`	Show one version and a page of its cases. Flag: `--limit <n>` — 200 by default, up to 1000.
`evals list`	List evaluations with their run count and latest run. Flags: `--limit <n>`, `--name <substring>`.
`evals runs list`	List evaluation runs, newest first. Flags: `--limit <n>`, `--evaluation-id <id>`, `--status <status>`.
`evals runs get <run-id>`	Show one run: counts, per-scorer means, per-case cost and duration, and its URL.

What’s next

Tracing

Instrument your app so traces show up for the CLI to read.

Evaluations from the Terminal

Read datasets, evaluations, and past runs.

TraceRoot Cloud

Create API keys and open traces in the web app.

Overview

Tracing

AI Agents

Detectors

Evaluations

CLI

Install

Authenticate

Inspect and export traces

Read evaluations

Command reference

What’s next

Tracing

Evaluations from the Terminal

TraceRoot Cloud

​Install

​Authenticate

​Inspect and export traces

​Read evaluations

​Command reference

​What’s next

Tracing

Evaluations from the Terminal

TraceRoot Cloud

Install

Authenticate

Inspect and export traces

Read evaluations

Command reference

What’s next