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 attempts to add ~/.empirical/bin to your shell PATH. In case you skipped it, run: 
export PATH="$HOME/.empirical/bin:$PATH"

​
Agent skill

The Empirical skill teaches compatible local coding agents how to use the empirical command. By default, the CLI installation flow configures the skill. To install it manually, run : 
# Install for global targets (for Claude Code and Codex)
empirical skill install

# Or specify an --agent param (supports `codex` and `claude-code`)
empirical skill install --agent codex
empirical skill install --agent claude-code

# Install in your project at .agents/skills
empirical skill install --project

# Overwrite an existing skill file
empirical skill install --force

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