> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.empiriolabs.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.empiriolabs.ai/_mcp/server. # EmpirioLabs AI CLI `empirio` starts your coding agent already connected to EmpirioLabs AI. One command signs you in, picks a model the agent can run and starts the agent. Your agents' own settings stay as they are, and the model list comes from the live catalog, so new models are available the day they launch. #### One command `empirio claude`, `empirio codex`, `empirio gemini` and more. Arguments after the agent's name go to the agent. #### Settings unchanged Each session gets the connection when it starts. Nothing in `~/.claude`, `~/.codex` or any other agent's settings is edited. #### Live model list Every agent sees the models it can run, read from the catalog when it starts. #### Browser sign-in Approve the CLI once in your browser, or use an API key. Disconnect it any time under **Settings**. ## Install **`macOS / Linux / WSL`** ```bash title="macOS / Linux / WSL" curl -fsSL https://empiriolabs.ai/install.sh | sh ``` **`Windows PowerShell`** ```powershell title="Windows PowerShell" irm https://empiriolabs.ai/install.ps1 | iex ``` The installers check every download against the release's signed checksums before installing anything. You can also download an archive for your platform from [GitHub Releases](https://github.com/EmpirioLabs-AI/cli/releases), or build it with Go: `go install github.com/EmpirioLabs-AI/cli/cmd/empirio@latest`. ## Start an agent ```bash empirio ``` `empirio` on its own opens a menu: choose an agent, choose a model, and the agent starts. To start one directly, name it: ```bash empirio claude # Claude Code empirio codex # Codex CLI empirio gemini -m # Gemini CLI on a model you choose empirio claude -p "explain this repo" # arguments after the name go to the agent empirio codex exec "add tests" ``` The first run opens your browser to sign in. After that, `empirio` starts the agent straight away. ## Supported agents | Agent | Start it | EmpirioLabs AI tools | Install the agent | | -------------------------------------------- | ------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [Claude Code](/integrations#claude-code) | `empirio claude` | Yes | `curl -fsSL https://claude.ai/install.sh \| bash` Windows: `irm https://claude.ai/install.ps1 \| iex` | | [Codex CLI](/integrations#codex-cli) | `empirio codex` | Yes | `npm install -g @openai/codex` macOS: `brew install --cask codex` | | [OpenCode](/integrations#opencode) | `empirio opencode` | Yes | `curl -fsSL https://opencode.ai/install \| bash` Windows: `npm install -g opencode-ai` | | [Gemini CLI](/integrations#gemini-cli) | `empirio gemini` | No | `npm install -g @google/gemini-cli` | | [Qwen Code](/integrations#qwen-code) | `empirio qwen` | Yes | `npm install -g @qwen-code/qwen-code` | | [Crush](/integrations#crush) | `empirio crush` | Yes | `npm install -g @charmland/crush` macOS: `brew install charmbracelet/tap/crush` Windows: `winget install charmbracelet.crush` | | [Kilo CLI](/integrations#kilo-cli) | `empirio kilo` | Yes | `npm install -g @kilocode/cli` | | [Aider](/integrations#aider) | `empirio aider` | No | `curl -LsSf https://aider.chat/install.sh \| sh` Windows: `powershell -ExecutionPolicy ByPass -c "irm https://aider.chat/install.ps1 \| iex"` | | [goose](/integrations#goose) | `empirio goose` | No | `curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh \| bash` Windows: `Invoke-WebRequest -Uri "https://raw.githubusercontent.com/aaif-goose/goose/main/download_cli.ps1" -OutFile download_cli.ps1; .\download_cli.ps1` | | [OpenHands CLI](/integrations#openhands) | `empirio openhands` | No | `uv tool install openhands --python 3.12` | | [Factory Droid](/integrations#factory-droid) | `empirio droid` | No | `curl -fsSL https://app.factory.ai/cli \| sh` Windows: `irm https://app.factory.ai/cli/windows \| iex` | Install an agent with its own installer, then run its `empirio` command. `empirio doctor` lists the agents installed on your computer. ## Sign in ```bash empirio login ``` Your browser opens the EmpirioLabs AI consent screen. Approve **EmpirioLabs AI CLI**, and the computer appears under **Settings > Connected applications** in the [dashboard](https://platform.empiriolabs.ai/dashboard), where you can disconnect it at any time. `empirio logout` disconnects it too. | To | Run | | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | Sign in on a computer without a browser, such as over SSH | `empirio login --no-browser`, open the address it prints on any device, then paste the address the browser ends on | | Use an API key instead | `empirio login --key` | | Use a key in scripts and CI | Set `EMPIRIOLABS_API_KEY`; it always takes precedence over a saved sign-in | Create keys on the [API keys page](https://platform.empiriolabs.ai/dashboard/api-keys). ## Models Each agent starts on your default model, or on the catalog's first featured model it can run when you have not chosen one. An agent only lists models that support what it needs: the API it speaks and tool calling. ```bash empirio models # every model with its context window and prices empirio models --agent codex # the models Codex CLI can run empirio model # make a model your default empirio claude -m # one session on another model ``` Agents with a second model for quick background work, such as titles and summaries, get the lowest-cost featured model by the same author. Choose another with `--fast-model `. ## EmpirioLabs AI tools Agents marked **Yes** under **EmpirioLabs AI tools** in the [agent table](#supported-agents) also get the tools of the [EmpirioLabs AI MCP server](/mcp), with nothing to set up. Each session gets the toolsets marked **Yes** under **In the default**; a tool call is billed like the same API request. | Toolset | `--tools` name | What it does | In the default | | ------------- | --------------- | ------------------------------------------------------------------------------------ | -------------- | | Models | `models` | Browse the model catalog, prices, capabilities, and parameters | Yes | | Text | `text` | Run chat, embeddings, reranking, decisions, and AI text detection (uses credits) | No | | Search | `search` | Run web search, grounded answers, and research (uses credits) | Yes | | Media | `media` | Generate and edit images, video, audio, speech, transcription, and 3D (uses credits) | Yes | | Jobs | `jobs` | Check, wait for, and cancel generation jobs | Yes | | Agents | `agents` | Run and manage agent tasks (uses credits) | No | | Account | `account` | Read usage history and the current balance | Yes | | Batch | `batch` | Upload batch files and manage batch jobs (uses credits) | No | | GPU Cloud | `gpu` | Deploy and manage GPU instances, clusters, and volumes (billable) | No | | Hosted Agents | `hosted_agents` | Create and manage hosted agents (billable) | No | ```bash empirio claude --tools all # every toolset, including GPU Cloud and hosted agents, which bill while they run empirio codex --tools search+media # only these toolsets empirio opencode --tools none # no EmpirioLabs AI tools ``` Set `EMPIRIO_TOOLS` to choose for every session. The tools are added next to the agent's own MCP servers for that session only; a server you already named `empiriolabs` is used instead. Each toolset's tools are listed on the [MCP server](/mcp) page. ## Commands | Command | Does | | ---------------------------------------- | ------------------------------------------------------------------------------------ | | `empirio` | Choose an agent and a model, then start it | | `empirio [-m ] [args]` | Start an agent; other arguments go to the agent | | `empirio --tools ` | Choose the EmpirioLabs AI tools: `default`, `all`, `none`, or toolsets joined by `+` | | `empirio --print-env` | Show what the agent would receive, with the key masked | | `empirio login` / `empirio logout` | Sign in or out; `logout` also disconnects a browser sign-in | | `empirio models` / `empirio model` | List models; show or set your default | | `empirio doctor` | Check your sign-in, the API and your installed agents | | `empirio agents [--json]` | List the agents `empirio` can start | | `empirio update` | Install the latest release | | `empirio uninstall` | Remove `empirio` and its saved settings, and disconnect a browser sign-in | ## Your agent settings `empirio` passes the connection to an agent for that session only. Where an agent saves a choice of its own during a session, such as a model picked with `/model`, `empirio` puts back the value it found when the session ends. `empirio --print-env` shows exactly what an agent receives. `empirio` keeps its own settings and your sign-in in `%APPDATA%\empirio` on Windows and `~/.config/empirio` elsewhere, readable only by you. | Variable | Use | | ------------------------- | --------------------------------------------- | | `EMPIRIOLABS_API_KEY` | API key to use instead of the saved sign-in | | `EMPIRIO_CONFIG_DIR` | Keep the CLI's settings in another directory | | `EMPIRIO_NO_BROWSER` | Sign in without opening a browser | | `EMPIRIO_NO_UPDATE_CHECK` | Turn off the daily notice about a new release | ## Update and uninstall `empirio update` installs the latest release after checking its signature and checksums, and the CLI tells you once a day when a new release is out. `empirio uninstall` removes the program and its settings and disconnects a browser sign-in. Agents and their own settings are left as they are. ## Verify a release Every release publishes `SHA256SUMS`, its signature `SHA256SUMS.sig`, and a build provenance attestation for every file. With [`allowed_signers`](https://github.com/EmpirioLabs-AI/cli/blob/main/internal/release/allowed_signers) from the CLI's repository: ```bash ssh-keygen -Y verify -f allowed_signers -I release@empiriolabs.ai -n empirio-release -s SHA256SUMS.sig < SHA256SUMS sha256sum --check --ignore-missing SHA256SUMS gh attestation verify empirio_linux_amd64.tar.gz --repo EmpirioLabs-AI/cli ``` ## Troubleshooting | Message | What to do | | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | ` is not installed` | Run the install command it prints, then the same `empirio` command again | | A model is missing from an agent's list | That model lacks the API or tool calling the agent needs; `empirio models --agent ` lists the ones it can run | | The browser cannot reach your computer | Sign in with `empirio login --no-browser` | | `the API key was not accepted` | Check the key on the [API keys page](https://platform.empiriolabs.ai/dashboard/api-keys), or sign in again with `empirio login` | Building an app that signs people in to EmpirioLabs AI? See [Sign in with EmpirioLabs AI](/oauth).