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. To make it available without it, run:

​
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 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.
  • 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 environment variable.