# Antigravity CLI (agy): running agents in terminal and scripts

URL: https://opcaios.org/en/blog/antigravity-cli-agy
Date: 2026-11-03
Author: Lê Quốc Nghĩa

# 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?](/blog/antigravity-la-gi); 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](/tien-ich/gemini) CLI, and AI credits.

![Diagram of Antigravity CLI: installation, login, TUI, print mode with JSON output, conversation continuation, run mode, permissions and sandbox, migration from Gemini CLI](https://opcaios.org/images/blog/antigravity-cli-agy/so-do.webp)
*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.

```bash
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):

1. **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.
2. **SSH:** The CLI prints a URL, I open it on my machine, log in, then paste the confirmation code back into the remote terminal.
3. **Gemini API key:** I set `modelProvider` to `gemini` in the CLI's settings.json and export the `GEMINI_API_KEY` variable. Just setting the variable doesn't work, and the CLI doesn't read `.env` files.
4. **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.

```bash
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:

1. **default:** show diff before editing files, ask before running commands.
2. **accept-edits:** auto-review file edits in workspace, still ask before running commands.
3. **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.
4. **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:

1. Use `--output-format json` and check `status` with `jq`; only `SUCCESS` is success.
2. Set `--print-timeout` explicitly.
3. Allow only the commands you need with `permissions.allow`, do not use `--dangerously-skip-permissions` on machines with real data.
4. Think about `--sandbox`; from 1.4.4 on, this flag has no effect if the machine has no sandbox.
5. Pin `--model` so 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](/blog/codex-exec-chay-tu-dong).

## 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](/blog/mcp-va-skill-trong-antigravity); for rules files, see [What is AGENTS.md?](/blog/agents-md-la-gi).

## 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](/tien-ich/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](/blog/che-do-an-toan-trong-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](/blog/bao-mat-khi-dung-ai-viet-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](/services/dao-tao-ung-dung-ai) from OPCAIOS.

*Source: [Google Antigravity](/tien-ich/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.*
