Commands

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

Running stella with no subcommand opens the Command Deck — a tabbed terminal UI — exactly as if you had run stella chat. 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

Each command page in this section documents its usage synopsis, behavior, relevant flags, and realistic examples.

Global flags

The following flags apply to every command. Most have a corresponding environment variable so you can set it once for a shell session or in your CI configuration — the exception is --api-key, which is intentionally env-less (use credentials.toml or a provider key env var such as ANTHROPIC_API_KEY instead).

Because these are top-level flags, place them before the subcommand — e.g. stella --output-format json run "…", not stella run "…" --output-format json.

--output-format values

--budget modes

Token usage, cost, and per-step metering are recorded in a local SQLite store on your disk (<workspace>/.stella/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 resolvable credential, in this preference 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 hijack selection. To be explicit, pin a model with --model provider/model_id.

Exit codes

Every command follows standard shell conventions:

This makes Stella safe to compose in scripts and CI pipelines — check $? (or rely on set -e) to react to failures.