CLI Reference
This page is grounded in crates/cli/src/cli.rs.
Binary
swarmie [COMMAND]If no command is provided, Swarmie starts the interactive REPL.
Commands
prompt (alias: p)
Run Swarmie non-interactively.
swarmie prompt [PROMPT]PROMPT behavior:
- If omitted, reads from stdin.
- If set to
-, reads from stdin.
Options:
| Flag | Type | Description |
|---|---|---|
-c, --config <key=value> | repeatable string | Override config value (dotted path supported, value parsed as TOML when possible). |
-m, --model <MODEL> | string | Model to use. |
--provider <PROVIDER> | string | Provider to use. |
-p, --profile <CONFIG_PROFILE> | string | Config profile from config.toml. |
--dangerously-bypass-approvals | bool | Bypass approval prompts in non-interactive runs. |
-C, --cd <DIR> | path | Working directory root for the agent. |
--json | bool | Print events to stdout as JSONL. |
--worktree | bool | Run the headless session in an isolated git worktree. |
--worktree-result <commit|apply|stash> | enum | Post-run strategy for worktree changes (default: commit). |
Examples:
swarmie prompt "Summarize this repo"
swarmie prompt -m sonnet -p work
cat prompt.txt | swarmie prompt -
swarmie prompt "Explain src" --json
swarmie prompt "Review changes" --worktree
swarmie prompt "Draft fix" --worktree --worktree-result apply
swarmie prompt "Try risky refactor" --worktree --worktree-result stash
swarmie prompt "Inspect another checkout" -C ../project --worktreeresume
Resume an interactive session.
swarmie resume [--last]Options:
| Flag | Type | Description |
|---|---|---|
--last | bool | Continue most recent session for current workspace. |
web
Start HTTP server and open web interface.
swarmie web [OPTIONS]Options:
| Flag | Type | Default | Description |
|---|---|---|---|
--port <PORT> | u16 | 4200 | Port to listen on. |
--hostname <HOSTNAME> | string | 127.0.0.1 | Hostname/interface to bind. |
--password <PASSWORD> | string | none | Bootstrap password for first-run local auth setup (prefer SWARMIE_SERVER_PASSWORD). |
--cors <ORIGIN> | repeatable string | none | Additional CORS origins. |
--no-open | bool | false | Do not open browser automatically. |
server
Start HTTP server in headless API-only mode.
swarmie server [OPTIONS]Options:
| Flag | Type | Default | Description |
|---|---|---|---|
--port <PORT> | u16 | 4200 | Port to listen on. |
--hostname <HOSTNAME> | string | 0.0.0.0 | Hostname/interface to bind. |
--password <PASSWORD> | string | none | Bootstrap password for first-run local auth setup (prefer SWARMIE_SERVER_PASSWORD). |
--cors <ORIGIN> | repeatable string | none | Additional CORS origins. |
--tls | bool | false | Enable TLS-aware auth cookie behavior. |
--behind-proxy | bool | false | Trust proxy forwarding headers for locality detection. |
--auth-db-path <PATH> | path | none | Optional auth SQLite DB path. |
Notes
swarmie webresolves bootstrap password from--passwordfirst, thenSWARMIE_SERVER_PASSWORD.swarmie serverresolves bootstrap password from--passwordfirst, thenSWARMIE_SERVER_PASSWORD.- HTTP auth uses session cookies and scoped API keys; password is used for setup/login only.
swarmie promptexits non-zero on startup/runtime failures and auto-denies permissions unless bypass is set.--worktreevalidates git prerequisites and may auto-stash a dirty tree before session start.- On teardown failure, Swarmie prints a warning and keeps the session exit code unchanged.