# Antigravity CLI: a practical guide to Google’s agy

URL: https://agentvera.dev/en/blog/how-to-use-antigravity-cli/ · Published: 2026-11-05

Antigravity CLI guide: install agy, sign in, write AGENTS.md, pick models and effort, set modes and permissions, add MCP servers and move over from Gemini CLI.

**In short:**

- Antigravity CLI (agy) is Google’s terminal agent that replaced Gemini CLI for Google AI Pro, Ultra and free individual users on June 18, 2026.
- Install it with one script, run agy in a project, sign in with your Google account, and keep project rules in AGENTS.md or GEMINI.md, which it reads unchanged.
- MCP servers move from settings.json to mcp_config.json, extensions become plugins with agy plugin import gemini, and --mode replaces --approval-mode.

Antigravity CLI is Google’s coding agent for the terminal. You install it with one script, start it with `agy` inside a project, sign in with your Google account and describe the task. It reads your files, proposes edits and commands, and in its default mode asks before it changes anything.

If you used Gemini CLI on a personal account, this is where you ended up. Google’s [developer blog post of May 19, 2026](https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/ "Transitioning Gemini CLI to Antigravity CLI") announced that Gemini CLI would stop serving Google AI Pro and Ultra subscribers and free users of Gemini Code Assist for individuals on **June 18, 2026**. This guide covers install, sign-in, project instructions, models and effort, modes and permissions, MCP, key commands, the migration from Gemini CLI and the limits Google states. Everything here comes from [Google’s Antigravity documentation](https://antigravity.google/docs/getting-started?tab=cli "Antigravity quickstart") as of November 2026.

## What Antigravity CLI is and who it’s for

Antigravity CLI is the terminal client of Google Antigravity, Google’s agent-first development platform. According to Google it is written in Go and shares its agent harness with the Antigravity 2.0 desktop app, so improvements to the agent land in both. It keeps the building blocks Gemini CLI users know: agent skills, hooks, subagents and extensions, which are now called plugins.

It’s for you if you:

- used Gemini CLI with a personal Google account, Google AI Pro or Ultra;
- want a [coding agent](/en/glossary/coding-agent/ "What is a coding agent") in the terminal that runs Gemini models (and, depending on your plan, others);
- already use Antigravity on the desktop and want the same agent over SSH or in scripts.

Teams with a Gemini Code Assist Standard or Enterprise license, or a paid Gemini API key, can stay on Gemini CLI. Our [Gemini CLI guide](/en/blog/how-to-use-gemini-cli/ "How to use Gemini CLI") covers that path. Google is open about the gap: the blog post says there won’t be 1:1 feature parity right away.

## Install

| System | Command |
| --- | --- |
| macOS, Linux | `curl -fsSL https://antigravity.google/cli/install.sh \| bash` |
| Windows (PowerShell) | `irm https://antigravity.google/cli/install.ps1 \| iex` |
| Windows (CMD) | `curl -fsSL https://antigravity.google/cli/install.cmd -o install.cmd && install.cmd && del install.cmd` |

On macOS and Linux the binary lands in `~/.local/bin/agy`; on Windows in `AppData\Local\agy\bin`. Check it:

```bash
agy --version
```

## Sign in

Move into a project and start it:

```bash
cd my-project
agy
```

The first run asks for a color scheme, a rendering mode (Alt-Screen or Inline) and whether you trust the folder. Then it opens the browser so you can sign in with your Google account. Personal accounts on the Free, Pro and Ultra plans work; business accounts sign in through Gemini Enterprise. The token is stored in your OS keyring (Keychain, Secret Service or Windows Credential Manager), so later launches skip the browser.

Other options:

- **Over SSH:** `agy` prints a URL. Open it on your own machine, sign in and paste the code back into the terminal.
- **Gemini API key:** set `"modelProvider": "gemini"` in `~/.gemini/antigravity-cli/settings.json` and export `GEMINI_API_KEY`. The key alone does nothing without that setting.
- **Google Cloud credentials:** run `gcloud auth application-default login` and set `AGY_ADC_AUTH=true`.

`/logout` clears the saved sign-in.

## Your first task

```text
Explain how the payment module is structured, then add input validation
to the refund endpoint and run the tests.
```

A few shortcuts from day one: `@` suggests file paths, `!` at the start of a prompt runs a shell command, and `?` shows help with the slash commands. For scripts, `agy -p "summarize README.md"` runs one prompt headless and prints the answer; add `--output-format json` when another program reads it. `agy -i "prompt"` starts the interactive UI with a first prompt.

## Project instructions: AGENTS.md or GEMINI.md

Antigravity reads `AGENTS.md` or `GEMINI.md` in the folder where you start `agy` and in its parents up to the repo root. Both are always active and need no frontmatter. Global rules go in `~/.gemini/AGENTS.md` or `~/.gemini/GEMINI.md`. Rules add up rather than replace each other.

```markdown
# Project: billing-service

## Commands
- Install: npm ci
- Test: npm test (run before you say a task is done)

## Don't
- Don't edit files in src/generated.
```

For finer control, put Markdown files in `.agents/rules/`. Each needs frontmatter with a `trigger`: `always_on`, `model_decision`, `glob` (applies when the agent touches matching files) or `manual`. A missing or invalid trigger means the rule is silently dropped, and the CLI doesn’t support `manual` rules because it has no rule mentions. Keep files short: each is cut off after 24,000 bytes, and global plus `always_on` rules share a 20,000-token budget.

If Codex or another agent already reads your `AGENTS.md`, Antigravity picks up the same file. [CLAUDE.md vs AGENTS.md](/en/blog/claude-md-agents-md/ "CLAUDE.md and AGENTS.md") explains how to share one set of rules with Claude Code.

## Models and effort

Pick a model per run with `--model` (`agy models` lists them) or in a session with `/model`. Google’s models page lists Gemini models such as Gemini 3.8 Flash and Gemini 3.1 Pro next to Claude and GPT-OSS models; which ones you see depends on your plan.

Effort sets how hard the model thinks. `/effort` opens a gauge and saves your choice as the default; `--effort low` applies to one run only. The levels are `low`, `medium`, `high`, `xhigh` and `max`, but most models offer only low to high, and models with a fixed budget ignore it.

## Modes and permissions

| Mode | What happens |
| --- | --- |
| `default` | Shows a diff before creating or changing files and asks before terminal commands |
| `accept-edits` | Approves edits inside the workspace, still asks before commands |
| `auto` | Approves edits and runs commands in the terminal sandbox; risky actions still ask |
| `plan` | Analyzes and outlines steps before writing code |

Start with `--mode=accept-edits` (or `auto`, `plan`), cycle with Shift+Tab, or set `"agentMode"` in `~/.gemini/antigravity-cli/settings.json`. `auto` needs the sandbox and a personal account (v1.3.5+ on macOS and Linux, v1.4.4+ on Windows); business accounts don’t get it. `--sandbox` runs a session in the terminal sandbox.

Fine-grained rules live in the same settings file as `allow`, `ask` and `deny` lists, for example `command(git)` or `mcp(sql/execute_mutation)`. Deny beats ask, ask beats allow. `/permissions` edits them in the UI. `--dangerously-skip-permissions` approves everything; use it only in a throwaway environment. [AI coding agent security](/en/blog/ai-coding-agent-security/ "AI coding agent security") explains why.

## MCP servers

[MCP](/en/glossary/mcp/ "What is MCP") servers live in their own file: `~/.gemini/config/mcp_config.json` for every project, `.agents/mcp_config.json` for one workspace.

```json
{
  "mcpServers": {
    "local-db": { "command": "node", "args": ["/path/to/server.js"] },
    "docs": { "serverUrl": "https://api.example.com/mcp/", "headers": { "Authorization": "Bearer TOKEN" } }
  }
}
```

Remote servers must use Streamable HTTP; the old HTTP+SSE transport and `httpUrl` aren’t supported. `/mcp` opens a manager with status, reload and logs. Tools you haven’t allowed run in Ask mode.

## Commands worth knowing

| Command | What it does |
| --- | --- |
| `/model`, `/effort` | Change model and reasoning effort |
| `/permissions` | Manage allow, ask and deny rules |
| `/config` or `/settings` | Open the settings overlay |
| `/mcp` | MCP server manager |
| `/plan` | Research, ask questions, draft a reviewable plan |
| `/resume` | Pick an earlier conversation from this folder |
| `/rewind`, `/undo` | Go back in the conversation |
| `/fork`, `/clear` | Branch the conversation or start fresh |
| `/usage`, `/credits` | Model quotas and AI credits |
| `/plugin` | Install, enable or list plugins |

From the shell, `agy -c` continues the latest conversation in this folder and `--conversation <id>` resumes a specific one. `--add-dir` adds another folder to the workspace.

## Moving from Gemini CLI

The first time you run `agy` on a machine with Gemini CLI config, a checklist asks what to migrate: extensions, global configuration, session tokens and display settings. What carries over and what doesn’t, per Google’s [migration guide](https://antigravity.google/docs/cli/gcli-migration "Gemini CLI migration"):

- **Unchanged:** `GEMINI.md` and `AGENTS.md` in the project, `~/.gemini/GEMINI.md`, and global skills in `~/.gemini/skills/`.
- **Converted:** extensions become plugins with `agy plugin import gemini`, which turns their commands into skills.
- **Move by hand:** workspace skills from `.gemini/skills/` to `.agents/skills/`; MCP servers out of `~/.gemini/settings.json` into `mcp_config.json`, with `url` or `httpUrl` renamed to `serverUrl`.
- **Not guaranteed:** some custom themes and visual overlays.
- **Flags:** `--approval-mode` is gone; use `--mode`. There is no yolo mode.

## Limits and pricing

Google’s [plans page](https://antigravity.google/docs/plans "Antigravity plans") includes the CLI in every plan and describes quotas without numbers: Ultra has the highest quota, refreshed every five hours; Pro has a high quota refreshed every five hours until a weekly limit; other plans get a quota refreshed weekly. Limits follow how much work the agent does. On Pro and Ultra, AI credits can cover usage past the quota at Gemini Enterprise consumption pricing, and an overage setting lets you turn that off. `/usage` and `/credits` show where you stand.

## Running it next to Claude Code and Codex

Antigravity is often one of several agents. A few habits keep that sane:

- **One shared rules file.** Antigravity and Codex both read `AGENTS.md`; Claude Code reads `CLAUDE.md`, which can point to it.
- **One worktree per agent.** Give each agent its own [git worktree](/en/blog/git-worktree-parallel-agents/ "Git worktrees for parallel agents") so they don’t edit the same files.
- **Same MCP servers everywhere.** Each tool keeps its own config file, so the same server has to be added three times.

We build AgentVera, a desktop app for macOS, Windows and Linux that runs Antigravity CLI next to Claude Code, Codex, Gemini CLI and other agents, each in a real terminal with your own install and sign-in. For Antigravity specifically ([details](/en/agents/antigravity/ "Antigravity in AgentVera")):

- **[Workspace](/en/features/workspace/ "Workspace"):** Antigravity is one tile in a grid of agents per project and returns to its conversation after a relaunch.
- **Permissions:** Ask, Auto (`--mode=accept-edits`) or Full access (`--dangerously-skip-permissions`) per agent.
- **Model and effort:** set a model and low, medium or high effort when you create the agent.
- **Instructions:** agy has no flag for extra instructions, so keep rules in `AGENTS.md` or `GEMINI.md`.
- **[MCP manager](/en/features/mcp-manager/ "MCP manager"):** servers you set up once are added to Antigravity at launch, next to your own `mcp_config.json`.
- **Worktrees:** create one from the [Git panel](/en/features/git-and-github/ "Git and GitHub") and start Antigravity in it, with Claude Code in another.

The grid, worktrees, code review and the MCP manager are on the free plan. For how Google’s agents compare with Anthropic’s, read [Gemini CLI vs Claude Code](/en/blog/gemini-cli-vs-claude-code/ "Gemini CLI vs Claude Code"), or [download AgentVera](/en/download/ "Download AgentVera").

## Wrapping up

Install with the script, run `agy`, sign in with Google, and keep your existing `AGENTS.md` or `GEMINI.md`. Move MCP servers to `mcp_config.json`, import extensions with `agy plugin import gemini`, start in `default` or `accept-edits` mode, and check `/usage` before long sessions.

## Frequently asked questions

**Is Antigravity CLI free?** You can sign in with a personal Google account on the Free, Pro or Ultra plan. Google’s plans page says other plans get a quota refreshed weekly, while Pro and Ultra get larger quotas refreshed every five hours. Google publishes no exact numbers.

**Does Antigravity CLI read my GEMINI.md?** Yes. It reads AGENTS.md and GEMINI.md in the folder where you start agy and in parent folders up to the repo root, plus global files such as ~/.gemini/GEMINI.md. No changes are needed when you move from Gemini CLI.

**Where do MCP servers go in Antigravity CLI?** In a separate mcp_config.json: ~/.gemini/config/mcp_config.json for all projects or .agents/mcp_config.json for one workspace. Remote servers use serverUrl and must speak Streamable HTTP.

**What replaced --approval-mode and yolo?** The --mode flag, with default, accept-edits, auto and plan. Shift+Tab cycles the modes in a session. To skip every permission prompt there is --dangerously-skip-permissions, which is only sensible in an isolated environment.

**Can I keep using Gemini CLI instead?** Yes, if you have a Gemini Code Assist Standard or Enterprise license or a paid Gemini API key. Google AI Pro, Ultra and free individual users were moved to Antigravity CLI on June 18, 2026.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/