# CLI guide
## Scope
Parses Clap arguments, validates launch modes, and hands work to runtime owners.
## Where to look
| Arguments, subcommands, startup routing | `mod.rs` |
| Cross-flag/mode validation | `validation.rs` |
| Mission Control startup and service handoff | `mod.rs` |
| Session operations | `sessions.rs` |
| MCP commands | `mcp.rs` |
| Private Unix daemon start/status/stop/foreground | `mod.rs` (`DaemonCommand`), `../service/unix.rs` |
## Local rules
- Keep invalid usage distinct from runtime failure: `AppError::Usage` exits with 2; `AppError::Runtime` exits with 1.
- `--update` is standalone maintenance before TTY/config/provider/session initialization. TUI update handoffs contain restart data only; update and restart after terminal cleanup, app drop, writer-lease release, and Herdr release.
- Validate launch combinations before session/worker/provider side effects. Application-service mode rejects prompt, provider/model/auth, appearance, session-selection, and subcommand inputs intended for normal startup.
- Keep parsing in Clap types and cross-mode rules in `validation.rs`; do not scatter alternate argument parsing into runtime modules.
- Pass CLI overrides into configuration resolution instead of recreating provider/auth precedence in handlers.
- Default launch hands off to the worker-backed Mission Control runtime and requires TTY stdin/stdout. `--prompt` queues its initial input; `--app service` is the non-interactive conversation interface.
- Do not restore print mode, positional prompts, `--tui`, `--color`, or a text REPL.
- Session and MCP subcommands call their owning subsystems; CLI errors must not expose credentials or raw sensitive responses.