CLI

The Ellipsis CLI is a single binary named agent that drives the same /v1 REST API from your terminal. It is a thin, open-source client: the agent runs in the Ellipsis cloud; the CLI authenticates, starts sessions, and reads results.

Install

brew install ellipsis-dev/cli/agent
agent ping    # confirms the CLI can authenticate and reach /v1

Authenticate

Interactive use: log in once. agent login runs a device-code flow (prints a verification URL, opens it unless --no-browser, polls until you approve). The user token lands in ~/.config/ellipsis/config.json and attributes sessions to you.

agent login              # --no-browser over SSH
agent me                 # identity behind the current credential
agent logout             # remove the stored token

Scripts and CI: create an API key and export it as ELLIPSIS_API_TOKEN instead of logging in. Credentials resolve highest-wins: explicit argument, then ELLIPSIS_API_TOKEN, then the stored config file. 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, search, and hand off sessions for you. Install it once:

npx skills add ellipsis-dev/cli

That copies skills/ellipsis/ from the public ellipsis-dev/cli repository into your coding agent's skills directory (for example .claude/skills/). The agent loads it by name the next time a task mentions Ellipsis or the agent CLI. To pin it globally instead, copy the same directory into ~/.claude/skills/.

Start a session

A config source is optional. With none, the session runs on your team's default agent: the repository default for the repo you are standing in if one is set, else the account default, else a bare ad-hoc config (an empty system prompt on claude-opus-4-8, no triggers). The prompt is the sole per-session instruction, so a positional prompt is enough:

agent session start "triage the failing CI on splitshift-api"

When a default resolved, the CLI says which agent picked up the work:

using config "CI failure triager" (repo default)
✓ started session session_7Hq2mX4p (scheduled)

The CLI also detects the repository you are standing in (the origin remote, as owner/name) and sends it with the request. The server clones that repository into the sandbox at its default branch, on top of whatever the config declares, even when you pass --config. Outside a git repository, nothing is sent. To hand off uncommitted work instead of the default branch, use agent session handoff.

The positional prompt is shorthand for -p/--prompt; pass one or the other, not both. To start from a saved config, an inline config file, or a built-in template, pass at most one of --config (a saved config id), --config-file, or --template:

agent session start --config agent_x9Kd3Fq2
agent session start --config-file my_agent.json
agent session start --template welcome-to-ellipsis --watch

Sugar flags set individual config fields for one session without editing a config: --model, --system (the system prompt), --repo (repeatable, owner/name or a bare name), --cpu, --memory, --timeout, and --budget (per-run USD, limits.run). They merge into one override on top of the chosen or default config; --config-override and --config-override-file take a full partial config.

agent session start "audit the trade-expiry changes" \
  --repo splitshift-api --model claude-opus-4-8 --budget 5

By default start returns as soon as the session is created (-d/--detach). To block until it reaches a terminal status, pass one attach mode: -w/--watch streams live output; --watch --quiet blocks without streaming and exits with a code matching the outcome, for scripts; --connect waits for the sandbox, then opens the interactive view. If the resolved config sets interactive: false, --connect degrades to --watch with a printed note (the backend refuses the message surface for non-interactive sessions).

List, inspect, follow, and stop sessions:

agent session list --limit 20                    # filter with --config, --source, --author, --days
agent session get session_7Hq2mX4p               # inspect one session
agent session get session_7Hq2mX4p --watch       # follow until it finishes (--quiet for the result only)
agent session steps session_7Hq2mX4p             # render the session's steps, one line each
agent session transcript session_7Hq2mX4p -o run.jsonl   # download the raw transcript (.jsonl)
agent session stop session_7Hq2mX4p              # stop an in-flight session

Connect to a running session to follow it live and send messages, or follow read-only:

agent session connect session_7Hq2mX4p              # view, follow live, and send messages
agent session connect session_7Hq2mX4p --no-input   # follow read-only (no composer), for scripts

--no-steps skips replaying prior steps on open.

Replay a finished session, optionally with changes (--config, --config-override, --prompt, --watch, --quiet):

agent session replay session_7Hq2mX4p

Search session history

agent session search runs the same four-arm session search as the API: step text, recap text, created pull requests, and recap similarity. Results are grouped by session, newest first, with the matching snippet under each.

agent session search "shift trade webhook"
agent session search "acme/api#512"              # the session that created that pull request
agent session search "webhook retries" --author tony --since "3 days ago"

--author takes a GitHub login and resolves it against agent github members (it also works on agent session list). --since and --until accept ISO 8601 or the natural forms today, yesterday, and N days ago. Narrow further with --repo, --source, --status, --config (a config id, repeatable), --session, and --scope steps|recaps|both. Follow a hit with agent session get for the recap and agent session steps for the full steps.

Sync local Claude Code sessions

agent hooks manages local session sync: Claude Code hooks that upload each session you run in an enrolled repository, so laptop work appears in the same session history as cloud work.

agent hooks install            # write the Stop + SessionEnd hooks to ~/.claude/settings.json
agent hooks enroll             # opt the cwd's repository in (or pass owner/name)
agent hooks status             # hook state, enrolled repositories, last sync
agent hooks logs --failures    # the sync activity log (-n to tail, --json for NDJSON)
agent hooks stats              # sync counters, also in ~/.config/ellipsis/hooks/stats.json
agent hooks unenroll           # opt a repository back out
agent hooks uninstall          # remove the hooks; enrollment is kept

agent session sync is the upload itself, normally invoked by the hooks with their context on stdin; --transcript, --session-id, --reason, and --cwd exist for manual runs. agent session handoff "<instructions>" --parent <session_id> pushes a snapshot of your working tree and continues a synced session in the cloud.

Manage configs

agent config init agents/my_agent.yaml   # scaffold a starter config
agent config list                        # list saved configs
agent config get agent_x9Kd3Fq2          # print one config as YAML (-o json)

agent config create creates an agent the same way the dashboard does: Ellipsis opens a pull request adding the config file to your repository, and the agent goes live when it merges.

agent config create --repo api --file agents/foo.yaml   # from a local config file
agent config create --repo api --template code-reviewer   # from a template

agent template list prints the built-in templates with their slugs; a slug works anywhere a template is accepted (agent session start --template, agent config create --template).

Default agents

agent config default (alias defaults) manages which agent a session runs when you name no config source: the defaults ladder of repository default, then account default, then a bare ad-hoc config. Every verb maps to the /v1/defaults endpoints.

agent config default                     # the effective default for the repo you are standing in
agent config default list                # every rung that is set, account and per-repo
agent config default set agent_x9Kd3Fq2            # set the ACCOUNT default
agent config default set agent_x9Kd3Fq2 --repo     # set the default for the repo you are standing in
agent config default set agent_x9Kd3Fq2 --repo acme/api   # set a named repo's default
agent config default clear --repo acme/api         # clear a rung (alias rm)

Bare agent config default reads like session start resolves: the repo default for your origin remote if set, else the account default, else no default set (sessions start on the bare config).

$ agent config default
using config "CI failure triager" (repo default for acme/api)

Writes are always explicit about their target: without --repo they address the account default, --repo with no value addresses the repo you are standing in, and --repo owner/name addresses that repository. A rung pointing at a config that was deleted, disabled, or never merged shows broken: <reason> in list; sessions refuse to start on it until you fix or clear it. Sandbox tokens can read but not set or clear (the server's 403), so an agent cannot repoint your account's default.

Assets

agent asset manages assets: PNG images an agent stores past its sandbox, each behind an org-gated link. Every verb maps to the /v1/assets endpoints.

agent asset upload schedule-grid.png       # store a PNG; prints its org-gated link
agent asset list                           # stored assets, newest first (--session scopes to one run)
agent asset get 9f2c4b7d1e8a4c02b6f3a1d5e7c90842 -o schedule-grid.png   # show one, or -o downloads the bytes
agent asset delete 9f2c4b7d1e8a4c02b6f3a1d5e7c90842     # delete an asset (alias rm)

delete prints ✓ deleted <asset-id> on success. A missing, foreign, or already-deleted id prints asset not found: <asset-id> and exits nonzero. Sandbox tokens can't delete, so an agent's own token gets the server's 403. Every verb accepts --json.

Sandbox variables

agent sandbox variable (alias var) manages the write-only sandbox variable store that sandbox.variables entries resolve from. Values can be written and deleted but never read back.

agent sandbox variable list                    # names and timestamps; values stay hidden
agent sandbox variable set LOG_LEVEL=debug     # inline KEY=VALUE pairs
agent sandbox variable set --from-file .env    # or load from a .env or flat-JSON file
agent sandbox variable rm NPM_TOKEN            # delete one variable

set accepts inline pairs, --from-file, or both; file pairs load first, so an inline pair with the same name wins.

Sandbox builds

agent sandbox build (alias builds) runs a config's environment definition (base image plus dockerfile_append, repository checkout, image.setup, snapshot) without starting an agent, and caches the resulting image for future sessions. The workflow: Set up your agent's cloud development environment.

agent sandbox build start --config-file agents/foo.yaml --watch   # build a local config, stream to completion
agent sandbox build start --config agent_x9Kd3Fq2                 # re-verify a deployed config's image
agent sandbox build list                                          # recent builds, newest first
agent sandbox build get build_3fKq82Lm                            # status, phase timings, cache tier, cost
agent sandbox build logs build_3fKq82Lm --watch                   # persisted log; --watch follows live

start takes exactly one of --config-file or --config, plus --hooks to also run the config's post_start and post_clone hooks in the built sandbox. Like session start, it returns the build record immediately; --watch streams the build and exits with a code matching the outcome. Builds bill compute only, never tokens.

Discover integrations

The discovery commands mirror the integration discovery endpoints: what is connected and which repositories, channels, teams, and people a config can name.

agent integrations      # every connected integration, in one table
agent github repos      # repositories connected to the installation
agent github members    # org roster, 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 github members lists the logins --author accepts. The Slack and Linear commands report "not connected" when that integration is not set up; Sentry lists nothing.

Analytics

agent analytics mirrors the analytics endpoints: the same pull request and review aggregation as the dashboard, from the terminal.

agent analytics reviewers --account-type bot    # which apps review the most PRs
agent analytics prs --days 90                   # PR volume and trend, human vs bot
agent analytics reviews --repo splitshift-api   # review totals, verdicts, top reviewers

All three take the window flags -d/--days (default 30, mutually exclusive with --start) and --start/--end (ISO timestamps). --account-type is all, user (humans), or bot (apps and agents). reviewers adds -r/--repo (repeatable), --sort reviews|approved|changes-requested|comments|lines, and -l/--limit (default 10). prs adds --status open|draft|merged|closed (repeatable). reviews adds --author (reviewer login) and --review-state APPROVED|CHANGES_REQUESTED|COMMENTED (both repeatable).

Budget and usage

agent budget    # current spend against every limit
agent usage     # usage dashboard for the period

Notes

• Most commands accept --json to print the raw API response for piping into jq.
• Every command maps to the public REST API; anything the CLI does you can do over HTTP.
• agent --help and agent <command> --help list every command and flag.