Core AI Coding Tools

Antigravity CLI

agy, the Google Antigravity command-line tool, connected over the Gemini protocol.

This guide covers agy, the Google Antigravity command-line tool. agy speaks only the Gemini protocol, so it needs a key from a Gemini group; for Claude or GPT models use Claude Code, Codex or similar tools. The Antigravity desktop app does not accept a custom API key and is not covered here.

1Install and check the version

Choose your operating system at the top right of the page first; the commands below follow it. Run the install command:

macOS / Linux

curl -fsSL https://antigravity.google/cli/install.sh | bash

On macOS, also add the install directory to PATH:

macOS

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

Open a new terminal and confirm that it prints a version number:

Terminal

agy --version

2Configure access

YOUR_API_KEY in the examples is a placeholder and will not work as copied. Sign in to pick one of your keys and fill it into every example on this page.

First write the agy settings file, which switches it to API key authentication.

~/.gemini/antigravity-cli/settings.json

{ "modelProvider": "gemini" }

Write it in one step (skipped if already configured, otherwise backed up first)

# 1. Write the agy settings file to switch to API key authentication; skipped if already configured
dir=~/.gemini/antigravity-cli
file="$dir/settings.json"
mkdir -p "$dir"
if ! grep -q '"modelProvider"[[:space:]]*:[[:space:]]*"gemini"' "$file" 2>/dev/null; then
  # Back up an existing settings file to a timestamped .bak
  [ -f "$file" ] && cp "$file" "$file.$(date +%Y%m%d-%H%M%S).bak"
  echo '{ "modelProvider": "gemini" }' > "$file"
fi

This may overwrite existing settings

If settings.json already has modelProvider set to gemini, the command above leaves it alone. Otherwise it copies the existing file to a timestamped .bak file and then replaces it. If you have MCP or other options configured there, merge by hand and add only the modelProvider field. When saving by hand, use UTF-8 without a BOM.

Then set two environment variables. The command writes them to the profile of the shell you are using: ~/.zshrc for zsh (the macOS default) or ~/.bashrc for bash (the default on most Linux systems). Only one of the two files is needed.

macOS / Linux

# 2. Append the key and gateway URL to your shell profile: ~/.zshrc for zsh, ~/.bashrc for bash (picked up by new terminals)
case "$SHELL" in */zsh) rc=~/.zshrc ;; *) rc=~/.bashrc ;; esac
# Back up first, then drop earlier copies of these variables so reruns do not pile up
touch "$rc" && cp "$rc" "$rc.agy.bak"
grep -v -e '^# Antigravity CLI (agy)
#39; -e '^export GEMINI_API_KEY=' -e '^export GOOGLE_GEMINI_BASE_URL=' "$rc.agy.bak" > "$rc"
echo '# Antigravity CLI (agy)' >> "$rc"
echo 'export GEMINI_API_KEY="YOUR_API_KEY"' >> "$rc"
echo 'export GOOGLE_GEMINI_BASE_URL="https://api.keyvia.cc"' >> "$rc"
# Apply to the current terminal as well, so no restart is needed
export GEMINI_API_KEY='YOUR_API_KEY'
export GOOGLE_GEMINI_BASE_URL='https://api.keyvia.cc'
echo 'Setup complete. Go to your project directory and run agy to start.'

The command ends by printing a setup-complete message. The current terminal is ready to use; other terminals that were already open must be reopened for the variables to take effect.

Note

GEMINI_API_KEY and GOOGLE_GEMINI_BASE_URL are general-purpose names. Gemini CLI, the Google GenAI SDK and other tools on the same computer read them too, so their requests also go through this service. The key is stored in plain text; do not upload or share this file.

The lines are written under a # Antigravity CLI (agy) comment so you can find them later. Running the command again does not duplicate them: it backs the file up as .agy.bak, removes earlier copies of these two variables, then writes the new values, so rerun it to change the key. To stop using it, delete the comment and the two lines below it.

Field notes

GOOGLE_GEMINI_BASE_URL takes the root URL without /v1 or /v1beta; agy appends the path itself.

modelProvider accepts only gemini; any other value is ignored and agy falls back to Google account sign-in. Setting GEMINI_API_KEY without this field has no effect, and agy does not read .env files.

The key must be in a group that supports the Gemini protocol.

3Verify

Go to your project folder and start agy:

Terminal

agy

On first run, press Enter on the colour scheme screen.
On the Terms of Service screen Enter only ticks the box; move right to Done first, then press Enter.
When asked whether to trust the current folder, choose Yes, I trust this folder.

agy skips the sign-in screen and opens the main interface, and the header shows Gemini API key instead of an account email, which means the key is in use. Send a message; if the reply comes back and the request appears in the console usage records, the setup works.

Troubleshooting

command not found: open a new terminal; on macOS, make sure you ran the PATH command. A red ERROR: logging before google.Init during the Windows install can be ignored as long as agy --version prints a version number.
A Google sign-in page opens, or you see authentication required: the settings are not active. Run the commands in step 2 again and open a new terminal.
404 or model unavailable: make sure the key belongs to a Gemini group and the selected model is in the model list.
gemini-3.1-flash-lite-preview is not supported: agy uses this model in the background to title sessions. It does not affect normal use and can be ignored.
Invalid thought signature: start a new session and do not switch models partway through one. If it persists, open a support ticket with the time of the error.
For 401, 403, 429 and other status codes see Error codes.