CLI

​

Install

# Install the standalone binary
curl -fsSL https://cli.empirical.run/install | sh

# Check installed version
empirical version

# Authenticate as yourself
empirical login

export PATH="$HOME/.empirical/bin:$PATH"

​

Agent skill

# 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

​

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