Get started with Antigravity CLI: install it and make your first change

Antigravity CLI is Google's terminal agent. You describe a change in plain English, and it reads your project, proposes edits and runs commands with your permission. You start it with the command agy. This recipe takes you from install to a first small edit.

Where it fits

Google's Developers Blog says Gemini CLI stopped serving Google AI Pro, Google AI Ultra and free individual users on 18 June 2026, and that those tiers are now supported through Antigravity CLI. Gemini CLI is still available to people who use it through a Gemini Code Assist Standard or Enterprise licence, Google Cloud, or a paid Gemini API key. If you came here from the old Gemini CLI, see our Gemini CLI guide and the tool page for the differences.

Before you start

• A computer with a terminal (macOS, Linux or Windows).
• A Google account to sign in with.
• A practice folder you don't mind changing.

Plans and limits change. Google's pricing page lists a free Individuals plan with basic weekly rate limits, and paid Google AI Pro and Ultra plans with larger ones. We don't quote numbers here because Google's docs don't either.

Step 1: Install it

On macOS or Linux, Google's docs give this one-line installer:

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

On Windows, open PowerShell and run:

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

Piping a script from the internet straight into your shell is a common install pattern, but it does run whatever the script says. If you'd like to look first, open the address in your browser before you run it.

Then check it worked:

agy --version

Step 2: Make a practice project

mkdir agy-demo
cd agy-demo
echo "<h1>Hello</h1>" > index.html

Always start the agent from the folder you want it to work in.

Step 3: Start it and sign in

agy

On first launch you'll pick a colour scheme and a display mode, and confirm that you trust the folder. If there's no saved login, Google's docs say it opens your browser for Google Sign-In. On a remote or SSH machine it prints a web address to finish the login on your own computer instead.

If you use Google Cloud for work, the docs describe a business sign-in with Google Cloud. A Gemini API key is also supported, but it takes an extra setting. Setting GEMINI_API_KEY alone has no effect, so follow Google's install and sign-in docs.

Keep any API key private. Never paste it into a chat, commit it to Git or share a screenshot of it.

Step 4: Ask a question first

Start with something that only reads:

What files are in this project and what does index.html do?

Step 5: Make your first change

Turn index.html into a simple page with a title, a short paragraph about my favourite hobby and some basic styling. Keep it in one file.

By default the CLI shows the proposed edit as a diff and asks you to accept or reject it. Read it before you press accept. Then open index.html in your browser and ask for tweaks:

Make the heading blue and centre everything.

If you'd like it to lay out a plan before touching any files, try /plan followed by your task. Pressing Shift+Tab cycles through the working modes, which include one that outlines steps before editing.

Step 6: Handy commands

Anything starting with / is a command. A few from Google's command reference:

/rewind rolls back the conversation. Don't treat it as a full undo for your files. Use Git for that (see our git safety net guide).

Step 7: Give it standing instructions

The CLI reads project instructions from a plain Markdown file called AGENTS.md or GEMINI.md in your project folder (and parent folders up to the repository root). A short example:

# My project
- Use British English in visible text.
- Keep CSS in one file.
- Ask before adding new dependencies.

Because it reads AGENTS.md, one file can be shared with other tools. Our AGENTS.md guide explains how.

Step 8: Run one prompt from a script

For automation, the docs describe a non-interactive mode:

agy -p "Summarise what this project does in three bullet points"

It uses the login you already saved, so sign in once with an interactive agy session first. Tools that would need approval are not run in this mode unless you have allowed them in your settings.

Moving over from Gemini CLI

Google's migration guide says the basics carry across:

• Instructions. Your GEMINI.md and AGENTS.md files are still read, so nothing needs changing.
• Extensions. Run agy plugin import gemini to convert Gemini CLI extensions into Antigravity plugins.
• MCP servers. These are set up by hand. They now live in ~/.gemini/config/mcp_config.json (for all projects) or .agents/mcp_config.json (for one project), not in the old settings.json. A remote server's address goes in a field called serverUrl.
• Skills. Global skills in ~/.gemini/skills/ still work. Skills inside a project's .gemini/skills/ need moving to .agents/skills/.

Google also says there isn't one-to-one feature parity with Gemini CLI yet, and that some custom themes may not carry over.

Safety habits

• Commit before big changes so you can undo.
• Read before approving anything that deletes files or installs software.
• Be careful with auto-approve options. The docs describe modes and a --dangerously-skip-permissions flag that stop the prompts. Keep them for throwaway projects.
• Keep secrets out of prompts and files.
• Know the data terms. The README says that by using the CLI you agree to let Google collect and use your Interactions data, and that you can opt out in your settings.

Troubleshooting

"command not found: agy". Open a new terminal window so your path refreshes. The installer puts the program in ~/.local/bin on macOS and Linux.

Sign-in doesn't open a browser. On a remote machine it prints a web address. Open that on your own computer.

A missing Gemini CLI feature. Check Google's migration guide. Some things work differently, and Gemini CLI remains available through some licences and API keys.

Where to go next

• Read our Antigravity CLI tool page for a quick summary.
• Compare it with Gemini CLI or Claude Code.
• Learn what an MCP server is.