> ## Documentation Index
> Fetch the complete documentation index at: https://empirical.run/docs/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.
  * `empirical session status <id>` shows the current agent and sandbox state, queued messages, latest assistant response, branches, and pull requests.
  * `empirical session activity <id> --since 1h` prints durable activity in chronological order with RFC 3339 UTC timestamps. Add `--before <time>` to select a bounded interval; both options accept relative durations or RFC 3339 timestamps.
  * `empirical session listen <id>` follows live session activity. Add `--since 1h` to replay recent durable activity before following live events.
  * `empirical session listen <id> --until idle --timeout 300` waits until the agent is idle and no messages remain queued.
  * Add `--project <slug>` only when you need to choose a specific project.
* Git
  * `empirical git setup` configures git to authenticate to `git.empirical.run` with your CLI login, via a credential helper scoped to that host. Run it once per machine.
  * `empirical clone [directory]` clones a project's test repository from `git.empirical.run`, running the setup above first if needed. Without a directory, git creates `./<project-slug>`.
  * Add `--project <slug>` only when you need to choose a specific project; with several projects the error lists the available slugs.
  * After setup, plain `git clone https://git.empirical.run/<project-slug>.git` works too.
  * With your login you can fetch and push; pushes to the project's default branch are rejected. Project API keys are read-only. Without the CLI (for example in CI), use a project API key as the HTTP password.
* API
  * `empirical api <endpoint>` calls any Empirical API endpoint using your CLI login token.
  * Use `--project <slug>` to select a project without supplying an `x-project-slug` header. Do not combine it with `x-project-id` or `x-project-slug` headers.
  * Add repeatable `-q, --query <key=value>` options for URL query parameters. Values are URL-encoded automatically, and repeated keys append to any parameters already in the endpoint. Query parameters alone keep the request method as GET.
  * Example: `empirical api api/slack/threads --project flash -q entity_type=test_run -q entity_id=131825`.
  * Use `--jq <expression>` to filter JSON output (requires jq). The former `-q` shorthand for jq filtering now means `--query`; update existing commands to use `--jq`.
  * `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.