Getting Started with Google Antigravity CLI (agy): The Beginner's Hands-On Guide

If you are accustomed to using AI chat interfaces in a web browser, you know the frustration of the copy-paste loop: you copy code from your editor, paste it into a web chat, prompt the model, copy the response back, paste it into your editor, run the linter, encounter an error, and repeat.

Google Antigravity CLI (agy) eliminates that friction entirely. It brings an agentic AI pair programmer directly into your operating system's terminal. Operating directly inside your project repository, agy can inspect files, write multi-file diffs, execute build commands, run test suites, search documentation, and orchestrate complex refactors—all without you ever touching a web browser.

Whether you are a data engineer writing pipelines, a backend developer fixing API bugs, or a DevOps engineer maintaining infrastructure, this hands-on guide walks you through everything you need to know from first launch to advanced terminal workflows.

1. What is the Antigravity CLI?

The Antigravity CLI (agy) is a terminal user interface (TUI) client for Google's agentic AI platform.

+-------------------------------------------------------------------------+
|                       HOW ANTIGRAVITY CLI WORKS                         |
|                                                                         |
|   [ Your Terminal ] <---> [ `agy` Interactive TUI ]                     |
|                                  |                                      |
|            +---------------------+---------------------+                |
|            |                                           |                |
|            v                                           v                |
|   [ Direct File Access ]                      [ Terminal Execution ]    |
|   - Reads project code                        - Runs tests (pytest)     |
|   - Proposes visual diffs                     - Runs linters (ruff)     |
|   - Edits multiple files                      - Git operations          |
+-------------------------------------------------------------------------+

Why Developers Choose the CLI:

1. Zero Context Switching: You remain inside your shell (zsh, bash, fish) and terminal emulator (iTerm2, Alacritty, GNOME Terminal, Windows Terminal).
2. Native File System & Command Access: The agent can directly read your repository, check git diffs, and run test suites to verify its own edits.
3. Remote & Cloud Friendly: Works seamlessly over SSH connections on remote Linux instances, cloud development environments, and Docker containers where GUI desktop apps cannot run.
4. Blazing Fast: Near-zero startup latency and minimal memory footprint compared to Electron-based desktop editors.

2. Launching and First-Time Setup

To get started, navigate to any code repository on your machine:

cd ~/my-projects/data-pipeline
agy

First-Run Authentication

The first time you invoke agy:

1. The CLI will display a secure Google authentication URL and a verification code.
2. Open the URL in your browser, log into your Google developer account, and approve the connection.
3. Return to your terminal. The CLI will automatically detect authentication and open the interactive TUI prompt.

▲ Google Antigravity (agy) v2.4.0
Workspace: /home/user/my-projects/data-pipeline
Model: Gemini 3.8 Flash (Active) | Quota: Healthy

Type /help for available commands or @ to reference files.
> _

Exiting Cleanly

To exit the CLI at any point:

• Press Ctrl + D twice (Ctrl + D Ctrl + D)
• Or type /exit or /quit and press Enter.

3. Useful Startup Flags

You can launch agy with command-line flags to control its behavior for a specific session:

4. The Two Power Prefixes: @ and !

The heart of using agy efficiently lies in two special prefix characters: @ (for file context) and ! (for shell commands).

+-------------------------------------------------------------------------+
|                         THE TWO POWER PREFIXES                          |
|                                                                         |
|   `@` = PULL CONTEXT IN  (Attach files, folders, and schemas)           |
|   `!` = PUSH COMMAND OUT (Execute bash commands directly in terminal)   |
+-------------------------------------------------------------------------+

1. The @ File Mention Prefix

Instead of copying and pasting code into the prompt, type @ followed by any part of a filename. agy will open an interactive fuzzy-search dropdown:

Example A: Single File Review

> @src/pipelines/ingest.py Can you explain what this pipeline does?

The agent reads ingest.py directly from disk and provides a clear breakdown of the logic.

Example B: Multi-File Cross-Referencing

> @models/schema.sql @src/api/routes.py The database migration changed the user table. Update the routes to match the new schema.

The agent compares the SQL schema against your Python routes and proposes precise code changes.

Example C: Entire Directory / Config

> @config/ Check if our environment settings have all required variables for production deployment.

2. The ! Native Shell Escape Prefix

You never need to switch terminal tabs or suspend agy with Ctrl+Z to check git status or run tests. Prefixing any command with ! executes it directly in your local shell and displays the output inside your session:

Example A: Checking Git Status

> !git status

Output: Shows modified files, untracked files, and current branch.

Example B: Running a Test Suite

> !pytest tests/test_auth.py

Output: Displays test passes or traceback failures.

Example C: Checking Node Dependencies

> !npm run lint

5. Essential Slash Commands with Real Examples

Type / into the prompt to view the built-in commands menu. Here are the core commands you will use every day:

1. Planning Complex Work (/plan)

When you have a large task that touches multiple files, do not let the agent start editing code blindly. Use /plan to make the agent act as an architect first:

Example:

> /plan We need to add JWT authentication with refresh tokens to our FastAPI app.

What happens: The agent analyzes your repository and outputs a structured execution plan:

1. Which dependencies to add to requirements.txt
2. Schema changes needed in models/user.py
3. Token utility creation in core/security.py
4. Route endpoints to implement in routers/auth.py
5. Unit tests to verify token validation

You can review and refine the plan before authorizing the agent to proceed with code generation.

2. The Interactive Architect Interview (/grill-me)

When building a new feature with ambiguous requirements, /grill-me turns the tables: the agent interviews you to clarify architecture, edge cases, and trade-offs before writing a single line of code.

Example:

> /grill-me I want to build an automated data quality pipeline for our Snowflake tables.

What the agent asks you:

• "What is your expected data volume and refresh frequency (streaming vs. batch)?"
• "Should data quality failures hard-stop the ELT pipeline or write to a quarantine table?"
• "Are you using Snowflake Dynamic Tables, Streams & Tasks, or dbt test?"

After answering 3–4 targeted questions, the agent produces an airtight specification.

3. Reverting Mistakes (/undo and /rewind)

If the agent makes an edit that you do not like or breaks a test:

> /undo

The agent rolls back its last set of file modifications, restoring your workspace to the state it was in prior to the last message.

4. Clearing Context (/clear)

As you work on multiple tasks in a long session, the conversation history grows. Feeding 40 messages of old context into every prompt consumes unnecessary tokens and can confuse the model.

> /clear

Instantly resets the conversation memory while keeping you inside the same project directory.

5. Checking Quotas and Model Usage (/usage or /quota)

To check how many tokens you have consumed, your remaining requests, and when your quota resets:

> /usage

Sample Output:

=== Antigravity Quota Status ===
Active Model:      Gemini 3.8 Flash
Status:            Healthy
Requests Today:    142 / 1,500
Tokens Consumed:   384,210
Next Refresh:      In 3 hours 15 minutes
Shared Pool:       82% remaining

6. Interactive Configuration Menu (/config or /settings)

Typing /config launches an interactive configuration dashboard inside your terminal:

• Toggle between Strict Review (always ask before running terminal commands) and Always Proceed.
• Change your default agent model.
• Enable or disable the isolated terminal sandbox.

6. Real-World Developer Scenarios (Step-by-Step)

Let's explore four real-world scenarios to see how agy accelerates everyday development.

Scenario 1: Fixing a Cryptic Python Traceback

The Situation: Your ETL job crashed with a KeyError: 'transaction_id'.

Step 1: Ingest the error log
> I got this crash during our batch run:
KeyError: 'transaction_id' in src/transformers/clean_data.py on line 42

Step 2: Attach the relevant file
> @src/transformers/clean_data.py Why is this KeyError occurring and how should we handle missing keys safely?

Step 3: Agent proposes a fix
The agent reads line 42, identifies that raw webhook events occasionally omit 'transaction_id',
and proposes replacing raw dictionary lookups with .get() and adding a schema validation check.

Step 4: Verify via native shell escape
> !pytest tests/test_clean_data.py
[Tests pass!]

Scenario 2: Writing Unit Tests for Untested Code

The Situation: You have a legacy utility module src/utils/date_parser.py with zero test coverage.

Step 1: Point the agent to the code
> @src/utils/date_parser.py Write a comprehensive pytest test suite for this module.
Cover edge cases including leap years, daylight saving transitions, and invalid format strings.
Save it to tests/test_date_parser.py.

Step 2: Agent writes the test file
The agent generates tests/test_date_parser.py with 8 parameterized test cases.

Step 3: Run the newly created tests
> !pytest tests/test_date_parser.py

Step 4: Fix any bugs discovered by the tests
If 1 of the 8 tests fails because the legacy code had an unhandled bug, prompt:
> One test failed with an unhandled timezone offset. Update @src/utils/date_parser.py to fix it.

Scenario 3: Refactoring a Database Model & Generating Migrations

The Situation: You need to add a status column to your accounts table and backfill it.

Step 1: Use planning mode
> /plan We need to add an 'account_status' enum column ('ACTIVE', 'SUSPENDED', 'CLOSED')
to our accounts table in @models/account.py and create an Alembic migration.

Step 2: Review the proposed migration plan
Agent details the column definition, default value, and Alembic revision step.

Step 3: Authorize generation
> Proceed with updating the model and generating the migration file.

Step 4: Test the migration
> !alembic upgrade head
[Migration applied successfully!]

Scenario 4: Investigating Git History and Diffs

The Situation: You pulled latest changes from your team, and your local environment stopped building.

Step 1: Check what changed recently
> !git log -n 3 --oneline

Step 2: Ask the agent to inspect the latest commit
> !git show HEAD
Explain why this commit might have broken our Docker container build.

Step 3: Agent spots the issue
Agent: "The commit updated the node base image from node:18 to node:20 in the Dockerfile,
which is causing node-gyp native compilation failures with our older dependencies."

7. Global Configuration (settings.json)

All persistent settings for the CLI are stored in your home directory:

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

A standard configuration looks like this:

{
  "model": "gemini-3.8-flash",
  "tool_execution_policy": "request-review",
  "sandbox_enabled": false,
  "telemetry_enabled": true,
  "command_allowlist": [
    "git status",
    "git diff",
    "npm test",
    "pytest",
    "cargo check"
  ]
}

Key Settings Explained:

• model: Defines which Gemini model powers your CLI sessions. Use gemini-3.8-flash for everyday quick edits and code lookups, or gemini-3.8-pro for deep architecture and complex refactors.
• tool_execution_policy:
  • "request-review": The agent asks your explicit permission before executing bash commands (recommended for beginners).
  • "always-proceed": Autonomous mode; the agent runs commands without prompting.
  • "strict": Commands are disabled unless explicitly allowlisted.

8. Common Beginner Mistakes (and How to Avoid Them)

Mistake 1: Dumping 10,000 Lines of Terminal Logs into the Prompt

• The Problem: Pasting giant stack traces or raw data files fills up the context window and slows down response times.
• The Fix: Save the log to a file (e.g., error.log) and reference it with @error.log, or pipe the specific error snippet using !tail -n 30 app.log.

Mistake 2: Forgetting the @ Mention

• The Problem: Asking "Can you fix the bug in auth.py?" without @auth.py.
• The Fix: The agent will have to guess or search your repository to find the file. Always use @auth.py so the agent reads the exact code immediately.

Mistake 3: Starting a New Session for Every Tiny Change

• The Problem: Exiting agy and relaunching it over and over.
• The Fix: Keep agy running in a dedicated terminal split or window. Use /clear when you want a clean slate, or use ! to run bash commands without leaving.

9. Antigravity CLI Quick-Reference Cheat Sheet

Print or bookmark this table for your daily development:

Summary: Mastering the Terminal Flow

The true power of Google Antigravity CLI is fluid velocity:

1. You spot an issue.
2. You mention the affected file with @.
3. The agent proposes a surgical diff.
4. You verify the fix in place with !pytest or !npm test.
5. You commit your code with !git commit.

Once this workflow becomes second nature, you will find yourself writing higher quality code in a fraction of the time—all without ever leaving your terminal.