# Gemini CLI

> Use the Gemini CLI with MirAPI over the Gemini protocol: set GOOGLE_GEMINI_BASE_URL to the MirAPI base URL and GEMINI_API_KEY to your MirAPI key.

Gemini CLI is Google's terminal assistant, and it speaks the Gemini API natively. MirAPI implements the Gemini protocol at `POST /v1beta/models/{model}:generateContent`, so you can point Gemini CLI at MirAPI with two environment variables — no proxy or plugin required.

## What you need

| Element | Value |
|---|---|
| Base URL | `https://api.mirapi.ai` — the CLI appends `/v1beta` itself |
| API key | Your MirAPI key (`sk-...`), passed through `GEMINI_API_KEY` |
| Model | `deepseek-chat`, set with the `/model` command |

## Configure

1. Create a key in https://console.mirapi.ai → **API Keys** and export it:

```bash
export MIRAPI_API_KEY=sk-...
```

2. Export the connection variables. Add them to your shell profile (`~/.zshrc`, `~/.bashrc`, or `~/.config/fish/config.fish`) so they persist:

```bash
export GEMINI_API_KEY="$MIRAPI_API_KEY"
export GOOGLE_GEMINI_BASE_URL="https://api.mirapi.ai"
```

3. Reload your shell and start Gemini CLI:

```bash
source ~/.zshrc   # or ~/.bashrc, or open a new terminal
gemini
```

## Verify with a message

Run a one-shot prompt:

```bash
gemini -p "Reply with exactly: connected to MirAPI"
```

The reply should contain `connected to MirAPI`. Before you start, confirm the key and catalogue are reachable:

```bash
curl https://api.mirapi.ai/v1beta/models -H "x-goog-api-key: $GEMINI_API_KEY"
```

On Gemini paths, the gateway accepts the key via the `x-goog-api-key` header or the `?key=` query parameter.

## Environment variables

Gemini CLI reads three relevant variables:

| Variable | Purpose | Value for MirAPI |
|---|---|---|
| `GEMINI_API_KEY` | The key sent as `x-goog-api-key` | Your MirAPI key (`sk-...`) |
| `GOOGLE_API_KEY` | Google Cloud API key (Vertex AI) | Leave unset — MirAPI uses `GEMINI_API_KEY` |
| `GOOGLE_GEMINI_BASE_URL` | Overrides the API base URL | `https://api.mirapi.ai` — the CLI appends `/v1beta` |

Set exactly one key variable to avoid stale credentials. If a real Google key is still exported elsewhere, Gemini CLI may pick it up instead.

## Protocol and capabilities

Gemini CLI speaks only the Gemini API — you cannot switch it to the OpenAI chat completions or Anthropic messages surface. MirAPI serves the Gemini route at `POST /v1beta/models/{model}:generateContent`. Set `GOOGLE_GEMINI_BASE_URL` to the bare `https://api.mirapi.ai` — the CLI appends `/v1beta/models/{model}:generateContent` itself.

Which capabilities work depends on the model you choose — check `supported_parameters` and `output_modalities` in `GET /v1/models` before relying on tool calling, structured output, web search, reasoning, or image input. Responses stream as SSE, and reasoning content arrives before the final answer.

## Switching models

Gemini CLI starts on a Google model by default. Switch it with the `/model` slash command:

```text
/model deepseek-chat
```

Use any model name from `GET /v1/models`, verbatim. The model must be on your key's whitelist; otherwise the request fails with **403**.

## Errors and troubleshooting

| Status | Meaning | What to do |
|---|---|---|
| 401 | Key missing, invalid, or unknown | Fix the exported `GEMINI_API_KEY` |
| 403 | Key valid but rejected — balance, whitelist, quota, or IP | Resolve the cause, then retry |
| 413 | Payload too large | Reduce the request size |
| 429 | Rate limited | Jittered exponential backoff (1s→2s→4s, cap ~30s); no `Retry-After` header |
| 500 | Gateway or upstream error | Idempotent requests can be retried safely |

The gateway does not retry on your behalf. Every error message ends with the MirAPI request ID — include it when you open a support ticket.

## Billing

- Conversations are billed per token (input / output / cache read, per 1M tokens USD). Reasoning and thinking tokens count as **output**.
- Gemini CLI draws from a prepaid balance: no subscription, no minimum, and the balance never expires.
- When the balance runs out, requests fail with **403**; topping up restores the same key immediately.
- Reconcile usage in the console billing log, `GET /api/usage/token` (account-level totals), or `GET /api/log/token` (per-request detail).

## Troubleshooting

- **Keep the base URL bare.** Gemini CLI appends `/v1beta/models/{model}:generateContent` itself, so adding `/v1beta` to the base URL produces a doubled `/v1beta` path.
- **Model names are verbatim.** The model must appear in `GET /v1/models`; `vendor/` prefixes are console-only and not part of a request.
- **403 with a valid key** usually means the model is not whitelisted for the key or the balance is exhausted — top up or adjust the key, then retry.
- **Multimodal input** works only when the selected model supports image input; screenshots and files Gemini CLI sends as images need a vision-capable model.

## Related links

- [Quickstart](/docs/quickstart)
- [Models & pricing](/docs/models)
- [Billing & top-ups](/docs/billing)
- [Vision](/docs/guides/vision)
- [Authentication](/docs/api-reference/authentication)
- [Errors](/docs/api-reference/errors)