# Google Antigravity CLI Setup

> **Last verified**: 2026-09-18 · 📄 Per official docs (Antigravity CLI 1.2.x (auto-updater manifest 1.2.6, checked 2026-09))

## At a glance

| Item | Details |
|---|---|
| Models you can use | Through QCode: Gemini ✅ (native protocol, `GOOGLE_GEMINI_BASE_URL`) · Claude / GPT / Chinese models ❌. That is a limit of the **endpoint**, not of the tool: when agy signs in with a Google account, the official model page lists other families too — but those run on Google's quota, not through us |
| Protocol & Base URL | Gemini: `https://api.qcode.cc/gemini` (mainland China: `asia.qcode.cc`) |
| Where to configure | `~/.gemini/antigravity-cli/settings.json` plus env `GEMINI_API_KEY` / `GOOGLE_GEMINI_BASE_URL` |
| Official docs | [antigravity.google](https://antigravity.google) |

> **⚠️ Migrating from Gemini CLI?** The official post of 2026-05-19 says, verbatim, that from
> **2026-06-18** Gemini CLI and the Gemini Code Assist IDE extensions "will stop serving requests" —
> for **Google AI Pro and Ultra**, and for people using it free of charge on a personal account.
> **Enterprise paid keys are unaffected**: the same post states that Gemini CLI remains accessible via
> paid Gemini and Gemini Enterprise Agent Platform API keys. What launched that day was
> **Antigravity CLI and Antigravity 2.0**; the Antigravity IDE itself shipped earlier, on
> **2025-11-18**. If you followed [Gemini CLI Integration](/docs/ide/gemini) before, switch to this page.

[Google Antigravity](https://antigravity.google/) is Google's successor to Gemini CLI for consumer
sign-ins. It ships
as three pieces: a desktop IDE, the **Antigravity CLI (`agy`, written in Go)**, and an SDK.
This page covers the CLI only: pointing it at **QCode.cc** as its model upstream.

## 🔴 Read this first: Gemini protocol only

Antigravity CLI's custom endpoint is **Gemini-compatible**, set through the
`GOOGLE_GEMINI_BASE_URL` environment variable. The official troubleshooting table says, verbatim, that
`gemini` is "the only accepted value" for `modelProvider` — so this route **cannot take an
OpenAI-compatible endpoint**, and through QCode it can only serve Gemini-family models.

| Item | Value |
|---|---|
| Config file | `~/.gemini/antigravity-cli/settings.json` |
| Key field | `"modelProvider": "gemini"` |
| Credential | `GEMINI_API_KEY` env var (your QCode `cr_` key) |
| Endpoint override | `GOOGLE_GEMINI_BASE_URL` env var |
| Variables it ignores | Stated by the official docs: agy **does not load `.env` files**, and `GOOGLE_API_KEY` has no effect — the credential is read only from `GEMINI_API_KEY` in the environment. Gemini CLI does load `.env`, so the two behave oppositely; CI users hit this once and never forget |
| Usable models | Through QCode: Gemini family only |

> For Claude or GPT, use a different client — [Claude Code](/docs/getting-started/installation),
> [Codex CLI](/docs/ide/codex), [Cline](/docs/ide/cline), [Zed](/docs/ide/zed).
> Which protocol serves which models is documented in
> [Endpoints & API Paths](/docs/getting-started/endpoints-and-api-paths).

## 🔴 The Antigravity IDE (2.0 desktop app) cannot be connected

The Antigravity **desktop IDE currently has no official BYOK or custom-provider hook**, so its
built-in agent model cannot be swapped for a third-party endpoint. Community projects work around
this with a local intercepting proxy, but that is a reverse-engineered path with no official
support, and this page does not recommend it.

**The piece that connects to QCode is the CLI (`agy`), not the IDE.**

## Prerequisites

- A QCode.cc API key (starts with `cr_`), from the [console](https://qcode.cc/dashboard)
- Familiarity with [Endpoints & API Paths](/docs/getting-started/endpoints-and-api-paths)

## Step 1: Install Antigravity CLI

Defer to the [official install docs](https://antigravity.google/docs/cli/install):

<div data-os="macos" markdown="1">

```bash
curl -fsSL https://antigravity.google/cli/install.sh | bash
# installs to ~/.local/bin/agy
```

</div>

<div data-os="linux" markdown="1">

```bash
curl -fsSL https://antigravity.google/cli/install.sh | bash
# installs to ~/.local/bin/agy
```

</div>

<div data-os="windows" markdown="1">

PowerShell:

```powershell
irm https://antigravity.google/cli/install.ps1 | iex
# installs to C:\Users\<username>\AppData\Local\agy\bin
```

CMD:

```bat
curl -fsSL https://antigravity.google/cli/install.cmd -o install.cmd && install.cmd && del install.cmd
```

</div>

The official install page mentions `--skip-aliases` and `--skip-path`, but that is the **Windows** behaviour: `install.ps1` / `install.cmd` forward arguments to `agy install`, while `install.sh` on macOS / Linux only accepts `-d, --dir <path>` and `-h, --help` and exits on anything else. Do not copy those two flags on macOS / Linux.

## Step 2: Switch to API-key auth (skip the Google sign-in)

By default `agy` reads your OS keyring or opens a browser for Google account sign-in. To use an
API key instead, edit (or create) `~/.gemini/antigravity-cli/settings.json`:

```json
{
  "modelProvider": "gemini"
}
```

With this set, `agy` **skips the sign-in screen** and opens the main interface directly, reading
the `GEMINI_API_KEY` environment variable instead.

> 🔴 If `"modelProvider": "gemini"` is set but `GEMINI_API_KEY` is missing, **the CLI will not
> start**. Both are required together.

## Step 3: Point the key and endpoint at QCode

```bash
export GEMINI_API_KEY="cr_your_qcode_key"
export GOOGLE_GEMINI_BASE_URL="https://api.qcode.cc/gemini"
```

Add them to `~/.zshrc` / `~/.bashrc` to persist. On Windows PowerShell:

```powershell
$env:GEMINI_API_KEY = "cr_your_qcode_key"
$env:GOOGLE_GEMINI_BASE_URL = "https://api.qcode.cc/gemini"
```

**Stop `GOOGLE_GEMINI_BASE_URL` at `/gemini`** and leave `/v1beta` out: the official example is a bare
address (`export GOOGLE_GEMINI_BASE_URL="https://your-endpoint.example.com"`), and the client adds the
version segment and request path itself. agy is a closed-source Go client — Google documents neither the
joining rule nor whether a trailing `/` is normalised (the SDK behind Gemini CLI does strip one), so we
follow the documented shape instead of guessing at edge cases. This is the opposite of OpenCode's
`google` provider (which does need `/v1beta`); the difference is explained in
[Endpoints & API Paths](/docs/getting-started/endpoints-and-api-paths).

**From mainland China**, swap the host for `https://asia.qcode.cc/gemini` (Asia node, nearest of HK/JP); the
key is unchanged. `us` / `eu` work the same way.

> When authenticating with `GEMINI_API_KEY`, `/logout` does nothing — there is no stored session
> to clear.

## Step 4: Verify connectivity

Test QCode's Gemini endpoint directly, bypassing the tool:

```bash
# List the Gemini models you can currently call
curl -s https://api.qcode.cc/gemini/v1beta/models \
  -H "x-goog-api-key: $GEMINI_API_KEY"

# Send a minimal request (use a model id from the list above)
curl -s "https://api.qcode.cc/gemini/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "content-type: application/json" \
  -d '{"contents":[{"parts":[{"text":"ping"}]}],"generationConfig":{"maxOutputTokens":16}}'
```

- JSON containing `candidates` → endpoint and key are both fine
- **401** → the path is right; the key is missing or wrong

**Treat the live query as authoritative** for which models exist — do not copy a fixed list from any
document, including this one. The ids returned by that first `curl` are what this QCode leg can serve;
the full catalogue and prices are on [qcode.cc/models](https://qcode.cc/models).

One caveat: the `agy` `/model` panel and `agy --model=...` use **product display names** (shaped like
`Gemini 3.5 Flash`). Google does not document how an id from the API maps to a panel entry when a custom
endpoint is configured, nor whether that list comes from your endpoint at all. If your model is missing
from the panel, there is no further official guidance — we have **not tested** this, so we describe it as-is.

Once the endpoint checks out, run a conversation in `agy`.

## Vision input vs. image generation

Tools like `agy` can **read images** — feed them a UI screenshot, an error screenshot or an
architecture diagram and let the model write code or debug from it. That is a different thing from
**generating** an image:

- **Vision input**: reference an image file path in your prompt, or paste / drag an image in.
  Gemini models have vision. Typical uses: rebuilding a UI from a design, locating a bug from an
  error screenshot, reading an architecture diagram.
- **Image generation**: requires the dedicated `gpt-image-2` model on QCode's image endpoint —
  see [gpt-image-2 Image Generation](/docs/usage/image-2).

## Troubleshooting

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| CLI won't start | `modelProvider: "gemini"` is set but `GEMINI_API_KEY` is missing | Add the env var, or remove the field to return to account sign-in |
| 401 | Key not injected or wrong | Check `GEMINI_API_KEY` — `cr_` prefix, no stray spaces |
| 404 | `GOOGLE_GEMINI_BASE_URL` carries an extra `/v1beta`, or the path prefix is wrong | Stop at `/gemini`, as in the official example; the trailing-slash behaviour is not documented |
| `model_not_available_on_endpoint` | A Claude / GPT model was requested | This leg serves Gemini only; change client or model |
| Model-name error | Retired or misspelled id | Use the Step 4 `curl` to list what is actually callable |
| Slow / timing out from China | Using the `api` apex domain | Switch to `https://asia.qcode.cc/gemini` |
| `/logout` does nothing | You authenticated with an API key | Expected — there is no session to clear |

## Next

- [Endpoints & API Paths](/docs/getting-started/endpoints-and-api-paths) — protocol × model-family table
- [Gemini CLI Integration](/docs/ide/gemini) — the predecessor (enterprise keys still work)
- [Subagents](/docs/advanced/subagents) — orchestrating background agents
- [Automation & CI/CD](/docs/advanced/headless) — headless mode and scripting

> No QCode key yet? One `cr_` key covers Claude, GPT, Gemini and image models (on different
> protocols — see the table above). See [pricing](https://qcode.cc/pricing) to get started.