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: 
# 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 (set EMPIRICAL_ADD_TO_PATH=no to skip). To make it available without it, run: 
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: 
# 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.
    • 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.