Skip to main content
tracks calls the Tracks API 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.
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:
Every command reads it. The CLI reads two environment variables:

​
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

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

​
Commands

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

tracks runs

Start runs, follow them and read their results.

tracks experiments

Create, update and launch experiments.

tracks executions

Read an execution’s results and its slots.

tracks library

List what experiments can give agents.

tracks connections

Connect MCP servers that need your account.

​
Use it from a coding agent

Tracks publishes a skill 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:
See Use from your agent for other agents and for the MCP server.