Agent CLI
Install the agent CLI with Homebrew, log in, and type agent "prompt" to run a cloud agent from your terminal. Subcommands cover scripts and CI.
The agent CLI is a terminal client for the same REST API the dashboard uses. The agents themselves run in the Ellipsis cloud; the CLI starts them, streams their output, and lets you steer them. It ships as one open-source binary named agent.
Install
brew install ellipsis-dev/cli/agent
agent loginagent login prints a verification URL and code, opens the URL in your browser (--no-browser over SSH), and waits until you approve in the dashboard. The token lands in ~/.ellipsis/config.json and attributes your sessions to you. Scripts and CI skip the login: create an API key and export it as ELLIPSIS_API_TOKEN.
Run an agent
agent "prompt" starts a session in the Ellipsis cloud and drops you into the live conversation. The CLI detects the repository you are standing in (the origin remote) and checks it out in the sandbox.
$ agent -e cloud_agent_environment "triage the failing CI on api-repo"
✦ Cloud agent session on ellipsis.dev
⎿ Sandbox ready in 28s
Ran 3 shell commands
The failing job is test_expiry_grace_period: the fixture freezes time before
the item is created, so the grace window is already expired when the
assertion runs. Opened your-org/api-repo#512 with the fix.Type to steer: a message you send is picked up at the agent's next turn boundary. Ctrl-C once interrupts the running turn, twice leaves the view; the session keeps running, and the CLI prints resume with: agent session connect session_7Hq2mX4p.
Every flag goes after the prompt or before it:
| Flag | Effect |
|---|---|
-e, --environment <name> | Run in a saved environment, by name or id. Default: your organization's default environment. |
-r, --repo <owner/name> | Also check out a repository, in whichever environment the session runs (repeatable; a bare name means your account). Composes with -e. |
--model <model-id> | The model for this session (agent model list). Default: your organization's default model. |
--budget <usd> | Spend cap for this session, in dollars. |
-f, --config-file <path> | Start from a config file (YAML or JSON): an automation file, whose session: block is used, or a bare session config. |
-t, --template <slug> | Start from a built-in template (agent template list). |
--rebuild | Skip the sandbox image cache: a fresh full build whose snapshot refreshes the cache. |
-m, --metadata <key=value> | Attach metadata (repeatable). |
A bare agent with no prompt opens the launcher: your running sessions in a sidebar beside a composer, where Enter starts a new cloud session. Select a session to read its conversation and send it messages.
The defaults a bare prompt falls back to (model, environment, per-session budget ceiling) are organization settings, set on the dashboard's Automations > Settings tab or with PUT /v1/settings/organization: Organization.
Commands for scripts
The bare form is for you; subcommands are for scripts and CI. One line per group:
- Sessions:
agent session start|get|list|search|connect|stop|diff|export, including--watchas a CI gate. - Automations:
agent automation list|get|metrics|run|create|edit|delete|link|unlink|init, plusagent template listandagent model list. - Platform:
agent environment,agent variable,agent file,agent integrationand the per-integration lists,agent budget,agent usage,agent analytics.
agent --help and agent <command> --help list every command and flag. Most commands accept --json to print the raw API response. ELLIPSIS_API_BASE_URL points the CLI at a non-default host (default https://api.ellipsis.dev).
Teach your coding agent about Ellipsis
A public Agent Skill teaches a local coding agent (Claude Code, Cursor, Codex, and others) what Ellipsis is and how to drive it with this CLI, so the agent can start, watch, and search sessions for you. Install it once:
npx skills add ellipsis-dev/cliThat copies skills/ellipsis/ from the public ellipsis-dev/cli repository into your coding agent's skills directory (.claude/skills/ for Claude Code). The agent loads it the next time a task mentions Ellipsis or the agent CLI. To pin it globally, copy the same directory into ~/.claude/skills/.