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

# CLI reference

> The CLI's options, environment variables and files, what it tells Agentrail, and its exit codes.

## Options

Every command takes these.

| Option | What it does |
| - | - |
| `--workspace <id>` | The workspace to act in. See [Choose a workspace](https://agentrail.co/docs/cli/commands.md#choose-a-workspace). |
| `--json` | Print data as JSON. |
| `--no-update-check` | Skip today's check for a newer CLI. |
| `--help` | Show the command's options and inputs. |
| `--version` | Print the CLI's version. |

## Environment variables

| Variable | What it does |
| - | - |
| `AGENTRAIL_WORKSPACE` | The workspace to act in, when `--workspace` is not given. |
| `AGENTRAIL_NO_UPDATE_CHECK` | Set to any value that is not empty: skip the daily check for a newer CLI. `agentrail update` still checks. |
| `AGENT` | Set to any value that is not empty: print JSON, as inside a coding agent. |
| `DO_NOT_TRACK` | Set to any value but an empty one, `0` or `false`: tell Agentrail nothing about the command that ran. See [What Agentrail is told](#what-agentrail-is-told). |
| `AGENTRAIL_CLI_DEBUG` | Set to `1`: print what Agentrail is told about each request to stderr. |
| `XDG_CONFIG_HOME` | Where the CLI keeps its files. It is `~/.config` when not set. |

## Files

The CLI keeps its files in `agentrail` under `XDG_CONFIG_HOME`, so `~/.config/agentrail` by default, readable only by you:

* the sign-in, when you signed in with `--insecure-storage`. Otherwise it is in your operating system's keychain;
* a sign-in an agent started and has not finished;
* the list of commands Agentrail last sent, so help works when Agentrail cannot be reached;
* when it last checked npm for a newer CLI.

A workspace link is `.agentrail/link.json` in the directory you linked.

When neither a coding agent nor a CI run gives the CLI a session, it keeps its own in a file named `cli-session-<id>.json`, in an `agentrail` folder under `~/Library/Application Support` on macOS, `XDG_STATE_HOME` (`~/.local/state` by default) on Linux, or `%LOCALAPPDATA%` on Windows. If it cannot write there, it uses the temporary folder. See [What Agentrail is told](#what-agentrail-is-told).

## What Agentrail is told

Each request the CLI makes to Agentrail says:

* the command that ran, by its words, never its inputs;
* the run, and how many requests it has made;
* how the CLI was started: by a coding agent, in CI, in a terminal or from a script;
* the coding agent running it and the agent's version, when there is one, and the names, never the values, of the environment variables that showed it was an agent or CI;
* a session, as a one-way hash: the agent's own session, the CI run, or else the session the CLI keeps on this computer, which ends after 30 minutes without a command and lasts a day at most;
* the versions of the CLI and of the library that sends this.

This lets Agentrail tell the commands of one session from another's. It goes only to Agentrail's own servers.

Set `DO_NOT_TRACK=1` to send none of it and keep no session file. Every request still names the CLI's version, which Agentrail needs to tell you when your CLI is too old. Set `AGENTRAIL_CLI_DEBUG=1` to print what is sent, as it is sent.

## Exit codes

| Code | Meaning |
| - | - |
| 0 | Done |
| 1 | Agentrail refused: not found, not allowed, or invalid input |
| 2 | The command line, or a file of yours it reads, is wrong; the keychain could not keep the sign-in; or this CLI is too old. The message says what to do. |
| 3 | Not signed in, or the sign-in expired: run `agentrail login` |
| 4 | Agentrail, npm or the network could not be reached, or Claude Code or Codex could not add the MCP server during `agent setup` |
| 5 | The CLI failed in a way it does not know. The message shows the failure in full: [report it](https://github.com/agentrail-co/agentrail-cli/issues). |


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