> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluffbuzz.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Models

# `fluffbuzz models`

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

Related:

* Providers + models: [Models](/providers/models)
* Model selection concepts + `/models` slash command: [Models concept](/concepts/models)
* Provider auth setup: [Getting started](/start/getting-started)

## Common commands

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fluffbuzz models status
fluffbuzz models list
fluffbuzz models set <model-or-alias>
fluffbuzz models scan
```

`fluffbuzz models status` shows the resolved default/fallbacks plus an auth overview.
When provider usage snapshots are available, the OAuth/API-key status section includes
provider usage windows and quota snapshots.
Current usage-window providers: Anthropic, GitHub Copilot, Gemini CLI, OpenAI
Codex, MiniMax, Xiaomi, and z.ai. Usage auth comes from provider-specific hooks
when available; otherwise FluffBuzz falls back to matching OAuth/API-key
credentials from auth profiles, env, or config.
In `--json` output, `auth.providers` is the env/config/store-aware provider
overview, while `auth.oauth` is auth-store profile health only.
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 `FLUFFBUZZ_AGENT_DIR`/`PI_CODING_AGENT_DIR` if set, otherwise the
configured default agent.
Probe rows can come from auth profiles, env credentials, or `models.json`.

Notes:

* `models set <model-or-alias>` accepts `provider/model` or an alias.
* `models list --all` includes bundled provider-owned static catalog rows even
  when you have not authenticated with that provider yet. Those rows still show
  as unavailable until matching auth is configured.
* `models list --provider <id>` filters by provider id, such as `moonshot` or
  `openai-codex`. It does not accept display labels from interactive provider
  pickers, such as `Moonshot AI`.
* 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, FluffBuzz resolves the input as an alias first, then
  as a unique configured-provider match for that exact model id, and only then
  falls back to the configured default provider with a deprecation warning.
  If that provider no longer exposes the configured default model, FluffBuzz
  falls back to the first configured provider/model instead of surfacing a
  stale removed-provider default.
* `models status` may show `marker(<value>)` in auth output for non-secret placeholders (for example `OPENAI_API_KEY`, `secretref-managed`, `minimax-oauth`, `oauth:chutes`, `ollama-local`) instead of masking them as secrets.

### `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 `FLUFFBUZZ_AGENT_DIR`/`PI_CODING_AGENT_DIR`)

Probe status buckets:

* `ok`
* `auth`
* `rate_limit`
* `billing`
* `timeout`
* `format`
* `unknown`
* `no_model`

Probe detail/reason-code cases to expect:

* `excluded_by_auth_order`: a stored profile exists, but explicit
  `auth.order.<provider>` omitted it, so probe reports the exclusion instead of
  trying it.
* `missing_credential`, `invalid_expires`, `expired`, `unresolved_ref`:
  profile is present but not eligible/resolvable.
* `no_model`: provider auth exists, but FluffBuzz could not resolve a probeable
  model candidate for that provider.

## Aliases + fallbacks

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fluffbuzz models aliases list
fluffbuzz models fallbacks list
```

## Auth profiles

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fluffbuzz models auth add
fluffbuzz models auth login --provider <id>
fluffbuzz models auth setup-token --provider <id>
fluffbuzz models auth paste-token
```

`models auth add` is the interactive auth helper. It can launch a provider auth
flow (OAuth/API key) or guide you into manual token paste, depending on the
provider you choose.

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

Examples:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fluffbuzz models auth login --provider openai-codex --set-default
```

Notes:

* `setup-token` and `paste-token` remain generic token commands for providers
  that expose token auth methods.
* `setup-token` requires an interactive TTY and runs the provider's token-auth
  method (defaulting to that provider's `setup-token` method when it exposes
  one).
* `paste-token` accepts a token string generated elsewhere or from automation.
* `paste-token` requires `--provider`, prompts for the token value, and writes
  it to the default profile id `<provider>:manual` unless you pass
  `--profile-id`.
* `paste-token --expires-in <duration>` stores an absolute token expiry from a
  relative duration such as `365d` or `12h`.
* Anthropic note: Anthropic staff told us FluffBuzz-style Claude CLI usage is allowed again, so FluffBuzz treats Claude CLI reuse and `claude -p` usage as sanctioned for this integration unless Anthropic publishes a new policy.
* Anthropic `setup-token` / `paste-token` remain available as a supported FluffBuzz token path, but FluffBuzz now prefers Claude CLI reuse and `claude -p` when available.