> ## Documentation Index
> Fetch the complete documentation index at: https://traceroot.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Started

> Bring TraceRoot to your terminal

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`](https://github.com/traceroot-ai/traceroot-cli) repo.

## Install

```bash theme={null}
npm install -g traceroot-cli
```

## Authenticate

```bash theme={null}
traceroot login
```

This validates your project API key and saves it locally, so later commands need no flags. Create API keys in [TraceRoot Cloud](https://app.traceroot.ai) or your [self-hosted](/developer/self-hosting) dashboard.

For CI or scripts, set environment variables instead — the same ones the SDKs use:

```bash .env theme={null}
TRACEROOT_API_KEY=tr_...
TRACEROOT_HOST_URL=https://app.traceroot.ai
```

Confirm the credentials resolve to the right place:

```bash theme={null}
traceroot status
```

## Inspect and export traces

```bash theme={null}
# 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
```

## 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`. |

## What's next

<CardGroup cols={2}>
  <Card title="Tracing" icon="route" href="/tracing/get-started">
    Instrument your app so traces show up for the CLI to read.
  </Card>

  <Card title="TraceRoot Cloud" icon="cloud" href="https://app.traceroot.ai">
    Create API keys and open traces in the web app.
  </Card>
</CardGroup>