Quickstart & CLI
Get started with stepper and reference the CLI commands, flags, and modes.
Get up and running with stepper in minutes. The CLI offers three ways to use the agent: an interactive TUI, a headless one-shot prompt, or resuming a previous session. Each has its own command and flags.
Quick examples
These examples show the most common ways to invoke stepper.
sh
# Interactive TUI (needs a real terminal + an API key in the env):
STEPPER_ANTHROPIC_API_KEY=sk-... stepper --model anthropic/claude-sonnet-4
# Headless one-shot (streams assistant text to stdout, auto-approves actions):
stepper -p "add a README badge" --model ollama-cloud/qwen3-coder --mode auto
# Resume a previous session:
stepper --resume <session-id>With a .stepper/ directory in your project, you can run stepper without arguments and it will use the configured pipeline, model, and mode.
CLI reference
The full usage line and all available commands and global options.
sh
stepper [OPTIONS] [COMMAND]Commands
| Command | What it does |
|---|---|
| run | Launch the interactive TUI (the default with no subcommand). |
| auth login --codex | Sign in to ChatGPT (OAuth/PKCE) for the Codex backend. |
| auth set-key <provider> | Store a provider API key in the OS keyring (read from stdin). |
| auth delete-key <provider> | Remove a provider key from the OS keyring. |
| config --schema | Print the JSON Schema for setting.json. |
| config --validate | Validate the project's setting.json. |
| doctor | Run integrated diagnostics — config, provider keys, model resolve, MCP, catalog, latest release. |
| session rename <id> <name> | Rename a saved session from the command line. |
| init | Scaffold .stepper/ (detects the stack → stepper.md + setting.json). |
Global options
| Flag | Meaning |
|---|---|
| --model <provider/model-id> | Default model, e.g. anthropic/claude-sonnet-4, ollama-cloud/qwen3-coder, omlx/deepseek-coder. |
| --mode <auto|plan|accept-edits> | Permission mode (precedence: flag > setting.json mode > accept-edits). |
| -p, --print <prompt> | Headless one-shot: run the prompt, stream stdout, auto-approve. |
| --resume <session-id> | Continue a saved session (seeds its prior context). |
| --fallback-model <a,b,c> | Comma-separated model chain tried in order when the primary model fails (CLI wins over setting.json). |
| --output-schema <inline|file> | Headless: force the final response to match a JSON Schema (--output-schema-retries, default 2). |
| --cwd <dir> | Run against another directory. |