Antigravity CLI: The agy Command Guide for Builders

Antigravity CLI is Google's terminal coding agent, invoked with the agy command. It shipped as the replacement for Gemini CLI, which Google shut down for free, Pro, and Ultra users on June 18, 2026. If you typed gemini in your terminal, agy is what Google wants you typing now.

This is the practical guide to the tool itself: what it is, how to install it, the commands that matter, and the honest comparison against Claude Code. If your goal is specifically moving off the dead Gemini CLI, read the Gemini CLI shutdown and migration guide first, then come back here for the day-to-day usage.

What Is Antigravity CLI?

Antigravity CLI is a Go-based binary that brings Google's agent-first workflow into the terminal. It's the command-line sibling of Google Antigravity, the agent IDE - same multi-agent model, no editor window.

Three things define it:

• Single Go binary. It ships as one compiled executable - install is a one-line script, no Node or Python runtime to manage. It defaults to Gemini 3.5 Flash and auto-selects the model (no --model flag).
• Multi-agent by default. Like the Antigravity IDE, agy is built to dispatch and coordinate multiple agents rather than run one linear chat. It shares the same agent harness and settings as Antigravity 2.0.
• A Google-led product, not a community project. Gemini CLI was open source and took 6,000+ community pull requests before Google wound it down. agy is built and controlled by Google around that shared harness - don't expect the same community-extension flow.

One caveat worth knowing before you commit: at launch, Antigravity CLI does not have full 1:1 feature parity with Gemini CLI. Google kept the critical pieces (Agent Skills, Hooks, Subagents, and Extensions-now-plugins), but if you depended on a specific flag, check it works in agy before you rewrite your scripts.

How to Install Antigravity CLI

Install is a one-line script. On macOS or Linux:

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

On Windows (PowerShell):

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

Then start it and authenticate:

agy

agy authenticates through your system keyring, falling back to Google Sign-In (pick "Use a Google Cloud project" when prompted). Check your setup with /config, then smoke-test it non-interactively:

agy -p "summarize this repo"

Both agy and the old gemini command can coexist on the same machine, which makes a gradual cutover easier if you still have a paid API key keeping Gemini CLI alive.

The Slash Commands That Run It

agy is driven by slash commands in the TUI. These are the ones you'll actually use:

Two design changes worth flagging if you're coming from Gemini CLI. Browser use is now opt-in via /browser - Google moved it behind a command because the agent kept reaching for the browser when it shouldn't. And subagents are dynamic: you hand the orchestrator a goal in plain English and it decides what specialized subagents to spawn and runs them in parallel, no orchestration code from you.

On models, agy defaults to Gemini 3.5 Flash but /model also exposes Gemini 3.1 Pro, Claude Sonnet, Claude Opus, and GPT-OSS 120B (subject to your plan). Skills work like Gemini CLI: drop a markdown file at .agents/skills/lint.md and it becomes /lint. Hooks are JSON lifecycle interceptors (before tool call, after file edit, on session start), with workspace hooks overriding global ones. Sandboxing uses nsjail on Linux and sandbox-exec on macOS.

Migrating from Gemini CLI

If you're coming straight off Gemini CLI, the move is mostly mechanical and agy ships an importer:

• Import your extensions: agy plugin import gemini converts installed Gemini CLI extensions into Antigravity plugins.
• Move workspace skills: mv .gemini/skills/ .agents/skills/ - Antigravity looks for them under .agents/skills/.
• MCP config: Antigravity uses a dedicated mcp_config.json (workspace path: .agents/mcp_config.json). For remote servers, rename the url field to serverUrl.
• Context files stay put: GEMINI.md keeps working - no rename needed. agy reads both GEMINI.md and AGENTS.md. New projects increasingly standardize on AGENTS.md, but that's optional.
• Update automation: swap every gemini call in CI/CD, shell scripts, and cron jobs for agy.

The one that bites people is automation. Any pipeline calling gemini -p "..." broke on June 18 with no grace period. Audit your scripts first - that's where the silent failures hide. Full checklist in the migration guide.

The Quota Trap (Read This Before You Commit)

This is the single biggest complaint from early agy users, and it's not a bug - it's how the tool works. Subagents burn quota in parallel. One plain-English goal can spin up a nested loop of 10+ model calls without asking, and the meter runs the whole time.

The numbers from the field are brutal. One paid Google AI Pro user reported being locked out with an "Individual quota reached" error after exactly two prompts in agy - the same Pro quota that survived 1,000+ code modifications in the old Gemini CLI. The quota is also shared across the Antigravity desktop app, CLI, and SDK, so running agents in parallel across projects drains it even faster.

Three habits keep you out of the lockout:

• Watch /usage constantly. Unlike Gemini CLI, the agent can't see its own remaining quota and won't throttle itself. You are the governor.
• Don't over-parallelize. Pro/Ultra quotas comfortably support 3 to 5 parallel subagents. Past that you hit the ceiling before lunch. Less parallelism often means more total throughput across the day.
• Reach for /grill-me on expensive work so the agent plans before it spends, instead of looping autonomously on a vague goal.

If you're on the free tier, expect aggressive throttling and queued subagents that never start. For real throughput, connect a billing-enabled Google Cloud project.

Scripting and CI Gotchas

If you automate agy, three traps will cost you a debugging session each:

• Non-TTY hangs silently. In GitHub Actions or any non-interactive shell, a plain agy call waits forever for an approval prompt that never renders. The old --yolo sailed through; now you express approval explicitly with --headless plus an --approve policy. --approve all auto-approves file writes and command execution, so keep it inside a sandbox.
• agy -p can drop stdout. Early versions silently dropped stdout when --print/-p ran under a pipe, subprocess, or redirect. If a script reads agy's output, verify you actually get bytes back before trusting it.
• GEMINI_API_KEY is ignored. Local auth uses the agy auth login token; CI uses ANTIGRAVITY_TOKEN. Leave the old variable set and you'll burn time wondering why it has no effect.

None of these are dealbreakers, but they're the difference between a clean cutover and a broken Monday pipeline. Test on a throwaway workflow first.

Antigravity CLI vs Claude Code

This is the comparison most builders are actually searching for, because Claude Code is the closest terminal-native analog. Here's the honest split:

Short version: if you live in the Google ecosystem and want parallel agents from the terminal, agy is the natural pick. If you want the most mature terminal coding agent today and don't care which cloud it talks to, Claude Code is still the safer bet. Many builders will run both - agy for Gemini-backed tasks, Claude Code for everything else.

For the full field including Cursor and the Antigravity IDE, see our best AI coding agent comparison.

Should You Switch?

• You were on Gemini CLI free/Pro/Ultra: You have to move - the tool is dead. agy is the path of least resistance if your work is Google-centric.
• You hold an enterprise Gemini Code Assist license: You keep both tools, so there's no rush. Test agy on a side project before you standardize on it.
• You're tool-shopping fresh: Don't pick agy purely because it's new. The missing Gemini CLI parity and the quota trap are real trade-offs - if you run high-volume agent loops, the per-prompt cost ceiling will bite. Weigh it against Claude Code and Cursor on the work you actually do.

The smart play right now is to install agy, port one real workflow, and keep your fallback alive until the CLI proves it covers your cases. New tools earn trust by surviving your actual pipeline, not a toy demo.