---
title: "Trace an agent CLI · Ataris docs"
description: "Put ataris in front of Claude Code, Codex, or Grok to trace it on a laptop, in CI, or in your own sandbox."
canonical: "https://ataris.dev/docs/guides/cli"
last-updated: 2026-10-12
---
# Trace an agent CLI

Put ataris in front of Claude Code, Codex, or Grok to trace it on a laptop, in CI, or in your own sandbox.

The `ataris` CLI traces an agent CLI where it already runs: on your laptop, in CI, on a VM, or inside a sandbox or container you use today. Put `ataris` in front of the command. There is no tracing code to add, it needs no root, and it works on every plan.

It supports **Claude Code**, **Codex**, and **Grok**.

Install it with `curl -fsSL https://ataris.dev/install | sh` on macOS and Linux, or `irm https://ataris.dev/install.ps1 | iex` on Windows. See the [quickstart](/docs/quickstart#2-install-the-cli).

## Run an agent through the CLI

Create a workspace API key under **Settings → API keys**, then run the agent as you normally would, with `ataris` in front:

```bash
export ATARIS_API_KEY=atk_...

ataris claude -p "Fix the failing tests"
ataris codex exec "Upgrade the dependencies"
```

The CLI prints the session it created, runs the agent, and finishes the session with the agent's exit status. The run appears under **Sessions**, tagged `source:cli`.

| Option | Description |
| --- | --- |
| `--tag <key:value>` | Tag the session. Repeatable. See [Tags and missions](/docs/concepts/agents). |
| `--agent <name>` | Shorthand for `--tag name:<name>`. |
| `ATARIS_API_KEY` | Workspace API key. Required. |
| `ATARIS_API_URL` | API base URL. Defaults to `http://localhost:4001`. |
| `ATARIS_TAGS` | Extra tags, comma-separated. |

`ataris`'s own options come before the agent command; everything after it is passed to the agent unchanged.

## What gets recorded

On macOS and Linux, without root, the CLI records every process the agent starts, every file it opens, every network connection it makes, and every credential it touches, including inside the commands and scripts it runs. Some agent configurations record tool calls only; the session shows which.

Each tool call the agent makes becomes trace events:

| The agent | Event |
| --- | --- |
| Decides to call any tool | `decision.tool_use` on the `model` lane |
| Runs a shell command | `process.exec` on the `process` lane |
| Reads, writes, or edits a file | `file.open` on the `files` lane |
| Fetches a URL | `http.request` on the `network` lane |
| Calls an MCP tool (`mcp__<server>__<tool>`) | `decision.tool_use`, listed under the run's MCP servers |
| Loads a skill | Its `Skill` call and the `SKILL.md` read, listed under the run's skills |
| Gets a tool's result | `context.ingest` on the `context` lane |

The session page lists the **skills** the agent loaded and the **MCP servers and tools** it called, next to the timeline.

The CLI doesn't record the model's own text, only the prompt that started the run and each decision to call a tool.

## Run it in CI

Install the CLI in the job and put `ataris` in front of the agent. Keep `ATARIS_API_KEY` in your CI secrets.

```bash
curl -fsSL https://ataris.dev/install | sh
export PATH="$HOME/.local/bin:$PATH"

ataris --agent test-fixer claude -p "Fix the failing test"
```

The CLI exits with the agent's exit code, so the step passes or fails on the agent's result.

## Run it in your own sandbox

If you already run agents in a sandbox or container, add the `ataris` binary to its image and run the agent through it, the same way you would on a laptop. The sandbox needs outbound HTTPS to your Ataris API and `ATARIS_API_KEY` in its environment.

```bash
RUN curl -fsSL https://ataris.dev/install | ATARIS_INSTALL_DIR=/usr/local/bin sh
```

It runs inside the sandbox as an ordinary user, with no root.

## Policies

On Pro and above, the CLI checks each tool call against your [policies](/docs/concepts/policies) before it runs, and refuses the ones a rule blocks. The agent is told the call was blocked and why, and the attempt is recorded as `blocked`.