Quickstart

Set a key, run your first task, and let a judge verify your first goal — about five minutes end to end.

This page assumes the stella binary is on your PATH (installation guide).

1. Set a provider key

Stella is bring-your-own-key. Export a key for any supported provider and Stella detects it automatically:

export ANTHROPIC_API_KEY=your_key_here
# or OPENAI_API_KEY, GEMINI_API_KEY, XAI_API_KEY, DEEPSEEK_API_KEY,
# ZAI_API_KEY, OPENROUTER_API_KEY, … (full matrix in Models and providers)

No key at all? Point Stella at a local OpenAI-compatible server instead:

stella --model local/llama3.3 --base-url http://localhost:11434/v1

Confirm what Stella sees:

stella models

2. Chat

cd your-project/
stella

stella with no arguments opens an interactive REPL. Type a prompt and press Enter. Stella thinks (with a live spinner), calls tools as needed (reading files, running commands, searching code), shows its response, and prints a cost and token summary for the turn.

Useful in-chat commands: /files shows the Files Touched panel ([C|R|U|D] per file), /models and /config show configuration, /help lists everything, and Ctrl+D exits. The full list is in Commands.

3. One-shot run

For a single task with no REPL, use run:

stella run "fix the failing test in src/auth.rs"
stella run "add a health check endpoint to the API"

4. Your first judged goal

run executes a task; goal keeps working, in rounds, until an LLM judge confirms the goal is met from evidence:

stella --budget 5 goal "the parser handles CRLF files and tests pass"

Each round, the worker makes changes test-first, then the verify_done gate checks the witness test: it must fail on your previous code (git HEAD, replayed in a shadow worktree with only the new test files layered in) and pass on the new code. After the round, the judge re-checks the goal with its own read-only tools (read_file, grep, glob, ci_status) — its feedback drives the next round. The run ends on WITNESS CONFIRMED plus a satisfied judge, a round cap, or your budget.

--budget 5 is a hard limit: Stella meters every model call against the model card's pricing and aborts cleanly (never mid-tool) once total spend crosses $5.00. Omit it and spend is metered for reporting only.

5. Where next

Pin models per task: stella --model openai/gpt-5.5 run "…" — see Models and providers.
Drive CI to green: stella monitor main — see Commands.
Teach it your codebase's lessons: markdown files in .stella/memories/ load into the system prompt at session start.
Inspect everything it did: the full event stream and cost telemetry live in .stella/stella.duckdb — open it with any DuckDB client.