Ellipsis CLI

Drive the Ellipsis cloud from your terminal: start agent sessions, stream their output live, and manage configurations.

This is a thin client. The agent runs in the Ellipsis cloud; the CLI authenticates, opens a WebSocket, and streams results. It is open source (MIT), and the proprietary engine stays server-side.

brew install ellipsis-dev/cli/agent

skills/ellipsis is an Agent Skill that teaches any coding agent (Claude Code, Cursor, Codex, and others) what the Ellipsis platform is and how to drive it with this CLI:

npx skills add ellipsis-dev/cli

Or copy skills/ellipsis/ into your agent's skills directory (~/.claude/skills/ for Claude Code). Ellipsis agents can load it straight from their config, no clone required:

skills:
  - path: skills/ellipsis
    repository:
      owner: ellipsis-dev
      name: cli

agent install                     # open the dashboard sign-in page, where you install Ellipsis
agent login                       # device-code auth against the active host
agent logout                      # remove stored credentials (--all for every host)
agent me                          # show the current credential's identity

agent host list                   # list configured hosts (the active one is marked *)
agent host add beta https://beta-api.ellipsis.dev   # add a host and switch to it
agent host use prod               # switch the active host
agent host current                # show the active host and how it resolves
agent host set beta --rename staging   # rename / re-point a host (--api-base / --app-base)
agent host delete beta            # remove a host and its stored token

agent session start -e backend "..."   # run a prompt in a saved environment
agent session start --config-file f.json   # ...or from an inline config
agent session start --template ellipsis-helper   # ...or from a maintained template
agent session start --budget 5 "..."   # cap this session's spend, in dollars
agent session start --image shot.png "..."   # the agent sees the picture on its first turn
agent session start --watch "..."      # start and immediately stream it
agent session list --limit 20         # list recent sessions (filter by --source, --author, --since, …)
agent session get <session-id>        # inspect one session (prints a dashboard link)
agent session get <session-id> --watch  # follow a session until it finishes
agent session record <session-id>     # read a session's stored transcript, one line per record
agent session stop <session-id>       # stop an in-flight session

agent review 123                  # review a pull request now, instead of waiting for a push
agent review get <review-id>      # a review's findings, scope, and whether it posted
agent review list --repo api      # list a repository's reviews, newest first
agent review init                 # scaffold a starter review pipeline (code_review.yaml)

agent automation list             # list your automations
agent automation get <id>         # show one automation as YAML (--json for JSON)
agent automation run <id> --input '{"issue": "ENG-42"}'   # invoke it exactly as defined
agent automation init [path]      # scaffold a starter definition (default: agents/my_agent.yaml)
agent automation create --file agents/foo.yaml   # create one, live at once (or --template <slug>)
agent automation create --repo api --file agents/foo.yaml   # instead define it as a file, via a pull request
agent automation edit <id> --file agents/foo.yaml    # replace its definition, live at once
agent automation delete <id>      # delete it; it stops and its name is freed
agent automation link <id> --repo api   # move it into a repository, via a pull request
agent automation unlink <id>      # take it over from its file, so the API changes it

agent model list                  # list selectable agent models (the account default is marked)

agent integration                 # every connected integration in one table
agent github repos                # repositories connected to the GitHub installation
agent github members              # org roster (the logins/ids --author accepts), with linked Slack identities
agent slack channels              # channels in the connected Slack workspace
agent slack members               # workspace members, with linked GitHub identities
agent linear teams                # teams in the connected Linear organization
agent sentry orgs                 # connected Sentry organizations

agent file upload shot.png        # store a PNG; prints an org-gated link to paste into a PR comment
agent file list                   # list stored files (--session <id> scopes to one run's uploads)
agent file get <file-id> -o shot.png     # show one file, or download its bytes with -o
agent file delete <file-id>       # delete a file (it disappears from list/get and its link stops resolving)

agent variable list               # list sandbox env variable names (values are write-only)
agent variable set A=1 B=2        # create/update variables (or --from-file .env/.json)
agent variable delete K           # delete a variable

agent budget                      # current budget summary
agent usage                       # usage dashboard for the period

agent analytics reviewer --account-type bot   # which apps review the most PRs
agent analytics pr --days 30      # PR volume/trend with human vs bot splits
agent analytics review --repo my-service      # review totals + top reviewers
agent ping                        # check authenticated API connectivity

Every command shown is singular. The plural spelling of each (agent files, agent sessions, agent analytics prs) is a hidden alias that works but is left out of --help. See skills/cli-conventions for the full argument, flag, and help-text conventions.

Most commands accept --json to print the raw API response. The CLI talks to the public REST API. Point it at a different instance durably with agent host (below), or per-invocation with ELLIPSIS_API_BASE_URL (or the legacy ELLIPSIS_API_BASE).

--watch (on both session start and session get) streams the session's output live over WebSocket until it reaches a terminal status, falling back to periodic status polling if the live stream is unavailable. Either way it first prints a clickable dashboard link. How the stream works is described in docs/SESSION_STREAMING.md.

agent login uses the device-code flow: it requests a code pair, prints a verification URL (and opens it unless --no-browser), and polls until you approve the request in the dashboard. The issued user token is stored under ~/.ellipsis/config.json (mode 0600) and attributes sessions to you.

Credentials resolve in this order (highest wins): explicit argument → environment (ELLIPSIS_API_TOKEN / ELLIPSIS_API_BASE_URL, with the legacy ELLIPSIS_API_BASE accepted as a fallback) → the active host in the config file → default (prod). This lets the CLI run headlessly — e.g. inside an Ellipsis cloud sandbox where a per-sandbox token and base URL are injected into the environment — with no agent login and no config file on disk. agent logout only clears the on-disk token (--all for every host); a token supplied via ELLIPSIS_API_TOKEN lives in the environment and keeps working until you unset it.

agent host selects which Ellipsis instance the CLI targets — Ellipsis Cloud, a preview environment, or a self-hosted deployment — so you can switch without re-exporting env vars. agent host add <name> <api-url> registers an instance and makes it active; agent host use <name> switches; agent host list shows them all (the active one marked *). Each host keeps its own token (so switching doesn't re-authenticate) and its own dashboard/app URL. The app URL is derived from the API URL by default (api. → app.); a self-hosted instance whose dashboard host isn't a mechanical swap sets it explicitly with agent host add … --app-base <url> (or agent host set <name> --app-base <url>). agent login then authenticates the active host, and every link the CLI prints points at that host's dashboard.

Hosts and tokens live in ~/.ellipsis/config.json (mode 0600); set ELLIPSIS_CONFIG_DIR to relocate it. A config file from before hosts existed is migrated on first use — your existing login becomes a host named for its API base.

Session configs select one native block. Put the first message inside it:

session:
  claude_code:
    prompt: Fix the failing tests.
  # Or: codex: {model: gpt-6-astra, prompt: Fix the failing tests.}

The old harness, instructions, and top-level prompt fields are no longer accepted. --system now reports an error; put task instructions in the prompt or a repository AGENTS.md file. Environment build scripts use hooks.build_base and hooks.after_checkout; the old image block is removed.

npm install
npm run dev -- --help       # run from source (tsx)
npm run typecheck           # tsc --noEmit
npm test                    # unit tests (vitest)
npm run build               # bundle to dist/ (tsup)
npm run compile             # single-binary build (bun)

• npm test runs the vitest unit suite (test/): query building and error parsing in the API client, the option coercions, money formatting, and the deviceLogin poll loop (driven with fake timers, no network).

• scripts/smoke-local.sh is a fully-automated end-to-end check against a local docker compose backend. It drives the device-code login itself — scraping the verification code and approving it headlessly through the running public_api container — then exercises the authenticated API calls with a throwaway config dir. One command, no manual approval:

  ./scripts/smoke-local.sh
  # overrides: ELLIPSIS_API_BASE, ELLIPSIS_PUBLIC_API_CONTAINER, ELLIPSIS_SMOKE_CUSTOMER_ID

• scripts/smoke.sh is the manual variant for any backend (incl. staging/prod): it drives login and the API calls but waits for you to approve in the dashboard. See its header for the approval options.

  ELLIPSIS_API_BASE=http://localhost:5000 ./scripts/smoke.sh

Note: the verification_uri the backend returns points at app.ellipsis.dev unless the container sets ELLIPSIS_APP_BASE_URL=http://localhost:3000, so for local runs prefer smoke-local.sh's headless container approval over the browser link.

Pushing a v* tag triggers .github/workflows/release.yml, which Bun-compiles binaries for macOS and Linux (arm64 + x64), publishes a GitHub release with the tarballs, and regenerates the formula in ellipsis-dev/homebrew-cli.

git tag v2.30.0 && git push origin v2.30.0

The cross-repo push to the tap uses a write-scoped deploy key: the public half is registered on ellipsis-dev/homebrew-cli (Settings → Deploy keys, write access), and the private half is stored as the HOMEBREW_TAP_DEPLOY_KEY secret on this repo. The workflow checks out the tap over SSH with it. A deploy key is scoped to that one repo only — no account-wide PAT involved.

The full public REST surface (auth, sessions, session steps, configs, integration discovery, budget/usage) is wired against the live API, including live WebSocket streaming and session stop. Still pending: replacing the hand-rolled request/response types with the generated @ellipsis/sdk package.