Antigravity CLI: the complete guide

Get started

What is a terminal?

The terminal is the program where you start Antigravity CLI and give the agent tasks. The words you meet there, such as terminal, command, CLI and path, are explained in the list below the text.

Your computer already has a terminal. On a Mac you open Terminal under Applications, Utilities. On Windows you search for PowerShell in the Start menu. On Linux the program is usually called Terminal.

Antigravity CLI works in the folder where you start agy. So always start in your project's folder, never in your whole home folder. The command mkdir creates a new folder, and cd moves you into it.

What is Antigravity CLI?

Antigravity CLI is a coding agent, an AI program that does not just answer but also does the work. The agent writes and changes files, runs commands, searches the code and explains what it has done. On antigravity.google, Google calls the tool the lightweight, terminal-first way to work with Antigravity agents.

Antigravity CLI replaces Gemini CLI for individuals. Google's developer blog wrote on 19 May 2026 that Antigravity CLI is written in the Go programming language and can run several agents in the background. The tool keeps skills, hooks, subagents and extensions. The extensions are now called Antigravity plugins. The Extensions part further down explains what they do.

Google Antigravity is Google's platform for coding agents and is available for macOS, Windows, Linux and Googlebook. The platform has four parts, according to antigravity.google:

• The Antigravity app, which manages several agents at once.
• A code editor.
• Antigravity CLI, the agent in the terminal.
• An SDK, a code package for building your own agents.

Who is Antigravity CLI for?

Antigravity CLI is for you if you want an AI to do coding work in a real project. The agent can explain unfamiliar code, fix bugs, build a small app or write tests, small programs that check that the code works. Google writes on the product page that the tool suits builders who live in the terminal.

You do not need to know how to program to ask for an explanation. You do need to understand what you approve.

Individuals sign in with their Google account. Gemini CLI's project description on GitHub names Antigravity CLI as the right tool for free accounts, for Google AI Pro and Ultra and for Argon, Google's largest model. Companies reach Antigravity CLI through a business plan via Google Cloud, which the section on pricing describes.

If you prefer windows and buttons, the Antigravity app and the code editor are on the same platform. If you only want to chat with Gemini, the Gemini app is enough.

How do you install Antigravity CLI?

You install Antigravity CLI with one command that you paste into the terminal. The command fetches an install script from antigravity.google and runs it. A script is a file of commands that the computer runs one after another. The commands below are copied from Google's download page.

On Mac and Linux, curl downloads the script and bash runs it. The program ends up in ~/.local/bin/agy.

On Windows you run the command in PowerShell. The program then ends up in C:\Users\<username>\AppData\Local\agy\bin. If you use CMD, there is a separate command for it.

Then check the installation with agy --version. If the terminal answers with a version number, you are done.

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

agy --version

How do you sign in to Antigravity CLI?

Antigravity CLI signs in with your Google account. First agy looks for a saved sign-in. If there is none, the browser opens. There you sign in with your personal Google account, or choose business sign-in for a company account.

The computer saves the sign-in in its password store, which is called Keychain on Mac, Credential Manager on Windows and Secret Service on Linux. Next time agy signs in without asking. The command /logout signs out and deletes the saved details.

An API key for Gemini also works. The key is a long code that tells Google who you are. Google's sign-in guide describes two steps. First write "modelProvider": "gemini" in the settings file ~/.gemini/antigravity-cli/settings.json. Then put the key in the environment variable GEMINI_API_KEY.

Antigravity CLI does not read the variable GOOGLE_API_KEY, and it does not read files called .env. With a key you pay per request. How to get the key is in part 3 on the Gemini API.

Your first session with Antigravity CLI, step by step

The first session takes seven steps and follows Google's own getting-started guide:

mkdir agy-demo && cd agy-demo
agy

mkdir agy-demo
cd agy-demo
agy

How you work

How does Antigravity CLI work?

Antigravity CLI works in an agent loop. The agent reads, plans, edits and verifies, round after round, until the task is done. In each round the model decides what is needed, for example reading a file or running a test. The result goes back to the model before the next step.

Your approval is your control. In the default mode the agent shows a diff and waits before it creates or changes a file. The agent also asks before it runs a command. The principle is called human in the loop.

The agent can split large tasks among subagents, which are helper agents. Each subagent starts with an empty memory in its own conversation. The /agents panel shows what they are doing and lets you approve their requests.

You choose the model with /model, and the choice is saved for next time. Esc interrupts the agent in the middle of a step. Ctrl+C stops an answer while it is being written.

Which modes does Antigravity CLI have?

Antigravity CLI has four modes, according to Google's page on modes. The mode decides how much the agent may do without asking. Shift+Tab switches mode during the session.

• default shows every file change and asks before every command. Antigravity CLI always starts in this mode, and this is where you should begin.
• accept-edits approves file changes in the project's folder automatically. Commands still ask.
• plan lets the agent investigate and write a plan before it touches any code. You approve the plan first.
• auto approves file changes and runs commands in a sandbox without asking. A sandbox is a closed-off space that protects the rest of the computer. Risky actions still ask. The mode needs version 1.3.5 or later on Mac and Linux and 1.4.4 or later on Windows, according to the page on modes. You also need the terminal sandbox and a personal account.

How do you write a good task for Antigravity CLI?

A good task says what the agent should do, where, which rules apply and how the agent knows it is done. Compare "fix the login" with "The login in src/auth.ts lets in wrong passwords. Find the bug, fix it and run the tests. Do not change any other files." The second task gives the agent a goal and a way to check the result.

Google's best-practices guide gives two pieces of advice. Let the agent explore, plan and execute in separate steps. Also give it a way to check itself, for example tests or a build command. More advice on writing for AI is in the prompt guide.

• Point to files with @, for example @src/auth.ts. Then the agent knows exactly which file you mean.
• Show the error with a screenshot. Copy the image and press Ctrl+V in the input box, as Google's best-practices guide describes.
• Say how the result should be checked, with a test, a command or something that should be visible.
• Say what must not change.
• Ask for an explanation before you approve a change you do not understand.
• Start a new conversation with /clear when you switch tasks. Then the old context does not get in the way.

What are GEMINI.md and AGENTS.md?

GEMINI.md and AGENTS.md are text files with rules that Antigravity CLI reads every time. In the files you write what the agent should always know about your project, for example how the project starts, how the tests run and which rules the code follows. Google calls such instructions rules.

Antigravity CLI looks for the files in several places. In the project the agent reads GEMINI.md, AGENTS.md and the .agents/rules/ folder. The agent looks in the folder where you start agy and in the folders above it, up to the project's top folder. Subfolders are not read.

Rules for all your projects go in ~/.gemini/GEMINI.md or ~/.gemini/AGENTS.md. The agent combines all the rules it finds.

Keep the files short and concrete. Each file is cut off after a certain size, and global rules and rules that always apply share a limited number of tokens, according to Google's page on rules. The limits are on the same page. A token is roughly a piece of a word, and every line takes up room in the agent's working memory, the context window.

# Project: The booking site

## Getting started
- Start: npm run dev
- Test: npm test

## Rules
- Write all text in Swedish.
- Never change files in the migrations/ folder.
- Run the tests before you say you are done.

Which commands does Antigravity CLI have?

Commands in Antigravity CLI start with a slash, and you type them in the input box. According to Google's command reference, these are the most common:

• /help shows all commands and shortcuts.
• /config opens the settings, just like /settings.
• /model chooses the model.
• /diff shows the changes.
• /clear starts a new conversation.
• /permissions decides which commands are allowed, need asking or are denied.
• /mcp manages MCP servers, which are explained further down.
• /plugin manages plugins, which are add-ons.
• /usage shows how much of your quota, the usage included in your plan, you have used.
• /exit exits, just like /quit.

Where do you change the settings in Antigravity CLI?

Antigravity CLI saves its settings in the file ~/.gemini/antigravity-cli/settings.json. The easiest way to change them is /config. A panel opens, you choose with the arrow keys, and the change is saved straight to the file. Esc closes the panel.

Three settings are worth knowing. agentMode decides which mode the agent starts in. enableTerminalSandbox turns on the sandbox for commands. useG1Credits lets Antigravity CLI use your AI credits when the quota in your plan runs out. Google's settings page says useG1Credits is off from the start.

Flags change a single run. agy --mode=plan starts straight in plan mode, and agy --sandbox starts with the sandbox on. agy -c continues the latest conversation.

Extensions

How do you connect MCP servers to Antigravity CLI?

MCP, Model Context Protocol, is an open standard that gives an AI agent new tools, for example a database, GitHub, an issue tracker or a browser. An MCP server is a small program that offers the tools. The agent then uses them as its own.

You write the MCP servers into a file of their own. The file is written in JSON, a text format that programs can read. ~/.gemini/config/mcp_config.json applies to all projects, and .agents/mcp_config.json applies to a single project.

Each server sits under mcpServers. A server on your computer is given with command and args, and a server on the internet with serverUrl.

The command /mcp opens a panel. There you see whether the servers are running, reload the file and read logs. The example below is Google's own and starts a local server for a SQLite database.

{
  "mcpServers": {
    "sqlite-explorer": {
      "command": "node",
      "args": ["/usr/local/bin/sqlite-mcp-server.js"],
      "env": {
        "SQLITE_DB_PATH": "/var/data/app.db"
      }
    }
  }
}

Skills, plugins and hooks in Antigravity CLI

Google's features page describes three ways to extend Antigravity CLI:

Can you run Antigravity CLI in scripts?

Antigravity CLI can run a single task without a dialogue. The flag -p runs one prompt, prints the answer and exits. With --output-format json the answer comes as JSON, so another program can read it.

Google's best-practices guide shows the example below. The agent reads the changes in a git project and drafts a commit message, a short description of the change. Such a command can sit in a script, or in an automated CI/CD flow that tests and publishes code.

agy -p "Review this git diff and draft a conventional commit message"

Price and safety

How much does Antigravity CLI cost? Is it free?

Antigravity CLI can be used for free. The plan for individuals costs 0 dollars a month and gives several agent models with basic weekly limits, according to Google's Antigravity pricing page at the time of writing. Google AI Pro gives higher limits and Google AI Ultra higher still, the same page shows. The plans' prices are in part 1 on Gemini.

The plans give different models. Flash, Google's fast model for most work, is in the free plan, while Argon, Google's largest model, needs a paid plan, according to Google's Antigravity models page. The page also lists models from Claude and GPT. The range changes, so the models page shows which models are available right now.

The command /usage shows how much of the quota you have used, and /credits shows your AI credits. When the quota runs out, Antigravity CLI can continue on AI credits if you turn on useG1Credits.

Companies pay through Google Cloud. At the time of writing, the business plans start at 30 dollars per user per month, according to the pricing page. There is also a plan with no monthly fee, where the company pays for what it uses.

With a Gemini API key you instead pay per token. How the price is counted is in part 3. Prices change, so check them before you choose.

Is Antigravity CLI safe? Privacy and the sandbox

Antigravity CLI runs commands on your computer with your permissions. If you approve the wrong command, the agent can delete or leak files. Your most important protection is to read every diff and every command before you press Y.

Google can use what you write. According to the Antigravity terms, Google uses your prompts, your code and the agent's answers to improve its products. Employees and contractors may read the material, according to the same terms. The terms also say you can change that use in the settings.

The setting is called enableTelemetry in Antigravity CLI. The choice is saved with your account. For business accounts the setting is always off.

The sandbox shuts the commands in. In the sandbox, commands run without network access and can only write in the project's folders. They cannot reach sensitive files such as ~/.ssh and .env either. The sandbox is off from the start. On Windows the sandbox needs Windows 11 24H2 with the August 2026 update or later, according to Google's sandbox page.

Prompt injection is the biggest risk with agents. A web page, a file or an issue can contain text that tries to make the agent do something you did not ask for. Read more about prompt injection and in Is AI safe?.

Five habits protect you and your code:

• Start in the default mode.
• Turn on the sandbox with agy --sandbox when you work with unfamiliar code.
• Use git, so you can always go back to an earlier version.
• Never use a private account for customer data or personal data. Personal data is protected by GDPR.
• Never put passwords or keys in GEMINI.md.

Other tools

Gemini CLI: for companies and API keys

Gemini CLI is Google's older coding agent for the terminal, with the command gemini. Google announced Gemini CLI in a blog post on 25 June 2025. The code is open under the Apache 2.0 licence, according to the project's page on GitHub, so anyone may read and change it.

Gemini CLI no longer has a free tier. Since 18 June 2026 Gemini CLI has been built for organisations with Gemini Code Assist Standard or Enterprise and Code Assist for GitHub, according to the project description on GitHub. The tool also works with paid keys for the Gemini API. Gemini CLI is not tuned for Google's latest model series, which includes Argon, the same project description says.

Gemini Code Assist is being shut down. New customers cannot buy Gemini Code Assist Standard or Enterprise from 9 October 2026, according to Google Cloud's page on the sunset. Existing annual subscriptions can be renewed up to and including 31 January 2027, according to the same page. For coding agents, Google points there to Antigravity in Gemini Enterprise.

You install Gemini CLI with npm, and the tool needs Node.js 20.0.0 or later, according to the installation page. You put the key in GEMINI_API_KEY.

If you switch to Antigravity CLI, the agent still reads your GEMINI.md. The command agy plugin import gemini moves your extensions across. The MCP servers move from settings.json to mcp_config.json.

npm install -g @google/gemini-cli

Antigravity CLI, Claude Code or Codex?

Antigravity CLI, Claude Code and Codex are coding agents of the same kind. All three run in the terminal, read and change code, run commands and ask before they do anything risky. All three also read an instruction file in the project and can be connected to MCP servers.

The difference lies mostly in the company behind each and in the account you already have. Antigravity CLI uses Google's models and, according to Google's models page, also some models from other companies. Claude Code uses Anthropic's models and Codex uses OpenAI's. If you already have a plan with one of the companies, start with that company's agent.

Common questions about Antigravity CLI