Building Module 6 · Your Agent In Depth: Desktop App & CLI

Antigravity (App & CLI)

Last reviewed

Beginner

What you'll learn

~15 min
  • Know which Google path applies to you: Antigravity (personal accounts) or licensed Gemini CLI
  • Choose between the Antigravity desktop app and the `agy` CLI, and keep the CLI updated
  • Run the build loop (plan, approve, build, check, keep) with Antigravity's modes
  • Check your quota and know when to upgrade
ℹWhat happened to Gemini CLI?

Since 2026-06-18, personal Google accounts no longer work in the original gemini binary. Google’s replacement for individuals is Antigravity CLI (agy). Gemini CLI is still open source, and remains the path for an existing Gemini Code Assist Standard/Enterprise license, a paid Gemini API key or Vertex AI credentials (see the Enterprise section near the end).

ℹCloud Equivalent

Gemini Web at gemini.google.com is a free, browser-based way to use Google’s models for conversational tasks with no install. For a full browser terminal where you can install a CLI, see the Cloud Sandbox Cheat Sheet or set up your sandbox.

This is the in-depth lesson for Antigravity. If Antigravity is the tool you installed in Lesson 1.2, you are set up already: use this page for its modes, quotas and commands. Not your tool? Pick another from the Module 6 hub; one tool is enough.

Desktop app or CLI

The Antigravity app is Google’s desktop agent: download it from Google’s getting-started page for macOS, Windows, or Linux. It runs on the same free tier as the CLI, so a Google account is all you need to start.

On first run it asks what best describes your work, and your answer sets the layout. Pick Knowledge Work (or Science or Design) for a simpler workspace with starter workflows for documents, local folders, and scheduled tasks. Pick Software Engineering (or Data & Analytics) for the full developer layout: implementation plans to approve, proposed changes shown as diffs, terminals, and a browser preview of what it built. You can open a local folder in either.

The app and the CLI share your sign-in and the same agent, rules, and skills, so anything you set up in one works in the other.

Antigravity carries over what you’d learn in any modern CLI agent: execution modes, Skills, Hooks, Subagents, MCP servers and plugins. On first run it migrates your Gemini CLI sign-in, agy plugin import gemini converts extensions, and GEMINI.md files keep working unchanged.

What you get

  • A multi-vendor model menu: Free and Google AI Plus accounts get Gemini 3.8 Flash. Google AI Pro and Ultra add the Gemini 4 family and Claude 5.5 (Claude needs a paid, non-trial Pro plan).
  • Four execution modes: default (review each edit), accept-edits (auto-approve file writes), plan (read and outline first, then wait for your approval), and auto, which needs the terminal sandbox and is not available for business or enterprise accounts. Cycle with Shift+Tab.
  • Project context files: GEMINI.md or AGENTS.md at your project root give the agent persistent instructions.
  • Background tasks and one-shot mode: check /tasks later, or run agy -p "your prompt" non-interactively.
Install & sign in (skip if you already set this up in Lesson 1.2)

Install Antigravity CLI

Antigravity CLI is a native binary: no Node.js or npm required.

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

Check Google’s setup page for OS requirements.

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

Google’s CLI docs do not cover WSL; this Linux script is the route people use there. Check Google’s setup page for OS requirements.

PowerShell:

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

Antigravity CLI runs on Windows native: it does not require WSL. If you work in WSL, use the Linux command instead.

The installer adds the agy command (it lands in ~/.local/bin on macOS/Linux). Verify:

Terminal window
agy --version

Keep it current with agy update. If a new terminal can’t find agy, run agy install to repair your PATH.

Sign in

Start Antigravity CLI:

Terminal window
agy

It opens your browser to sign in with your Google account. Sign in, and you’re done.

💡Authenticating over SSH or on a remote server

Antigravity detects that you’re on SSH and, instead of trying to open a browser, prints an authorization URL. Open that URL on your local machine, sign in, copy the code it shows you, and paste the code back into the remote prompt.

Alternative, a Gemini API key: add "modelProvider": "gemini" to ~/.gemini/antigravity-cli/settings.json (the key alone does nothing), then:

Terminal window
export GEMINI_API_KEY="your-key" # create one at aistudio.google.com/app/api-keys
agy

Your first build

Already built welcome.html in Lesson 1.2? You’re set. If you are trying Antigravity as a second tool, run Lesson 1.2’s Step 2 in your ai-class folder.

The build loop and modes

The rhythm is plan, approve, build, check, keep. Open agy in your project folder, press Shift+Tab to cycle default, accept-edits, auto (where available), plan, and switch to plan mode. Describe the goal in one or two sentences, answer its questions, and approve the outline before it writes code. Then check the result and ask the agent to save a checkpoint (Module 7). The ordinary start:

Terminal window
agy

With approval prompts off:

Terminal window
agy --dangerously-skip-permissions

Adding --sandbox to either runs shell commands inside an OS sandbox. --dangerously-skip-permissions approves every tool permission request without asking, including file writes and commands; deny rules still take precedence, and a plan still waits for your review. This course starts practice sessions with it (what that does and does not protect); to be asked more often, start with agy. The four tools side by side are in the tool modes table.

CommandWhat it does
/modelChoose the reasoning model; the choice persists across sessions. /model <name> <prompt> runs one prompt on another model and switches back
/permissionsInteractive manager for which tools run without asking
/usageCheck model quota consumption (/quota is the same)
/effortSet how hard the model thinks (low, medium, high, and on some models Extra (xhigh) or max; --effort at launch). Gemini 4 Neon and Hydrogen default to High
/diffReview pending changes
/resumePick up an earlier conversation
/clearStart a fresh conversation (/new is the same)
/rewindRoll the conversation back to an earlier message (/undo is the same; see below for files)

Review, undo, and resume

/diff opens the interactive diff viewer. Google documents no automated review command, so after reading the diff, ask: “Review the changes you made in this session for bugs. List the findings; do not fix anything yet.” For undo, ask the agent to save a checkpoint before each task; /rewind rolls back the conversation, but check /diff afterwards because the docs do not say it restores files. agy -c reopens your last conversation and /resume picks an earlier one (conversations).

Plans and quotas

Antigravity, app and CLI alike, works without a subscription: the free tier gets Gemini 3.8 Flash under basic weekly rate limits. Google AI Pro and Ultra raise the ceiling and add a faster-refreshing five-hour bucket on top of the weekly one:

PlanPriceWhat it means for Antigravity
Free$0Gemini 3.8 Flash. Basic weekly limits
Google AI Plus$4.99/moSame Antigravity model access as Free; Plus adds Gemini 4 Hydrogen in the Gemini app, not in Antigravity
Google AI Pro$19.99/moHigher limits, refreshed every five hours until the weekly cap
Google AI Ultra 5x$99.99/moHigher agent-request limits than Pro, refreshed every five hours, plus higher weekly rate limits (Google publishes no Antigravity multiple; the “5x” is the Gemini app’s)
Google AI Ultra 20x$199.99/moThe highest agent-request limits, refreshed every five hours (the “20x” describes Gemini app usage, not Antigravity)

Prices from Google’s AI plans page; the Cloud Sandbox Cheat Sheet keeps current prices for every tool in one place.

Check your usage any time, even from a script, without spending quota:

Terminal window
agy -p "/usage"

Quota comes in two buckets, Gemini Models and Claude and GPT models, and /usage (or /quota) shows each one’s weekly limit and, where your plan has one, its five-hour limit. Using Claude does not draw down your Gemini allowance, and the reverse.

Eligible US college students can redeem a free year of Google AI Pro before 2026-12-31 (student offer); it charges $19.99/month when the year ends unless you cancel. The free tier is enough to finish this course: upgrade when the weekly limit is what slows you down.

Enterprise: keeping Gemini CLI

If your organization has a Gemini Code Assist Standard or Enterprise license (no new sales since 2026-10-09), Gemini CLI is the supported path, as it is for a paid Gemini API key or Vertex AI credentials:

Terminal window
npm install -g @google/gemini-cli
gemini --version

Sign in with your licensed Google Workspace account (you’ll be asked for a Google Cloud project ID); GEMINI.md files work as before. Organizations that want Antigravity sign in with a Google Cloud project, whose controls and billing differ from personal accounts; auto mode and Remote Agents are not available to business accounts.

🏛️In Your Field: Government Devclick to expand

For government work, use an enterprise seat (a Gemini Code Assist license or Antigravity through an agency Google Cloud project), not a personal free tier, and route tool access through your security office. An enterprise seat is not a CUI determination: CUI must not go into AI systems that are internet-enabled or external to agency control (ISOO Notice 2026-01); see approved tools and endpoints.

Verify it works

agy --version should print a version number. If you get “command not found,” confirm ~/.local/bin is on your PATH (agy install fixes it). Keep current with agy update.

🔧

When Things Go Wrong

Use the Symptom → Evidence → Request pattern: describe what you see, paste the error, then ask for a fix.

Symptom
Google account authentication fails or browser doesn't open
Evidence
Error: Could not open browser for authentication or 'Authentication failed'
What to ask the AI
"Antigravity CLI (agy) tried to open my browser for Google sign-in but it failed. I'm on a remote server via SSH. How do I complete sign-in using the authorization URL it prints, and what are the alternatives (Gemini API key with modelProvider: gemini)?"
Symptom
'agy: command not found' after the install script runs
Evidence
bash: agy: command not found
What to ask the AI
"The Antigravity CLI install script finished but my terminal can't find the 'agy' command. It installs to ~/.local/bin: how do I check whether that directory is on my PATH, and does 'agy install' fix it?"
Symptom
The old 'gemini' command refuses to sign in
Evidence
Sign-in is rejected for a personal Google account (the wording varies by version)
What to ask the AI
"Gemini CLI rejects my personal Google login with an unsupported-client error. Should I move to Antigravity CLI (agy), switch Gemini CLI to a Gemini API key, or get a Gemini Code Assist license? Walk me through the trade-offs."
Symptom
Antigravity says I've hit a rate limit
Evidence
Requests fail with a quota or rate-limit error mid-session
What to ask the AI
"Antigravity CLI is telling me I've hit a limit. How do I check my remaining quota, and what are my options: wait for the weekly reset (Free) or five-hour reset (Pro and Ultra), switch to a lighter model, or upgrade to Google AI Pro?"

Key Takeaways

  • Individuals use Antigravity (agy or the app); Gemini CLI stays for Code Assist licenses, paid API keys and Vertex AI
  • Two ways in: the Antigravity app (free tier), or the CLI with one curl command (irm in PowerShell; no Node.js), then agy update to stay current
  • The build loop: plan, approve, build, check, keep; Shift+Tab cycles default, accept-edits, auto (where available) and plan
  • Free tier gets Gemini 3.8 Flash under weekly limits; Google AI Pro and Ultra add Gemini 4, Claude 5.5 and a five-hour bucket; /model shows what your account can use
  • For government work, use an enterprise seat, not a personal account
Search lessons