Antigravity Setup Guide: CLI and Desktop

Intermediate · 15–20 min · Google account; Cloud project for the desktop route

The terminal is where your files live, so your agent should live there too.

Overview

Most of this page covers the terminal client. The last section, Desktop app with a Google Cloud project, connects Google's desktop assistant to a Cloud project that pays for its model access. Desktop sign-in and CLI authentication are separate setup routes.

Antigravity CLI is Google's terminal interface for the Antigravity agent platform. Google positions it as the successor path for consumer and free Gemini CLI users. Enterprise and API-key Gemini CLI paths remain available for specific Google Cloud and paid Gemini plans.

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 (opens in a new tab) or the Antigravity CLI docs (opens in a new tab).

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. Google also documents an optional Gemini API-key path: set modelProvider to gemini in ~/.gemini/antigravity-cli/settings.json and supply GEMINI_API_KEY through your environment. Setting the key alone does not select that provider. Follow the installation and authentication guide (opens in a new tab) for your account type; API billing is separate from subscription access.

Core commands

These are the commands you need 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 became Antigravity plugins. The current CLI provides 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. Check Google's plugin guide (opens in a new tab) for the current manager commands.

MCP servers

Antigravity CLI supports agy mcp add and agy mcp list. For a local stdio server:

agy mcp add lotus-wisdom -- npx -y lotus-wisdom-mcp
agy mcp list

Run agy mcp add --help for your installed version's transport, environment, and header options; flags precede the server name. Google documents registration in its MCP codelab (opens in a new tab) and alternative configuration paths in the MCP guide (opens in a new tab). CLI commands were checked against the official headless guide and changelog on October 19, 2026; this review did not test installation or a live server session.

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.
• The default authentication path is Google Sign-In/system keyring; an explicitly configured Gemini API-key path is also available.
• 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 (opens in a new tab).
• 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 installer usually places the binary 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.

Desktop app with a Google Cloud project

Use this route to connect Antigravity Desktop to an existing Google Cloud project through browser sign-in. It is separate from personal subscriptions, the standalone Antigravity IDE and the CLI above. It matters when a course or team pays for model access through a Cloud project rather than an API key; Vertex AI setup explains that arrangement, and Model access for a class says when a course would choose it.

Install the desktop app from Google's Antigravity download page (opens in a new tab), then check your Cloud project.

The steps below combine Google's documented Cloud route with our October 4, 2026 staff pilot using Antigravity 2.19.1.

Sign in through Google Cloud

1. In the desktop app, choose the business-account sign-in route, then Continue with Google Cloud.
2. Complete browser sign-in with the identity authorized for your intended project.
3. Select the Cloud project route for consumption-based billing. The pilot labeled this Pay as you go, separately from a Gemini Enterprise license.
4. Enter your project ID when prompted. Copy the ID from Cloud Console, not the project's display name.
5. Choose a supported location that meets your institutional requirements. The pilot used global; your requirements may differ.

Google's enterprise documentation (opens in a new tab) covers license selection and other authentication methods. The sign-in screen also explains the route's terms and logging.

Check the connected account

Open the account settings and inspect the signed-in identity, project ID and selected plan before sending a request. In the pilot, the connected account panel labeled the plan Agent Platform.

If the project or identity is wrong, sign out and repeat the Cloud selection. If access is denied, ask the project administrator to check your identity and permissions. Do not create a service-account private key as a shortcut for this browser sign-in route.

Pay as you go identifies how consumption is billed. It does not prove that education credits will cover a request.

Check one request and reopen it

Send a short message to an available Gemini model without project files or tools. Check the response, then reopen the conversation from history. If that works, the basic connection is ready; test the features your project needs next.

Our pilot checked a short Gemini response and history reopening. It did not test student onboarding, credit offsets or project-building features.

If the desktop route fails

Signing into the assistant does not give an application you build its own model access. Configure that application's credentials and billing separately, and keep credentials out of browser code and shared project files. For a different desktop client, return to Choose a client.

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 (opens in a new tab)
• Antigravity CLI GitHub repository (opens in a new tab)
• Antigravity getting started (opens in a new tab)
• Antigravity headless commands (opens in a new tab)
• Gemini API models (opens in a new tab)