stella CLI and MCP server

stella is Stella Loop's agent-native public surface. It talks only to the versioned /api/v1 HTTP API; it never imports or calls the Convex runtime. Official release tarballs compile in the deployed public HTTP-action origin; self-hosted installations can override it with STELLA_API_URL or --api-url.

Quick start

Native workspace and release state require a qualified Node.js 22, 24 or 26 runtime with SQLite 3.51.3 or newer in the 3.x series, excluding the withdrawn 3.52.0 release. Use Node.js 24.20.0, 22.23.2 or 26.8.1; these include the upstream WAL-reset corruption fix. An unsupported SQLite build refuses before opening or creating private state. Upgrading the runtime preserves the original installation and journal records.

export STELLA_API_URL=https://your-stella-loop.example
printf %s "$STELLA_API_KEY" | stella auth login --with-key
stella project switch STELLA
stella work list --ready
stella task claim TSK-45
stella context show TSK-45

Use --json for one stable JSON document on stdout (errors are JSON on stderr). stella --help documents the exit-code contract, and every group and leaf has its own synopsis, examples, related commands, and global-option help. stella api <METHOD> <path> is the day-zero escape hatch for any newly landed public endpoint.

Repository initialization and ownership

stella init --dry-run previews repository wiring and private ownership records; stella init --yes applies that plan. Root discovery uses the native adapters for Git, linked Git worktrees, colocated JJ and non-colocated JJ. It does not convert the repository layout. Optional global harness wiring still requires --global-wiring; --yes and role selection do not select it.

The repository's .stella/skills-lock.json is portable schema v3. It records authenticated pack coordinates, hashes, repository-relative skill destinations and roles. Installation identity, physical checkout ownership, global consumers, output hashes and recovery journals live under $STELLA_CONFIG_DIR/initializers (default ~/.stella/initializers), outside repositories. Private storage requires the current OS owner and restrictive POSIX permissions; a Windows ACL adapter is not yet qualified.

Version 2 migration retains its exact preimage in protected host storage and commits the portable lock and its owner in one recoverable transaction. Normal init recovers an interrupted private transaction before planning new changes; --check and --dry-run only report pending recovery. Concurrent edits preserve the affected files and recovery evidence. A legacy repository journal supplies no ownership authority and requires explicit reconciliation before migration.

Copied locks provide dependency metadata without granting ownership. Uninstall removes only unchanged privately owned output; modified or unowned files remain. An unchanged shared global entry remains while another consumer needs it. A legacy lock's global consumer ID is only a lookup hint into an independently validated private selection for that physical checkout.

Gemini wiring requires the qualified Gemini CLI 0.43.0 installation. Init detects .gemini/ or GEMINI.md, or accepts --harness gemini. It inspects public package identity and the supported JSONC settings without starting the provider. Static context.fileName paths determine repository instruction destinations, with GEMINI.md as the default and no duplicate section when AGENTS.md is selected. The adapter respects GEMINI_CLI_HOME and the system settings overrides. Dynamic environment-expanded names, escaping paths and skill-file collisions are refused. Skills go under .gemini/skills; --no-skills excludes them. Role refresh and uninstall use the same private ownership and modified-content checks. Repository wiring does not activate provider trust or establish an authenticated session.

Antigravity is a separate adapter, selected with --harness antigravity. The qualified native agy 1.1.27 binary must match the pinned official executable bytes for macOS/Linux arm64/x64. Inspection does not execute the binary. Init reuses AGENTS.md and installs skills at .agents/skills/<name>/SKILL.md; recorded destinations select the adapter on subsequent runs. Shared .agents or Google files alone do not select it. Existing Gemini configuration is preserved; --harness antigravity,gemini explicitly selects both. No vendor profile or credential import runs. --no-skills omits skills and --check reports executable or installed-content drift. Unknown versions need adapter qualification before mutation. See the Google CLI transition review.

MCP

The MCP server generates its tools from the same capability map as the HTTP router and dedicated CLI commands, so names and schemas cannot drift.

{
  "mcpServers": {
    "stella-loop": {
      "command": "stella",
      "args": ["mcp", "serve"],
      "env": {
        "STELLA_API_URL": "https://your-stella-loop.example",
        "STELLA_API_KEY": "slk_prod_…",
        "STELLA_PROJECT": "STELLA"
      }
    }
  }
}

Stdio is the default transport. For a local Streamable HTTP server:

stella mcp serve --transport http --port 3333

The endpoint is http://127.0.0.1:3333/mcp. Missing or invalid credentials are returned as structured per-tool errors, so the MCP process can start before an ephemeral agent receives its key.

Repository setup

stella init --role orchestrator --yes installs repository-local wiring. Detected Codex settings are optional: preview them with stella init --role orchestrator --global-wiring --dry-run, then use the same selection with --yes to apply it. --no-mcp and --no-codex-agent exclude individual writers. Selecting a role or accepting a plan never selects new global targets on its own.

A normal refresh preserves an unchanged, physically bound prior global selection without writing global files or extending it for new roles. Changed settings and legacy or copied ownership records require explicit review. Global plan entries name their targets and content hashes without printing unrelated private settings. The user-scoped Claude --plugin route, --prune-stale-consumers, and --codex-tool-approval also require --global-wiring; tool approval additionally requires the orchestrator role and its MCP writer.

Authenticated setup broker integration remains a separate implementation gate. Scoped setup credentials cannot grant global host access by adding a flag.

Development gates

pnpm --filter @stella-loop/cli test
pnpm --filter @stella-loop/cli typecheck
pnpm --filter @stella-loop/cli lint
pnpm --filter @stella-loop/cli build

The tests enforce the generated command tree, help bar, capability and MCP parity, resumable event streaming, exit taxonomy, config precedence and file permissions, and the backend-import boundary.