Join early access

CLI

stella is Stella Loop’s primary agent surface — a product surface in its own right, not tooling. The founding bet: every coding agent can run a shell command and read --help, so a first-class CLI with an excellent help system is the durable agent interface. The CLI is a strict thin client over the public API — there are no private endpoints behind it.

Install and authenticate

npm install -g @stella-loop/cli
printf %s "$STELLA_API_KEY" | stella auth login --with-key
stella whoami
stella project switch ATLAS

Configuration lives in ~/.stella/config.json (written with owner-only permissions), with per-API-URL credentials. Precedence: flags > environment (STELLA_API_KEY, STELLA_API_URL, STELLA_PROJECT, STELLA_ORG) > stored config. Self-hosted deployments point --api-url (or STELLA_API_URL) at their own origin.

Help is a contract

An agent must be able to operate the product from --help alone — and that is tested, not hoped:

  • Every command documents a synopsis, examples, and related commands; root help ships a “Typical agent session” walkthrough and the exit-code table.
  • Unknown commands get nearest-command suggestions.
  • Group help for epic, proposal, and spec includes the rules that matter — for example, every proposal requires at least one --report at creation.

Contracts every command obeys

  • --json — exactly one stable JSON document on stdout; errors as JSON on stderr. In agent mode (--json or a non-TTY), prompts, colors, and spinners are disabled, and destructive operations require --yes or fail with confirmation_required.
  • Exit codes — 0 ok · 1 runtime · 2 usage · 3 auth · 4 permission · 5 not found · 6 conflict · 7 rate limit · 8 validation. A losing claim race is exit 6, distinguishable from a crash.
  • Transport — automatic idempotency keys on mutations, bounded retries on transient failures honoring Retry-After, and an upgrade notice when the server requires a newer client.
  • Watching — stella events tail --follow and stella activity tail --follow stream server-sent events with resume and duplicate suppression.

The command tree

Generated from the same capability map as the API, so it is always complete. The main groups:

Group What it covers
stella signal / stella capture Capture, list, triage, connectors, demand corpus
stella northstar Documents, versions, diffs, weights, tensions, repo sync
stella intent Create, submit, approve, fire, runs, conclude
stella analyzer / report / score Registry, runs, reports, scores
stella proposal / pool Submit, promote, prune, reorder, dependencies
stella epic List, show, stages, cancel, withdraw-candidate
stella work / task / context / status / session Ready work, claiming, context bundles, status updates, work sessions
stella spec Specs, revisions, approval, decomposition
stella review Rounds, findings, decisions, selection, merge, learnings, seeds
stella loop / approvals / approve / reject / gates / tiers / budgets / costs The loop engine surface
stella inbox / watch / notify Notifications, watching, preferences
stella repo / changeset Repositories, change sets, merges
stella key / webhook / events / search / api Keys, webhooks, the event feed, global search, and the raw escape hatch

stella api <METHOD> <path> is the day-zero escape hatch for any endpoint, and stella completion <bash|zsh|fish> generates shell completions.

MCP server

The same binary serves MCP: stella mcp serve (stdio, or --transport http). See MCP.