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

# pi CLI

> Trace interactive pi sessions with the traceroot extension

Trace interactive [pi](https://pi.dev) sessions — turns, model calls, tool calls and token usage — with the [traceroot pi extension](https://github.com/traceroot-ai/traceroot-pi-extension).

> [!NOTE]
>
> Embedding pi in your own Node process with `@earendil-works/pi-coding-agent`? Use the [pi SDK](https://traceroot.ai/docs/integrations/pi.md) integration instead.

## Install

Requires Node.js 22.19 or later and pi 0.79 or later.

```bash theme={null}
pi install npm:@traceroot-ai/pi-extension
```

## Set up

Tracing is opt-in. Set these before starting pi, then restart pi:

```bash theme={null}
export TRACEROOT_ENABLED=true
export TRACEROOT_API_KEY="tr-..."
# Optional: only needed for self-hosted deployments
# export TRACEROOT_HOST_URL="https://your-traceroot.example.com"
```

| Setting | Env var | Default | Description |
| - | - | - | - |
| Enabled | `TRACEROOT_ENABLED` | `false` | Required. Turns tracing on. |
| API key | `TRACEROOT_API_KEY` | — | Required. |
| Host | `TRACEROOT_HOST_URL` | hosted service | Set only when self-hosting. |
| Capture content | `TRACEROOT_CAPTURE_CONTENT` | `true` | Send prompts and responses. `false` keeps only metadata. |
| Capture tool I/O | `TRACEROOT_CAPTURE_TOOL_IO` | `true` | Send tool arguments and results. |
| Debug | `TRACEROOT_PI_DEBUG` | `false` | Log to stderr. `TRACEROOT_LOG_FILE` writes a JSON-lines log. |

Inside pi, `/traceroot status` shows whether tracing is on and where it sends; `/traceroot disable` and `/traceroot enable` switch it for the current session.

## Usage

Use pi as usual. Each session becomes one trace, with one span per turn.

```
pi.session                   # one per session
├── pi.turn                  # one per prompt
│   ├── openai/gpt-…         # LLM span — tokens, cache, cost
│   │   ├── bash: …          # TOOL span — command and result
│   │   └── edit: …
└── pi.turn
```

## Verify

Run one prompt in pi and confirm the trace arrives:

1. **In the traceroot UI**: Navigate to **Tracing > Traces** in [traceroot Cloud](https://app.traceroot.ai). You should see a trace with root span `pi.session`.
2. **Via the CLI**: Run `traceroot traces list` to inspect your recent traces from the terminal.

## What gets captured

| Attribute | Description |
| - | - |
| Sessions | One trace per session; resumed and forked sessions are linked |
| Turns | One span per prompt, marked when interrupted |
| Model calls | Provider and model, prompt and response; errors and aborts marked |
| Tokens | Input, output, cache read and write counts, and cost |
| Tool calls | Tool name, arguments and result; failed tools marked |
| Compaction | Each compaction as a span on the session |

With content capture on, prompts and tool I/O are sent as they are. Nothing is redacted; set `TRACEROOT_CAPTURE_CONTENT=false` and `TRACEROOT_CAPTURE_TOOL_IO=false` to send metadata only. See [Data Capture and Privacy](https://traceroot.ai/docs/tracing/data-capture.md#what-is-captured-by-default).

## Limitations

* The exporter ignores `HTTPS_PROXY`, so exports can fail on proxy-only networks.
* If no trace arrives, run `/traceroot status` and set `TRACEROOT_PI_DEBUG=true` to log to stderr.

## Run the example

> [card] [traceroot-pi-extension](https://github.com/traceroot-ai/traceroot-pi-extension)
>
> Source and full settings

## Next steps

> [card] [pi SDK](https://traceroot.ai/docs/integrations/pi.md)
>
> Trace pi sessions you run from your own code.

> [card] [Data Capture and Privacy](https://traceroot.ai/docs/tracing/data-capture.md)
>
> Control what leaves your machine.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.