> ## 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`. If `empirical` is not available in a new terminal, add it manually:

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

Verify the login and see the projects available to you:

```sh theme={null}
empirical whoami
empirical api api/projects
```

## 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 (with the error reason when the sandbox failed), queued messages, latest assistant response, branches, and pull requests.
* `empirical session logs <id>` prints the session history in chronological order with RFC 3339 UTC timestamps. Add `--since <time>` and `--before <time>` to select an interval; both accept relative durations or RFC 3339 timestamps. Add `--json` for raw NDJSON.
* `empirical session logs <id> -f` prints the history, then follows live events.
* `empirical session logs <id> -f --since 0s --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.


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