> ## 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 reference

> Arguments, options and examples for every empirical command, from signing in to calling the API and reading the KV store.

This page lists every command of the `empirical` CLI. Add `--help` to any command to print the same help in your terminal. To install the CLI and sign in, see [CLI](https://empirical.run/docs/cli.md).

## Get started

### `empirical login`

Authorize the CLI with Empirical.

```sh theme={null}
empirical login [options]
```

| Option | Description |
| - | - |
| `--no-browser` | Don't open a browser; paste the code shown after authorizing (for SSH or headless machines). |
| `--code <code>` | Sign in with a one-time code from Install CLI in the dashboard, without a browser. |

### `empirical signup`

Create an Empirical account and log in.

```sh theme={null}
empirical signup [options]
```

| Option | Description |
| - | - |
| `--no-browser` | Don't open a browser; paste the code shown after authorizing (for SSH or headless machines). |

### `empirical logout`

Clear stored CLI authorization.

```sh theme={null}
empirical logout
```

### `empirical whoami`

Print the signed-in identity and its projects.

```sh theme={null}
empirical whoami
```

### `empirical skill`

Manage skills for local coding agents.

#### `empirical skill install`

Install the Empirical SKILL.md for local coding agents.

```sh theme={null}
empirical skill install [options]
```

| Option | Description |
| - | - |
| `-a, --agent <agent>` | Agent to configure: agents (Codex and other AGENTS.md-style tools) or claude-code. Can be repeated. |
| `--global` | Install into the global agent skill directory (\~/.agents, \~/.claude). |
| `--project` | Install into the current project's skill directory. |
| `--dry-run` | Print target paths without writing skill files. |

### `empirical feedback`

Tell the Empirical team what is broken, missing or confusing.

```sh theme={null}
empirical feedback <message...> [options]
```

| Argument | Description |
| - | - |
| `<message...>` | What happened or what you need. |

| Option | Description |
| - | - |
| `-p, --project <slug>` | Project slug. |
| `--title <title>` | One-line summary (default: first line of the message). |

Examples:

```text theme={null}
$ empirical feedback "session logs should show how long each tool call took"
$ empirical feedback -p flash --title "Login loops" "After login --no-browser the CLI asks again"
```

## Project and repository

### `empirical projects`

List the projects you can access.

```sh theme={null}
empirical projects [options]
```

| Option | Description |
| - | - |
| `--json` | Print the projects as JSON. |

Examples:

```text theme={null}
$ empirical projects        # slug, id, repo and name of each project
$ empirical projects --json # full project records
```

Pass a slug as `--project <slug>` to commands that act on a project.

### `empirical clone`

Clone a project's test repository.

```sh theme={null}
empirical clone [directory] [options]
```

| Option | Description |
| - | - |
| `-p, --project <slug>` | Project slug. |

Examples:

```text theme={null}
$ empirical clone                          # the only project on your account, into ./<slug>
$ empirical clone --project flash          # into ./flash
$ empirical clone my-tests --project flash # into ./my-tests
```

Run `empirical projects` to list the projects you can see.

### `empirical git`

Work with the git.empirical.run remote.

#### `empirical git setup`

Configure git to authenticate to git.empirical.run with your Empirical login.

```sh theme={null}
empirical git setup
```

### `empirical environments`

Inspect environments in ENVIRONMENTS.yaml and write their .env files.

#### `empirical environments show`

List the environments, or with --environment show every variable of one environment, its value and where it comes from.

```sh theme={null}
empirical environments show [options]
```

| Option | Description |
| - | - |
| `-e, --environment <slug>` | Environment slug. |
| `-p, --project <slug>` | Project slug (default: this checkout's project). |
| `--local` | Use only the repository; don't read dashboard variables. |
| `--show-values` | Show dashboard variable values instead of masking them. |
| `--json` | Print JSON. |

#### `empirical environments pull`

Write each environment's .env file with the dashboard's current variables. Prints variable names, never values.

```sh theme={null}
empirical environments pull [options]
```

| Option | Description |
| - | - |
| `-e, --environment <slug>` | Environment slug (default: every enabled environment). |
| `-p, --project <slug>` | Project slug (default: this checkout's project). |
| `--test-run <id>` | Write a test run's variables, overrides included, to its environment's file (.env when it has none). |
| `--dir <path>` | Repository to write into (default: this checkout's root). |
| `--json` | Print JSON. |

## Actions

### `empirical session`

Send prompts to agent sessions.

```sh theme={null}
empirical session [message...] [options]
```

| Option | Description |
| - | - |
| `-x, --execute` | Wait for the agent response and print the final assistant text. |
| `--follow-up` | Queue the message for the next turn instead of steering the active turn. |
| `--id <id>` | Existing session ID. |
| `-p, --project <slug>` | Project slug override for a new session. |
| `-m, --message <message>` | Prompt message. |
| `--agent <agent>` | Hive agent for a new session: \<name> or \<name>@\<version> (default: main-worker). |
| `--model <model>` | Model to use for a new session. |
| `--environment-id <id>` | Environment ID for a new session. |

Examples:

```text theme={null}
Create a session with a prompt without waiting:
  $ empirical session "my message"

Create a session with a prompt and wait for the final assistant text:
  $ empirical session -x "my message"

Continue a session and wait for the final assistant text:
  $ empirical session --id 123 -x "follow up"

Queue a message for the next turn instead of steering the active turn:
  $ empirical session --id 123 --follow-up "after that, do this"
```

#### `empirical session list`

List sessions.

```sh theme={null}
empirical session list [options]
```

| Option | Description |
| - | - |
| `--limit <number>` | Maximum number of sessions to show. |

#### `empirical session status`

Show current state, latest activity, branches, and pull requests.

```sh theme={null}
empirical session status <id>
```

| Argument | Description |
| - | - |
| `<id>` | Session ID. |

#### `empirical session logs`

Print session history (user and assistant messages, tool calls); -f to follow live.

```sh theme={null}
empirical session logs <id> [options]
```

| Argument | Description |
| - | - |
| `<id>` | Session ID. |

| Option | Description |
| - | - |
| `--since <time>` | Start (inclusive): duration (30m, 1h, 2d) or RFC 3339 timestamp; default is the session start. |
| `--before <time>` | End (exclusive): duration or RFC 3339 timestamp. |
| `-f, --follow` | Keep following live events after the history. |
| `--until <condition>` | With -f, exit once the condition is met (supported: "idle" — agent stopped and queue empty). |
| `--timeout <seconds>` | With -f, give up after this many seconds (exit code 2). |
| `--kind <kinds>` | Keep only rows of these comma-separated kinds (user, assistant, tool, tools, thought, notification, ...). |
| `--last <n>` | Keep only the last n rows (after --kind). |
| `--subagent <call-id>` | Show that subagent's own transcript; a unique prefix of the id that ends its subagent row is enough. |
| `--tool-output` | List each tool call on its own row, with its full output. |
| `--json` | Emit raw NDJSON (session\_entry frames, then live stream frames with -f). |

Examples:

```text theme={null}
Whole session history:
  $ empirical session logs 123

The last hour, as raw NDJSON:
  $ empirical session logs 123 --since 1h --json

The latest answer, in full:
  $ empirical session logs 123 --kind assistant --last 1

A subagent's own transcript, by a unique prefix of the call id that ends its subagent row:
  $ empirical session logs 123 --subagent call_GlNohq

The last command's full output:
  $ empirical session logs 123 --kind tool --last 1 --tool-output

Follow new events only, until the agent is idle:
  $ empirical session logs 123 -f --since 0s --until idle --timeout 600
```

### `empirical test-runs`

Trigger test runs and wait for results.

#### `empirical test-runs trigger`

Start a full test run.

```sh theme={null}
empirical test-runs trigger [options]
```

| Option | Description |
| - | - |
| `-p, --project <slug>` | Project slug. |
| `-e, --environment <slug>` | Environment to run against. |
| `--branch <branch>` | Test repository branch to run. |
| `--shards <n>` | Number of shards. |
| `--playwright-projects-match <globs>` | Comma-separated Playwright project globs to run, replacing the environment's. |
| `--playwright-projects-ignore <globs>` | Comma-separated Playwright project globs to skip, replacing the environment's. |
| `--tests <ids>` | Comma-separated test case ids to run. |
| `--tags <tags>` | Comma-separated tags to run, replacing the environment's. |
| `--exclude-tags <tags>` | Comma-separated tags to skip, replacing the environment's. |
| `--wait` | Wait for the run to end; exit code 0 means it passed. |
| `--timeout <seconds>` | With --wait, give up after this many seconds (exit code 2). |
| `--json` | Print the run as JSON. |

Examples:

```text theme={null}
$ empirical test-runs trigger -p flash -e production
$ empirical test-runs trigger -p flash -e staging --branch fix-login --wait
$ empirical test-runs trigger -p flash --tags @smoke --wait --timeout 1800
```

#### `empirical test-runs status`

Print a run's state and result counts.

```sh theme={null}
empirical test-runs status <id> [options]
```

| Argument | Description |
| - | - |
| `<id>` | Test run id. |

| Option | Description |
| - | - |
| `-p, --project <slug>` | Project slug. |
| `--json` | Print the run as JSON. |

#### `empirical test-runs wait`

Wait for a run to end; exit code 0 means it passed.

```sh theme={null}
empirical test-runs wait <id> [options]
```

| Argument | Description |
| - | - |
| `<id>` | Test run id. |

| Option | Description |
| - | - |
| `-p, --project <slug>` | Project slug. |
| `--timeout <seconds>` | Give up after this many seconds (exit code 2). |
| `--json` | Print the finished run as JSON. |

```text theme={null}
Exit codes: 0 passed, 1 failed or did not finish, 2 timed out.
```

### `empirical api`

Call an Empirical API endpoint.

```sh theme={null}
empirical api <endpoint> [options]
```

| Argument | Description |
| - | - |
| `<endpoint>` | API path or absolute URL. |

| Option | Description |
| - | - |
| `-X, --method <method>` | HTTP method. |
| `-f, --field <key=value>` | String field for a JSON body. |
| `-F, --typed-field <key=value>` | Typed field for a JSON body. Supports numbers, booleans, null, JSON, and @file. |
| `-H, --header <header>` | Request header, e.g. "Name: value". |
| `-p, --project <slug>` | Project slug (sets x-project-slug). |
| `-q, --query <key=value>` | Append a URL query parameter (repeatable). |
| `--jq <expression>` | Filter JSON output with jq. |
| `--paginate` | Fetch all pages using Link headers or pagination metadata. |
| `--input <file>` | Read raw request body from a file, or - for stdin. |

Examples:

```text theme={null}
$ empirical api api/projects
$ empirical api api/chat-sessions -f title="Bug" -f body="Details"
$ empirical api api/projects/1 -X PATCH -F archived=true
$ empirical api api/chat-sessions --paginate --jq '.[] | .data.chat_sessions[]?.id'
$ empirical api api/slack/threads --project flash -q entity_type=test_run -q entity_id=131825
$ empirical api api/projects -H "x-project-id: 1"
$ empirical api api/chat-sessions --input payload.json
```

### `empirical kv`

Read and write the project key-value store.

#### `empirical kv get`

Print a value (or the whole entry with --entry).

```sh theme={null}
empirical kv get <key> [options]
```

| Argument | Description |
| - | - |
| `<key>` | Key to read. |

| Option | Description |
| - | - |
| `--entry` | Print the entry with its version and metadata. |
| `-p, --project <slug>` | Project slug. |

#### `empirical kv set`

Write a value; JSON is stored as JSON, anything else as a string.

```sh theme={null}
empirical kv set <key> <value> [options]
```

| Argument | Description |
| - | - |
| `<key>` | Key to write. |
| `<value>` | Value to store. |

| Option | Description |
| - | - |
| `--ttl <ttl>` | Time to live: seconds, or 90s, 10m, 2h, 7d (max 30d). |
| `--if-absent` | Write only if the key does not exist. |
| `--if-version <version>` | Write only if the entry is at this version. |
| `--string` | Store the value as a string even if it is valid JSON. |
| `-p, --project <slug>` | Project slug. |

#### `empirical kv refresh`

Reset a key's TTL without changing its value.

```sh theme={null}
empirical kv refresh <key> [options]
```

| Argument | Description |
| - | - |
| `<key>` | Key to refresh. |

| Option | Description |
| - | - |
| `--ttl <ttl>` | New time to live: seconds, or 90s, 10m, 2h, 7d. |
| `--if-version <version>` | Refresh only if the entry is at this version. |
| `-p, --project <slug>` | Project slug. |

#### `empirical kv delete`

Delete a key.

```sh theme={null}
empirical kv delete <key> [options]
```

| Argument | Description |
| - | - |
| `<key>` | Key to delete. |

| Option | Description |
| - | - |
| `--if-version <version>` | Delete only if the entry is at this version. |
| `-p, --project <slug>` | Project slug. |

#### `empirical kv list`

List entries in key order, following every page.

```sh theme={null}
empirical kv list [prefix] [options]
```

| Argument | Description |
| - | - |
| `[prefix]` | Only list keys that start with this prefix. |

| Option | Description |
| - | - |
| `--values` | Include each entry's value. |
| `--limit <count>` | Stop after this many entries. Default: `1000`. |
| `-p, --project <slug>` | Project slug. |

## Files

### `empirical files`

Upload, download and list project files.

#### `empirical files upload`

Upload a file and print its link.

```sh theme={null}
empirical files upload <path> [options]
```

| Argument | Description |
| - | - |
| `<path>` | File to upload. |

| Option | Description |
| - | - |
| `--json` | Print the file record as JSON. |
| `-p, --project <slug>` | Project slug. |

#### `empirical files download`

Save a project file using your Empirical sign-in.

```sh theme={null}
empirical files download <file> [options]
```

| Argument | Description |
| - | - |
| `<file>` | Handle (file\@6526), id or file link. |

| Option | Description |
| - | - |
| `-o, --output <path>` | Where to save it; - writes to stdout. Default: the file's name in the current directory. |
| `-p, --project <slug>` | Project slug, when \<file> is a handle. |

#### `empirical files show`

Print a file's details and link.

```sh theme={null}
empirical files show <file> [options]
```

| Argument | Description |
| - | - |
| `<file>` | Handle (file\@6526) or id. |

| Option | Description |
| - | - |
| `--json` | Print the file record as JSON. |
| `-p, --project <slug>` | Project slug. |

#### `empirical files list`

List the project's files, newest first.

```sh theme={null}
empirical files list [options]
```

| Option | Description |
| - | - |
| `--session <id>` | Only files created by this session. |
| `--limit <count>` | How many files to list (max 100). Default: `20`. |
| `--json` | Print the files as JSON. |
| `-p, --project <slug>` | Project slug. |

## CLI

### `empirical version`

Print the installed CLI version.

```sh theme={null}
empirical version
```

### `empirical upgrade`

Upgrade to the latest published CLI.

```sh theme={null}
empirical upgrade
```


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