Commands
Every Stella subcommand, global flag, REPL command, and built-in tool.
Global flags
These apply to every subcommand and can also be set by environment variable. Pass them before the subcommand: stella --budget 5 goal "…", not stella goal "…" --budget 5.
| Flag | Env var | What it does |
|---|---|---|
--model <provider/model> | STELLA_MODEL | Pin the worker model for this invocation, e.g. anthropic/claude-fable-5, openai/gpt-5.5, zai/glm-5.2. |
--api-key <key> | — | Highest-precedence step of the credential chain. Prefer an env var or ~/.config/stella/credentials.toml for anything long-lived; a flag value is visible in shell history and ps. |
--base-url <url> | STELLA_BASE_URL | Required with --model local/<model> to point at a local OpenAI-compatible server; optional for other providers to route through a proxy or gateway. |
--output-format <fmt> | STELLA_OUTPUT_FORMAT | text (default, interactive) or json (headless, for scripts). |
--budget <usd> | STELLA_BUDGET | Hard USD spend limit for the whole run or session. Work aborts cleanly (never mid-tool) once total spend exceeds it. Omit to meter spend for the cost summary without ever blocking. |
Subcommands
Interactive chat
stella # chat is the default
stella chatOpens the interactive REPL: type a prompt, Stella thinks, calls tools, responds, and prints a per-turn cost and token summary.
run — one-shot task
stella run "fix the failing test in src/auth.rs"Sends a single prompt non-interactively and exits when the task completes. Combine with --output-format json for scripting.
goal — judged rounds
stella goal "the login flow has a passing e2e test and CI is green"Works in rounds until an LLM judge confirms the goal is met from evidence. The judge has its own read-only tools (read_file, grep, glob, explorations, ci_status) to verify claims directly; its feedback drives the next round. Bounded by a round cap and --budget.
monitor — CI to green
stella monitor # defaults to main
stella monitor my-branch # branch name or PR numberWatches CI for a branch or PR via the gh CLI, reads failure logs, and fixes failures until the run is fully green — CI-to-green as a judged goal.
models, config, version
stella models # every provider, its models, and key status
stella config # the current resolved configuration
stella version # print the version and exit (also: stella --version)REPL commands
Inside stella chat:
| Command | What it does |
|---|---|
/goal <text> | Work in judged rounds until the goal is met |
/files | Show the Files Touched panel ([C|R|U|D] per file) |
/models | List configured providers and models |
/config | Show current configuration |
/rename <name> | Rename this terminal tab |
/color <name> | Switch the accent color (tell windows apart) |
/clear | Clear conversation history |
/help | Show help |
/exit or Ctrl+D | Exit Stella |
Built-in tools
The worker's toolbox. All file tools are pinned to the workspace root, and every successful create, read, update, or delete lands in the Files Touched ledger.
| Tool | Description |
|---|---|
read_file | Read a file with line numbers (supports offset/limit) |
write_file | Create or overwrite a file (creates parent dirs) |
edit_file | Replace an exact substring in a file (surgical edits) |
delete_file | Delete a workspace file (completes the CRUD ledger) |
bash | Run a shell command (timeout kill; trace: true echoes each line) |
grep | Search file contents with regex (shells to ripgrep) |
glob | Find files matching a glob pattern (shells to fd) |
build_project | Build with the workspace's own toolchain (cargo/npm/go/make) |
run_tests | Run tests — kind unit/e2e/all plus a runner-native filter |
verify_done | The deterministic definition of done: witness test must fail on git HEAD and pass on the new code |
explorations / save_exploration | Shared codebase maps — explore once, reuse everywhere |
save_memory | Persist a lesson for every future session's prompt |
ci_status | CI runs and failure logs via gh (judge-usable, read-only) |
screenshot | Capture the screen as verification evidence |
create_issue, update_issue, close_issue, search_issues, start_work_on_issue | Issue tracking — loaded only when configured |
Issue tools are conditional: set LINEAR_API_KEY for the Linear backend (it wins), or have gh auth login done for GitHub Issues. With neither, the tools aren't registered at all — no dead schema, no wasted tokens.
Workspace state
Stella keeps everything it learns and records inside your repository and your home directory — nowhere else:
.stella/stella.duckdb— the full event stream, per-call token/cost telemetry, the files-touched ledger, and the graph tables the context plane writes into. Open it with any DuckDB client..stella/memories/— markdown lessons (yours andsave_memory's) loaded into a byte-stable system prompt at session start. New memories take effect next session by design: hot-injection would invalidate the prompt cache on every save.~/.config/stella/credentials.toml— long-lived provider credentials, the third step of the credential chain (flag → env var → credentials file → interactive prompt).