---
title: "CLI providers"
kicker: "models"
summary: "CLI model providers and config for Claude, Codex, Gemini, Cursor Agent, OpenClaw, OpenCode, GitHub Copilot, Antigravity, and pi."
read_when:
  - "When changing CLI model integration."
---

# CLI models

Summarize can use installed CLIs (Claude, Codex, Gemini, Cursor Agent, OpenClaw, OpenCode, GitHub Copilot, Antigravity, pi) as local model backends.

## Model ids

- `cli/claude/<model>` (e.g. `cli/claude/sonnet`)
- `cli/codex/<model>` (e.g. `cli/codex/gpt-5.5`)
- `cli/gemini/<model>` (e.g. `cli/gemini/flash`)
- `cli/agent/<model>` (e.g. `cli/agent/auto`)
- `cli/openclaw/<model>` (e.g. `cli/openclaw/main`)
- `openclaw/<model>` (alias for the same OpenClaw CLI path)
- `cli/opencode/<model>` (e.g. `cli/opencode/openai/gpt-5.4`)
- `cli/opencode` (use the OpenCode runtime default model)
- `cli/copilot/<model>` (e.g. `cli/copilot/gpt-5.2`)
- `cli/copilot` (use the Copilot CLI runtime default model)
- `cli/agy` (use the Antigravity CLI active session model)
- `cli/pi/<model>` (e.g. `cli/pi/sonnet`)
- `cli/pi` (use pi's configured default model)

Use `--cli [provider]` (case-insensitive) for the provider default, or `--model cli/<provider>/<model>` to pin a model.
Bare `cli/codex` defaults to GPT-5.5; set `cli.codex.model` to override it.
Antigravity does not support per-call model selection in print mode, so use `cli/agy` without a model suffix. pi supports `cli/pi/<model>` or a configured `cli.pi.model`.
If `--cli` is provided without a provider, auto selection is used with CLI enabled.

Codex GPT Fast:

- `--model codex-fast` maps to `cli/codex/gpt-fast`.
- OpenAI fast mode is not a CLI model. Use `--model openai/gpt-5.5 --fast --thinking medium`; see `docs/openai.md`.

## Auto mode

Auto mode can prepend CLI attempts in two ways:

- `cli.enabled` set in config:
  - Auto always uses this list order.
  - Also acts as an allowlist for explicit `--cli` / `--model cli/...`.
- Auto CLI fallback (`cli.autoFallback`, default enabled):
  - Applies only to **implicit** auto (when no model is set via flag/env/config).
  - Default behavior: only when no API key is configured.
  - Default order: `claude, gemini, codex, agent, openclaw, opencode, copilot`.
  - Antigravity and pi are opt-in unless added to `cli.autoFallback.order`.
  - Remembers + prioritizes the last successful CLI provider (`~/.summarize/cli-state.json`).

Gemini CLI performance: summarize sets `GEMINI_CLI_NO_RELAUNCH=true` for Gemini CLI runs to avoid a costly self-relaunch (can be overridden by setting it yourself).

Set explicit CLI allowlist:

```json
{
  "cli": { "enabled": ["gemini"] }
}
```

Configure auto CLI fallback:

```json
{
  "cli": {
    "autoFallback": {
      "enabled": true,
      "onlyWhenNoApiKeys": true,
      "order": ["claude", "gemini", "codex", "agent", "openclaw", "opencode", "copilot"]
    }
  }
}
```

Disable auto CLI fallback:

```json
{
  "cli": { "autoFallback": { "enabled": false } }
}
```

Note: `--model auto` (explicit) does not trigger auto CLI fallback unless `cli.enabled` is set.

## CLI discovery

Binary lookup:

- `CLAUDE_PATH`, `CODEX_PATH`, `GEMINI_PATH` (optional overrides)
- `AGENT_PATH` (optional override)
- `OPENCLAW_PATH` (optional override)
- `OPENCODE_PATH` (optional override)
- `COPILOT_PATH` (optional override)
- Otherwise uses `PATH`

Run `summarize status` to list enabled CLI providers whose executable is currently available.
`summarize status --verbose` also prints the resolved executable path and configured CLI model.
Missing or disabled providers are omitted.

## Attachments (images/files)

When a CLI attempt is used for an image or non-text file, Summarize switches to a
path-based prompt and enables the required tool flags:

- Claude: `--tools Read --dangerously-skip-permissions`
- Gemini: `--yolo` and `--include-directories <dir>`
- Codex: `codex exec --output-last-message ...` and `-i <image>` for images
- Agent: uses built-in file tools in `agent --print` mode (no extra flags)
- OpenCode: `opencode run --format json ... --file <path>` when a file/image path is required
- Copilot: `copilot -p <prompt>`; passes `--model <model>` when one is configured
- Antigravity: `agy --print`; does not auto-approve tools for attachment prompts
- pi: `pi --print --mode json`; passes `--system-prompt`, sends prompt over stdin, and uses `--no-tools` for isolated summaries

## Config

```json
{
  "cli": {
    "enabled": [
      "claude",
      "gemini",
      "codex",
      "agent",
      "openclaw",
      "opencode",
      "copilot",
      "agy",
      "pi"
    ],
    "autoFallback": {
      "enabled": true,
      "onlyWhenNoApiKeys": true,
      "order": ["claude", "gemini", "codex", "agent", "openclaw", "opencode", "copilot"]
    },
    "codex": { "model": "gpt-5.5" },
    "gemini": { "model": "flash", "extraArgs": ["--verbose"] },
    "claude": {
      "model": "sonnet",
      "binary": "/usr/local/bin/claude",
      "extraArgs": ["--verbose"]
    },
    "agent": {
      "model": "auto",
      "binary": "/usr/local/bin/agent"
    },
    "openclaw": {
      "model": "main",
      "binary": "/usr/local/bin/openclaw"
    },
    "opencode": {
      "binary": "/usr/local/bin/opencode"
    },
    "copilot": {
      "binary": "/usr/local/bin/copilot"
    },
    "agy": {
      "binary": "/usr/local/bin/agy"
    },
    "pi": {
      "binary": "/usr/local/bin/pi"
    }
  }
}
```

Notes:

- CLI output is treated as text only (no token accounting).
- If a CLI call fails, auto mode falls back to the next candidate.
- Cursor Agent CLI uses the `agent` binary and relies on Cursor CLI auth (login or `CURSOR_API_KEY`).
- Antigravity CLI uses the active agy session model; `cli.agy.model` is ignored by runtime selection.
- Antigravity normal text summaries run `agy --print` with no prompt argument in a temporary cwd with `--sandbox`, streaming the prompt over stdin so extracted content is not exposed in argv. Attachment prompts keep the caller cwd so agy can inspect the requested path but do not auto-approve tools.
- pi runs in JSON mode (`--print --mode json`) with `--no-tools`, `--no-context-files`, `--no-extensions`, `--no-skills`, `--no-session` for isolated summarization. It receives the summarize system prompt via `--system-prompt`, the summarize prompt over stdin, and reports usage/cost via JSONL events. Use `PI_PATH` to override the binary path.
- Codex CLI normal text summaries run isolated by default: `codex exec --ephemeral --ignore-user-config --ignore-rules -C <temp-dir> ...` with a sanitized temporary `CODEX_HOME` that carries auth only. Set `cli.codex.isolated` to `false` only when you intentionally need Codex to inherit local config/rules.
- Gemini CLI is invoked in headless mode with `--prompt` for compatibility with current Gemini CLI releases.
- OpenClaw uses `openclaw agent --agent <model> --message <prompt> --json` because current OpenClaw requires `-m/--message`; very large extracted inputs are rejected before launch to avoid argv limits.
- OpenCode uses `opencode run --format json`, streams prompt text over stdin, and uses the runtime default model when none is configured.
- Copilot uses `copilot -p`, treats stdout as plain text, and uses the runtime default model when none is configured.

## Quick smoke test (all CLI providers)

Use a tiny local text file and run each provider with a longer timeout (Gemini can be slower):

```bash
printf "Summarize CLI smoke input.\nOne short paragraph. Reply can be brief.\n" >/tmp/summarize-cli-smoke.txt

summarize --cli codex --plain --timeout 2m /tmp/summarize-cli-smoke.txt
summarize --cli claude --plain --timeout 2m /tmp/summarize-cli-smoke.txt
summarize --cli gemini --plain --timeout 2m /tmp/summarize-cli-smoke.txt
summarize --cli agent --plain --timeout 2m /tmp/summarize-cli-smoke.txt
summarize --cli openclaw --plain --timeout 2m /tmp/summarize-cli-smoke.txt
summarize --cli opencode --plain --timeout 2m /tmp/summarize-cli-smoke.txt
summarize --cli copilot --plain --timeout 2m /tmp/summarize-cli-smoke.txt
summarize --cli pi --plain --timeout 2m /tmp/summarize-cli-smoke.txt
```

If Agent fails with auth, run `agent login` (interactive) or set `CURSOR_API_KEY`.

## Generate free preset (OpenRouter)

`summarize` ships with a built-in preset `free`, backed by OpenRouter `:free` models.
To regenerate the candidate list (and persist it in your config):

```bash
summarize refresh-free
```

Options:

- `--runs 2` (default): extra timing runs per selected model (total runs = 1 + runs)
- `--smart 3` (default): number of “smart-first” picks (rest filled by fastest)
- `--set-default`: also sets `"model": "free"` in `~/.summarize/config.json`
