Antigravity CLI Setup Guide

Intermediate · 15-20 min · Google account required

Reference page for: Antigravity CLI setup and Gemini CLI migration. Other pages link here for Google's terminal-agent workflow.

Overview

Antigravity CLI is Google's terminal interface for the Antigravity agent platform. Google now frames it as the successor path for consumer and free Gemini CLI users, while keeping enterprise/API-key Gemini CLI access available for specific Google Cloud and paid Gemini paths.

Use Antigravity CLI when you want:

• A terminal agent that shares the Antigravity 2.0 backend
• SSH-friendly, keyboard-first workflows
• Multi-step agent work without living in a desktop IDE
• Google's current consumer/free successor to Gemini CLI

Do not treat Antigravity CLI as a replacement for direct Gemini API access. If a workflow uses Google AI Studio, GOOGLE_API_KEY, GEMINI_API_KEY, Cherry Studio, OpenCode, Vox, or another provider client, keep following the Gemini API setup for that tool.

Install

Use the official installer from the Antigravity CLI repository or the Antigravity CLI docs.

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

irm https://antigravity.google/cli/install.ps1 | iex

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

Then verify the command:

agy --version
agy --help

If the installer added files but your shell cannot find agy, check that the install directory is on your PATH. The installer usually places the binary in a standard user location such as ~/.local/bin or ~/bin. Add the relevant path to your shell profile, reload it, and restart the terminal:

# Example for ~/.local/bin on macOS/Linux
export PATH="$HOME/.local/bin:$PATH"

Authenticate

Antigravity CLI authenticates through the system keyring and falls back to Google Sign-In when no active session exists.

agy

On a local machine, the first run opens a browser sign-in flow. In an SSH session, it prints an authorization URL that you complete in a local browser.

To clear saved credentials from inside an Antigravity session:

/logout

For enterprise access, connect the relevant Google Cloud project during onboarding. Do not invent a standalone Antigravity API-key environment variable for normal use; Google's public CLI docs describe Google Sign-In and GCP onboarding, not a standalone API-key flow.

Core Commands

These commands are the verified public surface to document for ordinary setup work:

agy                         # Start an interactive terminal session
agy -p "Summarize this repo" # Run one prompt and print the response
agy --model <model>         # Choose a model for the session
agy models                  # List available models
agy --continue              # Continue the most recent conversation
agy --conversation <id>     # Resume a specific conversation
agy update                  # Update the CLI

For an initial prompt that should continue interactively:

agy --prompt-interactive "Read the project and propose a literature-review workflow"

For a one-shot research task:

agy -p "Read the markdown files in this directory and list the unresolved methodological questions."

Plugins

Gemini CLI extensions moved into the Antigravity plugin model. The current CLI exposes plugin management through agy plugin:

agy plugin list
agy plugin import gemini
agy plugin install <target>
agy plugin validate <path>
agy plugin enable <name>
agy plugin disable <name>

Use agy plugin import gemini when you are migrating old Gemini CLI extensions. Use agy plugin help for the current command surface.

Migrating From Gemini CLI

What changes

• The command changes from gemini to agy for the terminal agent.
• Installation changes from the old Gemini CLI npm package to the official Antigravity installer.
• Authentication changes from Gemini CLI's older flows to Antigravity's Google Sign-In/system-keyring flow.
• Gemini CLI extensions become Antigravity plugins.
• Consumer/free Gemini CLI access is moving to Antigravity CLI.

What does not change

• Direct Gemini API clients still use Google AI Studio and Gemini API keys.
• GOOGLE_API_KEY and GEMINI_API_KEY remain valid names in tools that call the Gemini API directly.
• Enterprise Gemini CLI access can still exist under Google's paid Gemini / Gemini Enterprise Agent Platform paths.
• Model selection still belongs to the model/provider guide for the tool you are using.

Migration checklist

• Replace old gemini terminal commands with agy only where the document is about the CLI tool.
• Replace old Gemini CLI setup links with Antigravity CLI docs.
• Remove the old Gemini CLI npm-package install step from new setup instructions.
• Keep Gemini API-key instructions in API-provider pages.
• Review any old Gemini CLI MCP example manually rather than auto-rewriting it.

Research Workflow

Use Antigravity CLI as the terminal agent in your research project:

cd ~/Documents/Research-Project
agy

Keep research protocols in visible project files that any agent can read:

README.md
AGENTS.md
CLAUDE.md
analysis/protocol.md

A useful first prompt:

Read the project protocol and folder structure. Then identify the safest next three steps for preparing this literature corpus for synthesis.

For large-context Gemini model work, use Antigravity CLI when you want Google's agent platform in the terminal. Use Google AI Studio, Cherry Studio, OpenCode, or Vox when the task is direct model comparison or API-backed multi-model work.

Troubleshooting

agy: command not found

Check that the installer path is in PATH. The binary is usually placed in a standard user location such as ~/.local/bin or ~/bin; add the relevant directory to your shell profile, reload it, and restart the terminal:

echo $PATH

Browser sign-in does not open

Copy the printed authorization URL into your browser. This is expected in SSH and remote terminal sessions.

Old Gemini CLI commands still appear in notes

Check whether the note is about the Gemini API or the Gemini CLI:

• API/model access: keep GOOGLE_API_KEY, GEMINI_API_KEY, and Gemini API docs.
• Terminal-agent access: migrate to agy.
• MCP examples: do not rewrite unless Antigravity publishes the exact syntax.

What's Next

Antigravity CLI now sits alongside Claude Code, OpenCode, and Cherry Studio. For the broader tool choice, see the CLI Tools Overview.

External references

• Google transition announcement
• Antigravity CLI GitHub repository
• Antigravity CLI documentation
• Gemini API models