Getting Started

This walks you from zero to a verified change: install the binary, set a provider key, initialize the repo, and run. The full provider matrix (OpenRouter, local servers, Vertex, Bedrock, custom gateways) lives in Providers & models.

1. Set an API key

Stella is bring-your-own-key. Export a key for any one provider — Stella auto-detects it:

export ANTHROPIC_API_KEY=your_key_here   # or OPENAI_API_KEY, GEMINI_API_KEY, ZAI_API_KEY, …

No key handy? Point Stella at a local OpenAI-compatible server instead — see Providers & models.

Confirm what Stella resolved:

stella config    # provider, model, redacted key, base URL, workspace

2. Initialize the repo (recommended)

From inside a project directory:

stella init

This infers a domain taxonomy and builds the tree-sitter code graph the agent queries instead of grepping blind — see Repo initialization. It's optional (and offline-safe), but every session afterwards starts smarter.

3. Run a one-shot prompt

stella run "explain what this repository does, then list the riskiest files"

stella run runs a one-shot, non-interactive task and prints the result. By default it goes through the staged pipeline (triage → plan → execute → verify → judge); --no-pipeline falls back to a single raw step loop. It can read files, run commands, and edit code as needed.

4. Chat interactively

Running stella with no subcommand opens the Command Deck, a tabbed terminal UI. Pass --plain (or set STELLA_PLAIN=1) for a plain line-based REPL instead:

stella

Inside the deck, type a message to send it, or use a slash command to open a tab:

Press Ctrl-C to quit. (The plain REPL has a different, smaller set — including /config and /goal — see stella chat.)

5. Give it a goal

Goal mode works in judged rounds until a separate judge model confirms the objective is met from evidence — not just because the worker says so:

stella goal "the test suite passes and there are no clippy warnings"

See Goal mode for how the judge is chosen and how the loop ends.

6. Pin a specific model (optional)

By default Stella auto-detects the provider. Pin one explicitly with --model:

stella --model anthropic/claude-fable-5 run "refactor the database layer"
stella --model zai/glm-5.2 goal "CI is green on the current branch"

Where to go next

• Providers & models — the full provider matrix and the credential chain.
• The inference pipeline — how work gets verified, not just done.
• Agent modes — deck, run, goal, monitor, fleet: which to use when.
• Configuration — settings.json, per-agent models, credentials.
• Scripting — run Stella headlessly in CI with JSON output.