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

# CLI

> Drive Tracks from your terminal, a script or a coding agent

`tracks` calls the [Tracks API](https://docs.tracks.alpic.ai/api/overview.md) from your terminal. Commands that return data print it as JSON, so their output can be piped to `jq`, read by a script or by a coding agent.

## Install

It needs Node.js 24 or later.

```bash theme={null}
npm install --global @alpic-ai/tracks
```

Or prefix commands with `npx @alpic-ai/tracks` instead of `tracks`.

## Authenticate

Create an API key in **API keys** in the web app, then set it in your environment:

```bash theme={null}
export TRACKS_API_KEY=trk_...
tracks health
```

Every command reads it. The CLI reads two environment variables:

| Variable | Required | What it is |
| - | - | - |
| `TRACKS_API_KEY` | Yes | An API key of your organization, starting with `trk_` |
| `TRACKS_API_URL` | No | The API to call. Defaults to `https://tracks.alpic.ai/api` |

## Check the API is reachable

`tracks health` prints `ok` when the API answers. It doesn't check your key or your balance: the first command that needs them tells you, with `ApiKeyRefused` or `InsufficientBalance`.

## Output

* **stdout** gets the data, as JSON indented on several lines: a run, a page of events, an execution… Lists come as `{ "data": [...], "has_more": false }`, as in the API.
* `tracks runs follow` prints one JSON object per line instead, as the run goes.
* **stderr** gets progress and errors: the consent URL of `tracks connections create`, the counts of `tracks experiments launch --wait`, and what went wrong.

Commands that only act, such as `tracks experiments delete`, print nothing.

## Exit codes

| Code | When |
| - | - |
| `0` | The command did what it was asked |
| `1` | Something went wrong: the API refused the request, the network failed, a flag is wrong |
| `2` | The run or the experiment ended, but not as you required (see below) |

On an error, stderr gets one line, `<_tag>: <message>`, such as `ApiKeyRefused: Missing, malformed or revoked API key, or its organization is closed`. The `_tag` is the API's [error](https://docs.tracks.alpic.ai/api/overview.md#errors), or a network error. A missing argument or flag prints the command's help and the problem instead. Commands send each request once, except `--wait` and `--min-pass-rate`, which retry a check that fails on the network a few times before giving up. For `tracks runs create`, pass `--idempotency-key` so a retry of yours can't start a second run.

Two commands exit with `2` when the work didn't turn out as required, so a CI job can tell it from an error:

* `tracks runs follow` exits `2` when the run ended `failed`, `time_limit`, `budget_exceeded` or `canceled`, and `0` when it `completed` or ended after its idle timeout.
* `tracks experiments launch --min-pass-rate 80` exits `2` when the execution's pass rate ends below 80%, or no run was judged. See [Run from CI](https://docs.tracks.alpic.ai/guides/run-from-ci.md).

## Commands

`tracks --help`, `tracks <group> --help` and `tracks <group> <command> --help` list every command and flag.

> **[tracks runs](https://docs.tracks.alpic.ai/reference/cli/runs.md)**
>
> Start runs, follow them and read their results.

> **[tracks experiments](https://docs.tracks.alpic.ai/reference/cli/experiments.md)**
>
> Create, update and launch experiments.

> **[tracks executions](https://docs.tracks.alpic.ai/reference/cli/executions.md)**
>
> Read an execution's results and its slots.

> **[tracks library](https://docs.tracks.alpic.ai/reference/cli/library.md)**
>
> List what experiments can give agents.

> **[tracks connections](https://docs.tracks.alpic.ai/reference/cli/connections.md)**
>
> Connect MCP servers that need your account.

## Use it from a coding agent

Tracks publishes a [skill](https://docs.tracks.alpic.ai/skill.md) that teaches a coding agent, such as Claude Code, to drive the CLI. Save it in a project, or in your home directory for every project:

```bash theme={null}
mkdir -p .claude/skills/tracks
curl -o .claude/skills/tracks/SKILL.md https://docs.tracks.alpic.ai/skill.md
```

See [Use from your agent](https://docs.tracks.alpic.ai/use-from-your-agent.md) for other agents and for the MCP server.


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