antigravity-cli

# Antigravity CLI (agy) Skill Targets `agy` v1.4.2. Use this skill to guide AI coding agents, automate CI/CD pipelines, orchestrate multi-agent swarms, configure Model Context Protocol (MCP) servers, manage custom Markdown agents, and control workspace environments with the `agy` CLI. ## Context: Gemini CLI Successor The `agy` CLI is Google's official replacement for Gemini CLI, announced at Google I/O on May 19, 2026. Gemini CLI ceased serving requests for consumer and free users on June 18, 2026. Enterprise users on Gemini Code Assist Standard/Enterprise retain Gemini CLI access indefinitely. Key architectural characteristics: - **Go binary** (not Node.js) — instant startup latency, zero npm dependencies, bundled embedded `ripgrep` engine. - **Unified agent platform** — shares the identical agent harness, runtime, and customization engine as the Antigravity IDE desktop application. - **Plugin system** — replaces legacy Gemini CLI extensions (`agy plugin import gemini` to migrate). - **High tool limit** — supports up to **512 tool calls** per turn on Gemini models for deep multi-step agentic execution. - **Binary identification** — `agy` (primary executable), `antigravity` (certain Linux distributions). Set the `ANTIGRAVITY_CLI_ALIAS` environment variable to override binary resolution. - **Default install path** — typically `~/.local/bin/agy`. ## Complete Command-Line Flag Reference ### Primary Command: `agy [flags] [prompt]` | Flag | Shorthand | Description | Added / Updated | | :--- | :--- | :--- | :--- | | `--print` | `-p`, `--prompt` | Runs a single prompt non-interactively and prints the response. | v1.0.0+ | | `--input-format <fmt>` | | Input format for print mode: `text` (default) or `stream-json`. `stream-json` reads NDJSON messages line-by-line from stdin for continuous multi-turn sessions. Requires `--output-format stream-json`. | v1.1.15+ | | `--output-format <fmt>` | | Output format for print mode: `text` (default), `json`, or `stream-json` (strongly-typed NDJSON event stream). | v1.1.8+ | | `--json-schema <schema>` | | Enforces a JSON schema on print mode output. Accepts an inline JSON schema string or a path to a schema file. Must have `"type": "object"` at the root; bare types fail at startup. | v1.1.8+, v1.2.14+ | | `--effort <level>` | | Reasoning effort for the session: `low`, `medium`, `high`, `xhigh`, `max`. | v1.1.5+, v1.2.11+ | | `--disable-slash-commands`| | Disables automatic expansion of leading slash commands and skills in headless print mode (`-p`). | v1.1.9+ | | `--prompt-interactive` | `-i` | Runs an initial prompt interactively in the TUI and continues the session. | v1.0.0+ | | `--continue` | `-c` | Continues the most recent conversation in the current workspace (with parent/child directory fallback). | v1.0.0+, v1.2.1+ | | `--conversation <id>` | | Resumes a specific conversation by its unique ID. | v1.0.0+ | | `--dangerously-skip-permissions` | | **CRITICAL FOR AUTOMATION.** Auto-approves all tool permission requests without interactive prompts. Since v1.3.2 it no longer auto-approves implementation plans in `/plan` mode; use `Artifact Review` in `/config` for that. | v1.0.0+, v1.3.2+ | | `--sandbox` | | Runs terminal operations in a secure restricted sandbox. | v1.0.1+ | | `--agent <agent>` | | Specifies a custom agent (Markdown or built-in) for the current CLI session. An unknown name makes headless `-p` runs exit `1` and list available agents; interactive sessions show an `Agent Not Found` warning and fall back to the default agent. | v1.1.1+, v1.2.11+, v1.3.4+ | | `--model <model>` | | Model slug or identifier for the current CLI session. A base model name works without `--effort` (the CLI picks the model's default thinking level). | v1.0.5+, v1.1.22+, v1.3.4+ | | `--mode <mode>` | | Sets agent execution mode: `default` (request review), `accept-edits`, `auto` (approves edits and safe commands, still prompts before irreversible actions), or `plan`. | v1.1.0+, v1.3.5+ | | `--print-timeout <dur>` | | Timeout for print mode. **Default is `0s` (unlimited)** — runs until the turn completes. When set, a mid-turn expiration returns partial output and exits 0 with a stderr warning. | v1.1.28+, v1.2.6+ | | `--add-dir <path>` | | Adds a directory to the workspace scope (repeatable). | v1.0.0+ | | `--project <id\|name>` | | Explicitly sets the project ID or project name for the session. | v1.0.12+, v1.1.18+ | | `--new-project` | | Creates a new isolated project context for the session. | v1.0.12+ | | `--remote-control` | | Initiates a session-scoped remote connection on startup for remote following/control. | v1.2.6+ | | `--log-file <path>` | | Overrides the CLI log file path. | v1.0.0+ | ## Complete Subcommands Reference ### 1. `agy mcp` (Model Context Protocol Management) Added in `v1.1.16+`. Manage user-level `~/.gemini/config/mcp_config.json` directly from the CLI without manual JSON editing: ```bash # List all configured MCP servers and their status agy mcp list # Add or update a stdio-based MCP server agy mcp add fs npx -y @modelcontextprotocol/server-filesystem /path/to/work # Add an stdio server with environment variables (repeatable -e) agy mcp add --env GITHUB_TOKEN=ghp_xxx gh -- docker run -i ghcr.io/github/mcp # Add an HTTP/SSE server with custom headers (repeatable -H) agy mcp add --header "Authorization: Bearer sso_token" remote-api https://mcp.internal.net/sse # Toggle server enablement agy mcp disable remote-api agy mcp enable remote-api # Remove a server configuration agy mcp remove fs ``` *Notes:* - URLs starting with `http://` or `https://` automatically infer `--type http`. - Use `--` before the command if any argument begins with a dash `-`. - Plugin MCP servers are automatically namespaced as `<plugin>_<server>` to prevent name collisions (`v1.2.2+`). - MCP servers can mark a tool as always loaded by setting `_meta: {"antigravity/alwaysLoad": true}` on it in their `tools/list` response, so the agent gets it directly instead of discovering it on demand (`v1.3.3+`). - Plugin MCP servers can use variables in request headers (e.g. `"Authorization": "Bearer ${TOKEN}"`); they are resolved to your configured values (`v1.4.0+`). - If an MCP server process exits unexpectedly, `/mcp` marks it `Error` instead of `Ready` (`v1.4.1+`). ### 2. `agy remote-control` (Remote Daemon Management) Added in `v1.2.0+` and `v1.2.6+`. Manages the background Remote Control service registered with your operating system's service manager (systemd, launchd, or background process): ```bash # Register and start the background daemon agy remote-control start # Start with a custom machine name and session scope agy remote-control start --name "devbox-chicago" --session # Inspect running daemon status, active tunnel, and PID agy remote-control status # Stop and unregister the background service agy remote-control stop ``` *Inside interactive TUI:* - Run `/remote-control` to open a session-scoped tunnel. - Run `/remote-control off` to tear down the active tunnel. ### 3. `agy mic-serve` (Audio Dictation Forwarding) Added in `v1.1.21+`. Forwards a local machine's microphone to an `agy` CLI session running on a remote host (e.g. over SSH) for terminal speech dictation (`/voice` or `F5`): ```bash # Run on local client machine agy mic-serve --addr 127.0.0.1:4713 ``` ### 4. `agy agent` / `agy agents` List and inspect available custom and built-in agents. ```bash # Human-readable list agy agent # Machine-readable list (agy agent rejects --output-format) agy -p "/agents" --output-format json ``` ### 5. `agy models` List available models for the current sign-in credential or API key. ```bash # Human-readable list agy models # Plain list (agy models rejects --output-format) agy models ``` ### 6. `agy plugin` / `agy plugins` Manage agent plugins (stored in `~/.gemini/config/plugins/`): ```bash # List installed plugins (marketplace and imported) with version and enabled state agy plugin list agy plugin list --json # Install from the official marketplace, another marketplace, or GitHub repo subpaths with branch resolution agy plugin install <plugin-name>@antigravity-plugins-official agy plugin install security-auditor@marketplace agy plugin install github.com/owner/repo/plugins/analyzer@main # Migrate legacy Gemini CLI extensions or Claude extensions agy plugin import gemini agy plugin import claude # Enable or disable plugins (enablement state persists in config.json) agy plugin enable <name> agy plugin disable <name> # Validate a plugin directory or its plugin.json agy plugin validate ./my-plugin # CI-friendly: fail on warnings and emit a machine-readable report agy plugin validate ./my-plugin --strict --json ``` *Notes:* - `agy plugin list --json` added in `v1.3.4+`; it lists every installed plugin, not only imported ones. - `agy plugin validate` (`v1.4.0+`, expanded in `v1.4.1+`) checks a plugin with the same rules the CLI uses to load it, including its `plugin.json` (unknown fields with "did you mean" hints, invalid names, components misplaced inside `.antigravity-plugin/`), skills, subagents, and rules. Each error and warning is reported with its file and line. - Inside the TUI, `/plugin` (`v1.3.2+`) opens the interactive manager for the official marketplace (browse, install, `install`/`uninstall`/`enable`/`disable`/`list`, or `+ Install from local directory...`). Plugin names and manifests are case-insensitive (`v1.3.6+`). ### 7. `agy install` Configures environment paths and shell configuration profiles (`.zshrc`, `.bashrc`): ```bash agy install agy install --dir /usr/local/bin agy install --skip-path agy install --skip-aliases ``` ### 8. `agy update` & `agy changelog` ```bash # Update the CLI binary to the latest release agy update # View changelog and release notes (also supported via agy -p "/changelog") agy changelog ``` ## Agentic Automation & Headless Scripting (`-p`) ### 1. Headless Slash-Command & Skill Expansion As of `v1.1.9+`, headless print mode (`-p`) automatically expands slash commands and installed skills rather than treating them as literal text: ```bash # Headless run that triggers the code-review skill agy -p "/jbd-code-review-skill review the uncommitted diff" --dangerously-skip-permissions ``` To opt out and send leading slashes as literal text, pass `--disable-slash-commands`. ### 2. Zero-Turn Read-Only Command Queries As of `v1.1.11+` and `v1.1.12+`, running read-only slash commands in print mode emits machine-readable data **without starting an agent turn, without consuming model quota, and without writing database records**: ```bash # Check remaining quota in JSON format agy -p "/quota" --output-format json # Inspect token usage and costs agy -p "/usage" --output-format json # Check G1 credits balance agy -p "/credits" --output-format json # Export active permissions or installed skills agy -p "/permissions" --output-format json agy -p "/skills" --output-format json ``` Interactive-only commands (such as `/clear`) fail fast with a descriptive error rather than faking execution. ### 3. Bidirectional Continuous Streaming (`--input-format stream-json`) As of `v1.1.15+`, scripts and test harnesses can maintain a persistent, multi-turn conversation over stdin/stdout using line-delimited NDJSON: ```bash # Launch persistent streaming runner agy -p --input-format stream-json --output-format stream-json --dangerously-skip-permissions ``` **Input protocol (one JSON object per line on stdin):** ```json {"prompt": "Analyze main.go for performance bottlenecks"} {"prompt": "Generate a patch fixing the memory allocation in WorkerPool"} ``` **Output protocol (one envelope per line: `{"event": "<name>", "<name>": {payload}}`):** - `init`: session metadata (cwd, permission mode, tools). - `step_update`: `state` (`ACTIVE`/`DONE`), `step_type`, incremental `text_delta`, `tool_info` (tool name, args, output), and `subagent_info` (`conversation_id`, `log_uri`). - `result`: final answer, status, and token accounting (`input_tokens`, `output_tokens`, `thinking_tokens`, `cache_read_tokens`). ### 4. Enforcing Structured Output Schema (`--json-schema`) Use `--json-schema` to guarantee that the final response conforms to a JSON schema: ```bash agy -p "Extract all exported functions in auth.go" \ --output-format stream-json \ --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \ --dangerously-skip-permissions ``` *Validation rule (`v1.2.14+`):* The root schema **must** have `"type": "object"`. Plain text or bare types (`string`) immediately terminate execution with exit code `1`. ### 5. Exit Codes & Structured Error Reporting The `agy` CLI uses distinct exit codes to simplify automation error handling: - **`0`**: Success, or graceful partial completion when `--print-timeout` expires. - **`1`**: Startup configuration errors, invalid command flags, malformed `--json-schema`, or an unknown `--agent` name in `-p` mode (`v1.3.4+`). - **`2`**: Print-mode usage errors, such as combining `--print` with `--prompt-interactive` (`v1.3.4+`).