Commands

The stella binary is a fast, BYOK (bring-your-own-key), model-agnostic terminal coding agent. Every feature is available through a subcommand.

Running stella with no subcommand opens the Command Deck, a tabbed terminal UI. This is the same as running stella chat. Pass --accessible (or set STELLA_ACCESSIBLE=1) to run that same deck so a screen reader can read it. Pass --plain (or set STELLA_PLAIN=1) for a plain line-based REPL instead. The deck also steps aside automatically when stdin or stdout is not a terminal.

# These two invocations are identical
stella
stella chat

Subcommands

Run the agent

Run many at once

Ask about this workspace

Steer what the agent knows

What it cost, what happened

Set up

stella arena is a benchmark-harness adapter for measuring stella, not for doing work with it. stella telemetry operates the managed enterprise spool and is disabled without a signed org-managed enrollment.

Global flags

The following flags apply to every command. Most have a matching environment variable, so you can set one once for a shell session or in your CI configuration. The exception is --api-key, which has no environment variable on purpose. Use credentials.toml or a provider key environment variable such as ANTHROPIC_API_KEY instead.

Every flag below works in either position: stella --spend-limit 5 run "…" and stella run "…" --spend-limit 5 do the same thing. No subcommand reuses these flag names for something else.

--upstream-pin: holding the vendor fixed

Only a gateway routes to another vendor's hardware, so this applies to OpenRouter, where it sets provider.order and allow_fallbacks: false. It does nothing on a direct endpoint.

stella run "…" --model openrouter/anthropic/claude-fable-5 \
  --upstream-pin z-ai --upstream-pin anthropic

Use it when two runs must be comparable. A gateway otherwise picks per app identity and may serve the same model from a different vendor between runs, which quietly changes the one thing a head-to-head comparison is supposed to hold fixed. It's a flag rather than a settings-only option because a measured trial runs with settings isolation (STELLA_NO_SETTINGS), where a flag is the only way to reach it. That's also why --base-url is a flag.

--tools: narrowing for one run

The value is a comma-separated list of name:on / name:off, where a name is a tool, a group, or *. It uses the same format as the settings tools table, so you can try a policy before writing it to a file.

stella run "triage the board" --tools '*:off,task_list:on,get_state:on,list_state:on'
stella run "ship the fix"     --tools 'task_assign:off'

This flag can only take capability away, never add it: turning something off is always allowed, and turning something on never overrides a deny from an org or project policy.

Diagnostics: -v, --log-level, --log-file

The diagnostic output explains why stella behaved the way it did. This is different from what the agent did (the event stream) and what it cost (the receipts). Diagnostic records carry a stable code and typed fields, and never include prompts, paths, or model output.

stella run "…" -vv                                   # debug everywhere
stella run "…" --log-level 'warn,stella_model=trace' # quiet except where you are looking
stella run "…" --log-file ./run.jsonl                # JSONL to a file, created 0600

A target is a Rust module path, so library modules are stella_store, stella_model, and so on, and the binary's own records are under stella (hyphens work too). The longest match wins. An unrecognized clause is reported and skipped rather than treated as fatal. Levels are off, error, warn, info, debug, trace.

You don't need a flag to catch an unplanned crash: stella writes .stella/private/crash-*.jsonl on a panic or a failed run, and stella doctor --last-failure prints the newest one.

--output-format (a flag of run and fleet, not a global)

--output-format <text|json|stream-json> (env STELLA_OUTPUT_FORMAT) is not in the table above on purpose. It's a promise about what reaches stdout, and only the commands that keep that promise offer it: stella run and stella fleet. As a subcommand flag, it goes after the subcommand — stella run "…" --output-format json — and using it anywhere else is a parse error, not a flag that's silently ignored. stella arena always emits stream-json, since the benchmark runner is its only reader. The interactive chat, goal, and monitor modes always render text, and query commands with a machine-readable shape declare their own flag (stella stats --format json, stella inspect --format json, stella memory list --format json).

--spend-limit modes

Token usage, cost, and per-step metering are recorded in a local SQLite store on your disk (<workspace>/.stella/private/store.db). Nothing is sent anywhere. See stella stats.

Model selection

If you do not pass --model, stella auto-detects a provider by picking the first one with a usable credential, in this order:

zai, anthropic, openai, xai, deepseek, gemini, openrouter, then vertex, and bedrock LAST

vertex and bedrock are checked last so that generic AWS or Google credentials present for other reasons never get picked by accident. To be explicit, pin a model with --model provider/model_id.

Exit codes

Every command follows standard shell conventions:

The signal range exists so a script wrapping stella run can tell "the user stopped this" from "this failed" — different outcomes that usually need different handling:

stella run "Fix the failing tests"
case $? in
  0)   echo "done" ;;
  130) echo "interrupted — nothing to report" ;;
  *)   echo "run failed" ;;
esac

This makes stella safe to use in scripts and CI pipelines. Check $? (or rely on set -e) to react to failures.