> For the complete documentation index, see [llms.txt](https://docs.avis.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avis.xyz/integrations/coding/gemini-cli.md).

# Gemini CLI

## Gemini CLI Integration Guide

This document explains how to integrate [Gemini CLI](https://github.com/google-gemini/gemini-cli) — Google's official terminal coding agent — with the AVIS Gemini-compatible API.

### What is Gemini CLI

Gemini CLI is an open-source coding agent that runs in your terminal, reads/edits files, and executes shell commands. It speaks Google's native Gemini API, so it works against AVIS through the Gemini-compatible surface via an official override — `GOOGLE_GEMINI_BASE_URL` — with no code changes.

### 1) Install Gemini CLI

```bash
npm install -g @google/gemini-cli
```

Verify:

```bash
gemini --version
```

### 2) Get an AVIS API key

See Authentication — sign in at [avis.xyz](https://avis.xyz), go to **Settings → API Keys**, and create one.

### 3) Point Gemini CLI at AVIS

Gemini CLI only honors a custom base URL when authenticating via **Gemini API key** mode — not Google Sign-In, not Vertex AI. Set both:

```bash
export GEMINI_API_KEY="<your-avis-api-key>"
export GOOGLE_GEMINI_BASE_URL="https://api.avis.xyz/api/gemini"
```

Add these to `~/.zshrc` / `~/.bashrc` to persist across terminals.

Notes:

* `GOOGLE_GEMINI_BASE_URL` must be a valid HTTPS URL.
* There is no `baseUrl` field in `settings.json` for this — despite what some third-party integration guides claim, the only supported mechanism is the `GOOGLE_GEMINI_BASE_URL` environment variable, and only in combination with `GEMINI_API_KEY` auth.

### 4) Run Gemini CLI

```bash
cd your-project
gemini
```

On first run, select **Use Gemini API key** when prompted for an auth method (not "Sign in with Google"). If Gemini CLI was previously authenticated via Google Sign-In or Vertex AI on this machine, switch auth methods explicitly — those modes ignore `GOOGLE_GEMINI_BASE_URL` entirely and will keep calling Google's real API regardless of the env var.

One-shot / non-interactive:

```bash
gemini "Reply with exactly one word: pong"
```

### 5) Pick a model

Query the live catalog for exact current IDs — this surface uses AVIS's flat canonical id (no `gemini/` prefix):

```bash
curl https://api.avis.xyz/api/gemini/v1beta/models \
  -H "x-api-key: $GEMINI_API_KEY"
```

Select a model with the `-m`/`--model` flag:

```bash
gemini -m gemini-2.5-pro "Reply with exactly one word: pong"
```

### 6) Troubleshooting

* Requests still hit Google's real API instead of AVIS
  * The active auth method isn't `gemini-api-key` — `GOOGLE_GEMINI_BASE_URL` is silently ignored under Google Sign-In or Vertex AI. Re-run `gemini` and explicitly pick **Use Gemini API key**.
* `401 Unauthorized`
  * `GEMINI_API_KEY` is invalid, revoked, or unset in the shell Gemini CLI was launched from.
  * Verify directly: `curl -H "x-api-key: $GEMINI_API_KEY" https://api.avis.xyz/api/gemini/v1beta/models`.
* `403` with a valid key
  * Account balance is depleted — see Errors.
* `404` / model not found
  * The model passed to `-m`/`--model` doesn't match AVIS's catalog — re-check against `GET /api/gemini/v1beta/models` (§5).

### 7) Minimal End-to-End Checklist

1. AVIS API key created (§2).
2. `GEMINI_API_KEY` and `GOOGLE_GEMINI_BASE_URL` exported (§3).
3. Auth method explicitly set to **Use Gemini API key** (§4) — not Google Sign-In or Vertex AI.
4. Model ID confirmed against `GET /api/gemini/v1beta/models` (§5).
5. `gemini "..."` returns model output from the AVIS-backed model.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.avis.xyz/integrations/coding/gemini-cli.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.