
What is Antigravity CLI?
Antigravity CLI is Google's command-line tool, called with the agy command, that uses the same agents, accounts, and customizations as the Antigravity app but runs directly in your terminal: it has an interactive interface (TUI) for direct work and a print mode (headless) for calling agents from scripts, Git hooks, or CI. The general introduction is in the post What is Antigravity?; this post goes deep into antigravity cli. We don't claim the CLI replaces the desktop app and don't measure speed or accuracy; the flags and commands below are taken from the official documentation and agy --help version 1.4.12, read on 03/11/2026, where the documentation contradicts itself this is noted clearly. The post covers installation, print mode, conversation continuation, run mode, CI, migration from Gemini CLI, and AI credits.

From installation to running agents in scripts: the main layers of Antigravity CLI. Diagram: OPCAIOS.
How do I install Antigravity CLI?
I install Antigravity CLI using Google's automatic installation script, according to the Getting Started page in the Antigravity documentation (read on 03/11/2026). On macOS, Linux, and Googlebook, the installation command is a single curl line that downloads install.sh and then runs it with bash; on Windows there is a version for PowerShell (install.ps1) and for CMD (install.cmd). I check with agy --version; on the first run, the CLI asks if I trust the current directory. The installation script takes two flags: --skip-aliases to not touch old aliases in my shell profile and --skip-path to not automatically add PATH. Later, agy update updates the CLI, and agy install reconfigures PATH with the same two flags plus --dir. The /docs/install page is now the Authenticate page: the app, CLI, IDE utilities, and SDK share one login layer, so logging in in one place means I'm logged in everywhere on my machine.
curl -fsSL https://antigravity.google/cli/install.sh | bash
agy --version
What are the ways to log into Antigravity CLI?
Antigravity CLI has four authentication methods, according to the Authenticate page (read on 03/11/2026):
- Local keyring: The CLI looks for a session in the operating system's key store; if there isn't one, it opens a browser to log into my Google account.
- SSH: The CLI prints a URL, I open it on my machine, log in, then paste the confirmation code back into the remote terminal.
- Gemini API key: I set
modelProvidertogeminiin the CLI's settings.json and export theGEMINI_API_KEYvariable. Just setting the variable doesn't work, and the CLI doesn't read.envfiles. - Google Cloud ADC: for enterprises, enabled with
AGY_ADC_AUTH=true.
What are the main agy commands?
Antigravity CLI commands fall into three groups, according to the CLI reference page and agy --help (read on 03/11/2026):
| Group | Example | Used for |
|---|---|---|
| Subcommands | agy models, agy agents, agy mcp, agy plugin, agy update |
View models, agents, manage MCP, plugins |
| Startup flags | --model, --effort, --mode, --add-dir, --sandbox |
Configure a session |
| Slash commands | /plan, /goal, /rewind, /fork, /resume, /usage |
Control a running session |
Running agy opens the TUI in the current directory; in the TUI, @ suggests file paths, ! at the start of a line runs a terminal command, Shift+Tab switches mode. Long-term configuration lives in settings.json, opened with /config; startup flags only override for the current session.
How does the print (headless) mode of Antigravity CLI work?
Print mode, also called headless, is how to run Antigravity CLI non-interactively: send a request, get a result, then exit, according to the Headless mode page (read 03/11/2026). Call it with -p or --print, --prompt. The answer goes to stdout, while errors, permission notices, and progress go to stderr, so you can assign the result directly to a shell variable. The --output-format flag has three values: text (default), json (one object when done, containing conversation_id, status, response, duration_seconds, num_turns, and usage counting tokens), and stream-json (each line one event: one init, many step_update, one result). Headless uses the saved login session; in CI when not logged in, the command exits with an authentication error instead of hanging.
agy -p "In one sentence, what is a git rebase?" --output-format json | jq -r '.response'
When do you use --json-schema and --print-timeout?
--json-schema forces the answer to follow a JSON Schema, accepting a schema string, a .json file path, or a simple type name; the parsed result sits in structured_output. This is more reliable than telling the agent "return JSON" and then parsing the string yourself. --print-timeout sets a time limit, for example 15m. Note: agy --help and the CLI reference say the default is 0s (wait until done), but the Headless page says the default waits up to 5 minutes. Because the documentation contradicts, always set a value explicitly in scripts.
How do you continue a conversation in a script?
Continuing a conversation in Antigravity CLI uses two flags, because each headless run remembers nothing by default, according to the Headless mode page (read 03/11/2026). --continue (short form -c) reopens the most recent conversation, while --conversation <ID> opens the exact conversation with the ID taken from the conversation_id field of the previous run. According to the Managing conversations page, history is tied to the working directory: run agy from which directory and you only see sessions from that directory. Each --continue is a new process. When you need many turns in one process, use --input-format stream-json with --output-format stream-json: the script writes each JSON line with event: "user" to stdin, each line runs one turn and returns a result event; closing stdin ends it. The documentation says this way is faster than calling --continue repeatedly; we have not measured it.
How do --mode and --effort differ?
--mode decides how far the agent goes on its own, while --effort decides how deep the model reasons. According to the Choose an execution mode page (read 03/11/2026), there are four modes:
- default: show diff before editing files, ask before running commands.
- accept-edits: auto-review file edits in workspace, still ask before running commands.
- auto (Preview): auto-review file edits, run commands in sandbox, auto-evaluate commands outside sandbox; commands that cannot be reversed still ask. Needs terminal sandbox, available from 1.3.5 on macOS, Linux, and 1.4.4 on Windows, not yet for business accounts.
- plan: research and plan before writing code.
The allow, ask, deny rules in /permissions still take priority over mode. For --effort, agy --help lists low, medium, high, xhigh, max; the /effort page explains most models only have the first three levels. In headless, a wrong --model name makes the command exit with a different code instead of silently switching models.
What do you need to watch for running agy over SSH, Git hooks, and CI?
Running Antigravity CLI outside your personal machine needs to handle three things: login, permissions, and error handling. Over SSH use the URL flow and confirmation code; in CI there is no browser, use a Gemini API key or ADC. According to the Headless mode and CLI best practices pages (read 03/11/2026), you should:
- Use
--output-format jsonand checkstatuswithjq; onlySUCCESSis success. - Set
--print-timeoutexplicitly. - Allow only the commands you need with
permissions.allow, do not use--dangerously-skip-permissionson machines with real data. - Think about
--sandbox; from 1.4.4 on, this flag has no effect if the machine has no sandbox. - Pin
--modelso results do not change when the default model changes.
Example scenario: a Git hook calls agy -p to draft a commit message from the diff, and the user reads it again before committing. The best practices page has an example using the --cwd flag, but this flag does not appear in agy --help version 1.4.12. This approach is close to codex exec.
How to Switch from Gemini CLI to agy?
Switching from Gemini CLI to Antigravity CLI is mostly automatic on the first run, according to the Migrating from Gemini CLI page (read 03/11/2026): the CLI lists assets to choose from, transfers tokens into keyring, and maps settings display. These are things I need to check manually:
| Thing to migrate | Gemini CLI | Antigravity CLI |
|---|---|---|
| Extension | Extension | Plugin, via agy plugin import gemini |
| Project skill | .gemini/skills/ |
.agents/skills/ (rename folder yourself) |
| MCP config | In settings.json | Separate file mcp_config.json |
| Remote MCP server URL | url or httpUrl |
serverUrl |
| Rules file | GEMINI.md, AGENTS.md | Keep as is |
The documentation notes only partial compatibility. Details on MCP and plugin are in the post MCP and skill in Antigravity; for rules files, see What is AGENTS.md?.
How do AI credits work in the CLI?
AI credits are extra credit used when the plan limit runs out, according to the CLI AI credits page (read 03/11/2026). The status bar shows remaining credits; /credits opens the details table, /usage shows plan limit usage. The useG1Credits key, default false, decides whether the CLI uses credit when the plan limit runs out or not, and it doesn't exist for business accounts. We haven't read the credit pricing table so I'm not stating the price. For scheduled scripts, leaving this key off means the script stops when the limit runs out instead of silently spending credits.
OPCAIOS experience
On my main Mac, I installed CLI agy version 1.4.12 alongside Antigravity 2.28.x app, Antigravity IDE 2.5.x, Claude Code and Codex. In OPCAIOS's system, Antigravity is the orchestrating agent: it manages infrastructure, hands out and tracks work. The CLI config has an allowlist of about 20 items and a few trusted work folders, instead of browsing all; the CLI has one extra browser skill installed. General rules sit in AGENTS.md, while GEMINI.md at user level has only one line asking for Vietnamese answers. I haven't put agy -p into CI yet, haven't used Remote Control, and haven't measured productivity.
Frequently Asked Questions
Does Antigravity CLI require installing the Antigravity application?
The Getting Started page guides you through installing the CLI using a separate, standalone script, independent of the desktop application, and the Authenticate page describes a shared login layer for the application, CLI, IDE, and SDK. Some third-party posts mention needing to install the application first, but I don't see that requirement in the documentation I read on 03/11/2026. In CI, you can use a Gemini API key or ADC instead of account login.
In print mode, does the agent run shell commands on its own?
No, not by default. No one clicks browse in headless, so the browsing tool gets "soft-rejected": the run continues, exits with code 0, and prints a message to stderr naming the blocked tool. Reading and writing files in the workspace are allowed; shell commands only run when there's a permissions.allow rule in settings.json, like command(git). See more at safety mode in Antigravity.
Should I use --dangerously-skip-permissions?
Only in isolated environments you can throw away, like temporary containers or VMs, with code and requests you completely trust. This flag allows all commands, including file deletion and network calls. A safer approach is to add permissions.allow rules for the exact commands you need, combined with --sandbox. See security when using AI to write code to pick your risk level.
Can the Gemini CLI extension run on agy?
Most of it converts: agy plugin import gemini turns the old extension into a plugin, old commands into skills, and MCP servers into entries in mcp_config.json. The docs note only partial compatibility. After importing, run agy plugin list to see which components were recognized.
Where should I start learning Antigravity CLI in real workflows?
Start in default mode in a test folder, get comfortable browsing diffs and /rewind, then move to accept-edits or plan. Next, write a small agy -p script with --output-format json, check status, and set --print-timeout. Only expand permissions once you understand what the agent does. For guided learning on safely bringing the agent into your daily work, see AI application training from OPCAIOS.
Source: Google Antigravity documentation at antigravity.google/docs (getting-started, install, cli/reference, cli/using, cli/headless, cli/best-practices, cli/credits, cli/gcli-migration, cli/modes, cli/conversations, cli/commands/effort) and agy --help version 1.4.12 (read 03/11/2026); unverified: actual default for --print-timeout, speed of stream-json, AI credits pricing. Experience is from OPCAIOS.
Translated from Vietnamese with AI. Read the original.
Want to apply this in your business?
Book a free 30-minute call (Vietnam time, in English or Vietnamese).
