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

# CLI

> Install and configure the Empirical command line tool

The Empirical CLI lets you - or your local coding agents - work with Empirical from the terminal. The CLI also bundles an agent skill that can be configured for common coding agents (Claude Code and Codex).

## Install

In your terminal, run:

```sh theme={null}
# Install the standalone binary
curl -fsSL https://cli.empirical.run/install | sh

# Check installed version
empirical version

# Authenticate as yourself
empirical login
```

The installer adds `~/.empirical/bin` to your shell `PATH`. To make it available without it, run:

```sh theme={null}
export PATH="$HOME/.empirical/bin:$PATH"
```

## Agent skill

The Empirical skill teaches compatible local coding agents how to use the `empirical` command.

The installer suggests this as a next step after install. Run it with exactly one of `--global` or `--project`:

```sh theme={null}
# Install in the global agent directories (Claude Code, plus Codex and other agents)
empirical skill install --global

# Install in your project at .agents/skills
empirical skill install --project
```

Run `empirical skill install --help` for all options.

The `SKILL.md` file is managed by the CLI: installs and upgrades overwrite it, so don't edit it directly. To customize the skill for your project, add a `CUSTOM.md` file in the same directory — the skill instructs agents to read it, and the CLI never touches it.

## Commands reference

* User auth
  * `empirical login` authorizes the CLI with Empirical.
  * `empirical logout` clears local CLI authorization.
  * `empirical whoami` prints the current authenticated account.
* Version and upgrade
  * `empirical version` prints the installed CLI version.
  * `empirical upgrade` upgrades to the latest published CLI version.
* Agent skill
  * `empirical skill install` installs the Empirical `SKILL.md` for local coding agents, overwriting any existing copy. Requires exactly one of `--global` or `--project`.
* Sessions
  * `empirical session "<prompt>"` creates a session and sends a prompt.
  * `empirical session --id <id> "<prompt>"` sends a prompt to an existing session.
  * `empirical session -x "<prompt>"` creates a session, waits for the agent response, and prints only the final assistant text.
  * `empirical session -x --id <id> "<prompt>"` sends to an existing session, waits for the agent response, and prints only the final assistant text.
  * `echo "<prompt>" | empirical session --execute --id <id>` reads the prompt from stdin.
  * `empirical session list` lists recent sessions.
  * Add `--project <slug>` only when you need to choose a specific project.
* API
  * `empirical api <endpoint>` calls any Empirical API endpoint using your CLI login token.
  * `empirical api api/endpoints` lists the endpoints available to your authentication method.

## Telemetry

The CLI collects usage telemetry to help improve the product. Command arguments and flag values are never collected. To opt out, set the [`DO_NOT_TRACK`](https://consoledonottrack.com/) environment variable.