bot/docs/cli/models.md

summary, read_when, title

summary	read_when	title
CLI reference for `hanzo-bot models` (status/list/set/scan, aliases, fallbacks, auth)	You want to change default models or view provider auth status You want to scan available models/providers and debug auth profiles	models

hanzo-bot models

Model discovery, scanning, and configuration (default model, fallbacks, auth profiles).

Related:

• Providers + models: Models
• Provider auth setup: Getting started

Common commands

hanzo-bot models status
hanzo-bot models list
hanzo-bot models set <model-or-alias>
hanzo-bot models scan

hanzo-bot models status shows the resolved default/fallbacks plus an auth overview. When provider usage snapshots are available, the OAuth/token status section includes provider usage headers. Add --probe to run live auth probes against each configured provider profile. Probes are real requests (may consume tokens and trigger rate limits). Use --agent <id> to inspect a configured agent’s model/auth state. When omitted, the command uses BOT_AGENT_DIR/PI_CODING_AGENT_DIR if set, otherwise the configured default agent.

Notes:

• models set <model-or-alias> accepts provider/model or an alias.
• Model refs are parsed by splitting on the first /. If the model ID includes / (OpenRouter-style), include the provider prefix (example: openrouter/moonshotai/kimi-k2).
• If you omit the provider, Hanzo Bot treats the input as an alias or a model for the default provider (only works when there is no / in the model ID).

models status

Options:

• --json
• --plain
• --check (exit 1=expired/missing, 2=expiring)
• --probe (live probe of configured auth profiles)
• --probe-provider <name> (probe one provider)
• --probe-profile <id> (repeat or comma-separated profile ids)
• --probe-timeout <ms>
• --probe-concurrency <n>
• --probe-max-tokens <n>
• --agent <id> (configured agent id; overrides BOT_AGENT_DIR/PI_CODING_AGENT_DIR)

Aliases + fallbacks

hanzo-bot models aliases list
hanzo-bot models fallbacks list

Auth profiles

hanzo-bot models auth add
hanzo-bot models auth login --provider <id>
hanzo-bot models auth setup-token
hanzo-bot models auth paste-token

models auth login runs a provider plugin’s auth flow (OAuth/API key). Use hanzo-bot plugins list to see which providers are installed.

Notes:

• setup-token prompts for a setup-token value (generate it with claude setup-token on any machine).
• paste-token accepts a token string generated elsewhere or from automation.