Skip to main content
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:
The installer adds ~/.empirical/bin to your shell PATH. If empirical is not available in a new terminal, add it manually:
Verify the login and see the projects available to you:

​
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:
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 subscribe <id> (from an agent session) wakes the calling session when session <id> finishes its turn and waits for input. One-shot; creating or messaging a session subscribes automatically.
  • 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.

​
KV

  • empirical kv set <key> <value> --ttl <ttl> writes to the project’s KV store. JSON values are stored as JSON, anything else as a string; --string forces a string. --ttl takes seconds or a duration such as 90s, 10m, 2h or 7d (up to 30 days).
  • Add --if-absent to write only if the key does not exist, or --if-version <n> to write only if the entry is still at that version. A failed condition exits with an error naming the current version and its writer.
  • empirical kv get <key> prints the value; --entry prints the whole entry with version, timestamps and written_by.
  • empirical kv list [prefix] lists entries in key order across every page; --values includes values and --limit <count> caps the output.
  • empirical kv refresh <key> --ttl <ttl> resets the expiry without changing the value, and empirical kv delete <key> removes it. Both accept --if-version <n>.
  • 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.
  • 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. To opt out, set the DO_NOT_TRACK environment variable.