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

# Model Flags

> Select model tiers or specific model IDs

Model flags let you choose which AI model to use. You can select by tier (Fable, Opus, Sonnet, Haiku) or specify an exact model ID.

## Cross-Runtime Model Mapping

The same tier flag selects each runtime's equivalent model:

| Tier  | Flag                 | Claude Code      | Codex CLI                     |
| ----- | -------------------- | ---------------- | ----------------------------- |
| Fable | `--fable` / `--best` | claude-fable-5   | gpt-5.4 (fallback — no Fable) |
| High  | `--opus` / `--high`  | claude-opus-5    | gpt-5.4                       |
| Mid   | `--sonnet` / `--mid` | claude-sonnet-5  | gpt-5.3-codex                 |
| Low   | `--haiku` / `--low`  | claude-haiku-4-5 | gpt-5.4-mini                  |

<Tip>
  `--opus` (the default) gives you the highest Opus-tier model for whichever runtime is active. `--fable`/`--best` selects Claude Fable 5, Anthropic's most capable model — it's available on Anthropic providers only, and on other runtimes (Ollama, LM Studio, Codex) it falls back to that runtime's highest tier with a one-line notice.
</Tip>

## Tier Flags

### Fable Tier (Fable 5)

<ParamField path="--fable" type="flag">
  **Most capable model** - Claude Fable 5, Anthropic's most powerful model (a tier above Opus). Anthropic providers only; not the default.

  ```bash theme={null}
  ai --fable task.md
  ai --aws --fable
  ai --apikey --best          # --best is a synonym for --fable
  ```

  **Equivalent:** `--best`

  **Default model:** `claude-fable-5` ($10/$50 per MTok, 1M context)

  **Availability:** Anthropic API, AWS Bedrock, Vertex AI, Azure, Vercel, and Claude Pro (subject to your subscription). On Ollama, LM Studio, and Codex it falls back to that runtime's highest tier and prints a notice.

  **Data retention:** Fable 5 is a Mythos-class *Covered Model*. Anthropic retains inputs/outputs for **30 days with human review on every platform that offers it** — direct API, Pro, Bedrock, Vertex, and Azure alike. This is a property of the model, so switching providers doesn't avoid it; the only way to avoid it is to not use Fable (use `--opus`).

  **Cloud enablement:** Because of that retention, **Bedrock** (`--aws`) and **Vertex** (`--vertex`) need a one-time, account/project-level data-sharing enablement before they'll serve Fable, or requests fail (`400`/`403`). `--apikey` and `--azure` need no step — their standard config already shares with Anthropic (same retention, just no manual enablement). See the [AWS Bedrock](../providers/cloud#aws-bedrock) and [Vertex AI](../providers/cloud#google-vertex-ai) provider docs for exact steps.

  <Note>Exception: **zero-data-retention (ZDR) organizations** must explicitly turn retention on for Fable on *every* platform — including the direct API (Console → Workspace → Privacy Controls) and Azure — since ZDR and Covered Models are mutually exclusive.</Note>

  **Use for:**

  * The most demanding reasoning and long-horizon agentic work
  * Tasks where Opus isn't quite enough
</ParamField>

<ParamField path="--best" type="flag">
  Alias for `--fable`

  ```bash theme={null}
  ai --best task.md
  ```
</ParamField>

### High Tier (Opus)

<ParamField path="--opus" type="flag">
  **Highest-tier model** - Most capable, best for complex reasoning

  ```bash theme={null}
  ai --opus task.md
  ai --aws --opus
  ai --ollama --opus      # Not applicable to Ollama
  ```

  **Equivalent:** `--high`

  **Default model:** `claude-opus-5`

  **Use for:**

  * Complex architectural decisions
  * Difficult refactoring
  * Security analysis
  * High-stakes code generation
</ParamField>

<ParamField path="--high" type="flag">
  Alias for `--opus`

  ```bash theme={null}
  ai --high task.md
  ```
</ParamField>

### Mid Tier (Sonnet)

<ParamField path="--sonnet" type="flag">
  **Mid-tier model** - Balanced capability and speed

  ```bash theme={null}
  ai --sonnet task.md
  ai --aws --sonnet
  ```

  **Equivalent:** `--mid`

  **Default model:** `claude-sonnet-5`

  **Use for:**

  * Most coding tasks
  * General development
  * Documentation
  * Code review
</ParamField>

<ParamField path="--mid" type="flag">
  Alias for `--sonnet`

  ```bash theme={null}
  ai --mid task.md
  ```
</ParamField>

### Low Tier (Haiku)

<ParamField path="--haiku" type="flag">
  **Lowest-tier model** - Fastest and most cost-effective

  ```bash theme={null}
  ai --haiku task.md
  ai --aws --haiku
  ai --ollama --haiku     # Not applicable to Ollama
  ```

  **Equivalent:** `--low`

  **Default model:** `claude-haiku-4-5`

  **Use for:**

  * Quick tests
  * Simple tasks
  * Cost-sensitive workloads
  * High-volume automation
</ParamField>

<ParamField path="--low" type="flag">
  Alias for `--haiku`

  ```bash theme={null}
  ai --low task.md
  ```
</ParamField>

## Custom Model Selection

<ParamField path="--model" type="flag">
  **Specify exact model ID** - Use any model supported by your provider

  ```bash theme={null}
  ai --model claude-opus-5
  ai --aws --model global.anthropic.claude-opus-5
  ai --ollama --model qwen3-coder
  ai --vercel --model openai/gpt-5.2-codex
  ai --codex --model gpt-5.4
  ```

  **Format depends on provider:**

  * **AWS Bedrock:** `global.anthropic.claude-opus-5`
  * **Vertex AI:** `claude-opus-5`
  * **Anthropic API:** `claude-opus-5`
  * **Ollama:** Model name from `ollama list`
  * **Vercel:** `provider/model-name` (e.g., `openai/gpt-4`)

  **Precedence:** `--model` overrides tier flags (`--opus`, `--sonnet`, `--haiku`)
</ParamField>

## Model Defaults Per Provider

### Claude Subscription (Pro/Max)

```bash theme={null}
ai --pro                 # Uses your subscription's latest model
```

Claude Pro/Max doesn't support tier selection - it always uses the latest available model from your subscription.

### API Providers (AWS, Vertex, Anthropic, Azure)

| Tier                         | Default Model      |
| ---------------------------- | ------------------ |
| Fable (`--fable`, `--best`)  | `claude-fable-5`   |
| Opus (`--opus`, `--high`)    | `claude-opus-5`    |
| Sonnet (`--sonnet`, `--mid`) | `claude-sonnet-5`  |
| Haiku (`--haiku`, `--low`)   | `claude-haiku-4-5` |

**Default tier:** High (Opus) — Fable is opt-in via `--fable`/`--best`.

```bash theme={null}
ai --aws                 # Uses Opus
ai --aws --sonnet        # Uses Sonnet
ai --aws --haiku         # Uses Haiku
```

### Local Providers (Ollama, LM Studio)

```bash theme={null}
ai --ollama --model qwen3-coder          # Specify model name
ai --lmstudio --model mlx-qwen-32b       # Specify model name
```

Local providers don't have default models - you must specify with `--model` or configure a default in `~/.ai-runner/secrets.sh`.

### Codex CLI

| Tier                      | Default Model   |
| ------------------------- | --------------- |
| High (`--opus`, `--high`) | `gpt-5.4`       |
| Mid (`--sonnet`, `--mid`) | `gpt-5.3-codex` |
| Low (`--haiku`, `--low`)  | `gpt-5.4-mini`  |

**Default:** gpt-5.4 (Codex native default). Tier flags override: `--mid` selects gpt-5.3-codex. `--fable`/`--best` has no Codex equivalent, so it falls back to the High tier (`gpt-5.4`) with a notice.

```bash theme={null}
ai --codex                   # Uses gpt-5.4 (native default)
ai --codex --mid             # Uses gpt-5.3-codex
ai --codex --haiku           # Uses gpt-5.4-mini
```

Override in `~/.ai-runner/secrets.sh`:

```bash theme={null}
export CODEX_MODEL_HIGH="gpt-5.4"
export CODEX_MODEL_MID="gpt-5.3-codex"
export CODEX_MODEL_LOW="gpt-5.4-mini"
```

### Vercel AI Gateway

```bash theme={null}
ai --vercel --model openai/gpt-5.2-codex        # OpenAI
ai --vercel --model anthropic/claude-opus-5   # Anthropic
ai --vercel --model google/gemini-exp-2506      # Google
```

Vercel supports 100+ models. Use `provider/model-name` format. See [Vercel AI Gateway docs](https://vercel.com/ai-gateway) for available models.

## Configuration

### View Default Models

```bash theme={null}
ai-status    # Shows default model IDs for each tier
```

### Override Model Defaults

Edit `~/.ai-runner/secrets.sh`:

```bash theme={null}
# Override AWS Sonnet model
export CLAUDE_MODEL_SONNET_AWS="global.anthropic.claude-sonnet-5"

# Override small/fast model (for background operations)
export CLAUDE_SMALL_FAST_MODEL_AWS="us.anthropic.claude-haiku-4-5-20251001-v1:0"

# Override Vertex Opus model
export CLAUDE_MODEL_OPUS_VERTEX="claude-opus-5"

# Override Fable 5 (top tier, --fable/--best) per provider
export CLAUDE_MODEL_FABLE_ANTHROPIC="claude-fable-5"
export CLAUDE_MODEL_FABLE_AWS="global.anthropic.claude-fable-5"
export CLAUDE_MODEL_FABLE_VERTEX="claude-fable-5"
export CLAUDE_MODEL_FABLE_AZURE="claude-fable-5"
export CLAUDE_MODEL_FABLE_VERCEL="anthropic/claude-fable-5"
```

See `~/.ai-runner/models.sh` for all available override variables.

## Dual Model Configuration

Claude Code uses two models:

1. **Primary model** (`ANTHROPIC_MODEL`) - Interactive work, selected by tier flags
2. **Small/fast model** (`ANTHROPIC_SMALL_FAST_MODEL`) - Background operations (defaults to Haiku)

When you run:

```bash theme={null}
ai --aws --opus
```

* **Primary:** Opus (`claude-opus-5`)
* **Background:** Haiku (`claude-haiku-4-5`)

Both models show in `ai-status` output.

## Examples

### Tier Selection

```bash theme={null}
# Most capable (Opus)
ai --aws --opus complex-refactor.md

# Balanced (Sonnet, default)
ai --aws task.md
ai --aws --sonnet task.md     # Explicit

# Fastest/cheapest (Haiku)
ai --aws --haiku quick-test.md
```

### Custom Models

```bash theme={null}
# Specific AWS Bedrock model
ai --aws --model us.anthropic.claude-opus-5

# Ollama local model
ai --ollama --model qwen3-coder

# Ollama cloud model (no GPU needed)
ai --ollama --model minimax-m2.5:cloud

# Vercel with OpenAI
ai --vercel --model openai/gpt-5.2-codex

# Vercel with xAI Grok
ai --vercel --model xai/grok-2
```

### Shebang Scripts

```markdown theme={null}
#!/usr/bin/env -S ai --aws --opus
Complex task requiring the most capable model.
```

```markdown theme={null}
#!/usr/bin/env -S ai --ollama --model qwen3-coder
Local execution with specific model.
```

### Resume with Different Model

```bash theme={null}
# Start with Sonnet
ai --aws --sonnet

# Resume with Opus for complex reasoning
ai --aws --opus --resume

# Resume with Haiku for speed
ai --aws --haiku --resume
```

### Cost Optimization

```bash theme={null}
# Use Haiku for bulk operations
for file in *.md; do
  ai --aws --haiku --skip "$file" >> results.txt
done

# Use Opus only for critical review
ai --aws --opus --skip final-review.md
```

## Model Recommendations

| Task Type            | Recommended Tier | Reason                   |
| -------------------- | ---------------- | ------------------------ |
| Complex refactoring  | Opus             | Needs deep understanding |
| Architectural design | Opus             | High-stakes decisions    |
| Security analysis    | Opus             | Accuracy critical        |
| General coding       | Sonnet           | Balanced performance     |
| Documentation        | Sonnet           | Good quality/speed ratio |
| Code review          | Sonnet           | Sufficient capability    |
| Quick tests          | Haiku            | Speed matters            |
| Bulk automation      | Haiku            | Cost-effective           |
| Simple tasks         | Haiku            | Overhead not needed      |

## Troubleshooting

<AccordionGroup>
  <Accordion title="Model not found error">
    Model IDs are provider-specific. Check your provider's available models:

    ```bash theme={null}
    # AWS Bedrock
    aws bedrock list-foundation-models --region us-west-2

    # Ollama
    ollama list

    # Vertex AI
    gcloud ai models list --region=us-central1
    ```

    See provider documentation for correct model ID format.
  </Accordion>

  <Accordion title="Wrong model being used">
    Check for overrides in `~/.ai-runner/secrets.sh`:

    ```bash theme={null}
    grep CLAUDE_MODEL ~/.ai-runner/secrets.sh
    ```

    Verify active model in session:

    ```bash theme={null}
    ai-status
    ```
  </Accordion>

  <Accordion title="Tier flags don't work with Ollama">
    Tier flags work differently with local and Codex providers. For Ollama/LM Studio, you may need `--model` to specify a local model name. For Codex, tiers map to GPT models automatically.

    ```bash theme={null}
    ai --ollama --model qwen3-coder
    ```
  </Accordion>
</AccordionGroup>

## Related Pages

<CardGroup cols={2}>
  <Card title="Provider Flags" icon="cloud" href="./provider-flags">
    Switch between cloud providers
  </Card>

  <Card title="Provider Model Lists" icon="list" href="/providers">
    Available models per provider
  </Card>
</CardGroup>