# `Pixir.CLI`
[🔗](https://github.com/Ranvier-Technologies/pixir/blob/main/lib/pixir/cli.ex#L1)

Escript entry point — one-shot, print-first (ADR 0001). Commands:

    pixir login              Browser OAuth (device-code fallback) → ~/.pixir/auth.json
    pixir doctor             Run local first-run diagnostics (no network)
    pixir models             Show local provider model catalogs (no network)
    pixir models refresh     Explicitly refresh supported provider catalogs
    pixir gc                 Plan isolated Subagent workspace reclamation
    pixir tree <id>          Project a Session/Subagent tree from local Logs
    pixir compact <id>       Record a durable History compaction checkpoint
    pixir fork <id>          Create a child Session from a parent History prefix
    pixir inspect-replay <id> Inspect Provider replay input without network
    pixir delegate           Validate or run a Delegate CLI spec
    pixir [--web-search] [--attach PATH] "prompt"           Run one Turn in the current directory, stream to stdout
    pixir [--json] [--attach PATH] [--bash-timeout-ms N] --write-policy <policy.json> "prompt"
                             Run a bounded-write headless Turn with JSON output
    pixir resume <id> [--web-search] [--attach PATH] "..."  Continue a persisted Session
    pixir acp                Speak Agent Client Protocol over stdio (ADR 0009)
    pixir help               Show help

Channel discipline (ADR 0005): the model's answer goes to **stdout**; prompts,
activity, diagnostics, and the resumable session id go to **stderr**. A prompt may be
passed as an argument or piped on **stdin**. Exit code is non-zero on error.
`--ask` is intentionally interactive-only; headless orchestrators should use
`--read-only`, explicit auto-mode approval, or a bounded write policy instead of
silently denying every write prompt. `--write-policy` and `--bash-timeout-ms` are
one-shot/resume runtime options: write policy requires auto mode, carries bounded
write/edit allowlists into Subagents and Workflows, disables mutating shell commands
in v1, and can pair with `--json` for one final machine-readable stdout envelope.

# `main`

```elixir
@spec main([String.t()]) :: no_return()
```

# `route`

```elixir
@spec route([String.t()], Pixir.Permissions.mode()) ::
  :ok | {:error, non_neg_integer()}
```

Pure-ish router (permission mode defaults to config or `:auto`). IO happens inside.

---

*Consult [api-reference.md](api-reference.md) for complete listing*