--- title: Antigravity CLI (agy) date: 2026-09-22 12:00:00 background: bg-[#1a73e8] tags: - agy - antigravity - ai - cli - google - coding - agent categories: - AI intro: | [Antigravity CLI (agy)](https://antigravity.google/docs/cli) is Google's AI-first terminal development assistant and agentic coding CLI. It reads codebases, executes edits, manages background tasks, orchestrates subagents, and automates developer workflows. plugins: - copyCode --- ## Getting Started {.cols-3} ### Quick Start {.row-span-2} ```bash # Launch interactive session in current repository $ agy # Resume most recent session $ agy -c $ agy --continue # Resume a specific session by conversation ID $ agy --conversation # Run non-interactive prompt and print output $ agy -p "explain the architecture of this repo" $ agy --print "fix lint errors across src/" # Run prompt and continue interactively $ agy -i "refactor auth middleware" $ agy --prompt-interactive "add unit tests" # Pipe stdin directly to agy $ git diff | agy -p "write a git commit message" $ cat logs.txt | agy -p "identify crash trace" # Multi-directory workspace $ agy --add-dir ../backend --add-dir ../frontend ``` ### Authentication | Method | Description | | --- | --- | | **Google Account** | Run `agy`, follow browser login prompts on first run | | **Vertex AI (ADC)** | `gcloud auth application-default login` | | **Service Account** | Set `GOOGLE_APPLICATION_CREDENTIALS=/path/to/sa.json` | | **Project Selection** | `agy --project ` or `GOOGLE_CLOUD_PROJECT` | ### Installation Methods ```bash # Verify installation $ agy --help # Configure environment PATH and shell settings $ agy install # Update CLI to latest release $ agy update # View release notes & changelog $ agy changelog ``` ### Execution Modes | Mode | Command Flag | Description | | --- | --- | --- | | **Default** | *(default)* | Prompts for confirmation before modifying files or running commands | | **Accept Edits** | `--mode accept-edits` | Automatically applies edits and writes files without prompting | | **Plan Mode** | `--mode plan` | Formulates step-by-step implementation plans before touching code | | **Sandbox** | `--sandbox` | Restricts shell execution inside an isolated terminal sandbox | | **Unrestricted** | `--dangerously-skip-permissions` | Auto-approves all tool permission prompts | ### Key Concepts - **Agentic Loop**: Dynamically inspects files, runs shell commands, views diffs, and self-corrects based on tool results. - **Progressive Disclosure**: Skills and contextual rules are loaded on demand rather than cluttering token context. - **Asynchronous Tasks**: Background commands and multi-agent runs execute concurrently without blocking turns. --- ## CLI Options {.cols-2} ### Core Flags {.row-span-2} | Flag | Short | Description | | --- | --- | --- | | `--print ` | `-p` | Run prompt non-interactively and print response | | `--prompt-interactive ` | `-i` | Run initial prompt and remain interactive | | `--continue` | `-c` | Resume the most recent conversation | | `--conversation ` | | Resume specific conversation by ID | | `--model ` | | Specify model for the session | | `--effort ` | | Set reasoning effort (`low`, `medium`, `high`) | | `--mode ` | | Agent mode (`accept-edits`, `plan`) | | `--sandbox` | | Enable terminal sandbox restrictions | | `--dangerously-skip-permissions` | | Auto-approve all tool permissions | | `--add-dir ` | | Add directory to workspace (repeatable) | | `--project ` | | Google Cloud / Vertex project ID | | `--new-project` | | Create a new project for this session | | `--output-format ` | | Output format (`text`, `json`, `stream-json`) | | `--input-format ` | | Input format (`text`, `stream-json`) | | `--json-schema ` | | Enforce structured JSON schema for outputs | | `--print-timeout ` | | Timeout limit for print mode (default `0s`) | | `--log-file ` | | Override CLI log file path | | `--remote-control` | | Connect to remote control background daemon | | `--disable-slash-commands` | | Disable slash command expansion in print mode | ### Subcommands ```bash # Manage MCP servers $ agy mcp [list|add|remove|enable|disable] # Manage plugins $ agy plugin [list|install|uninstall|enable|disable|import|validate] # List supported AI models $ agy models # List available agents $ agy agents # Manage remote control background daemon $ agy remote-control [start|status|stop] # Serve microphone input to a CLI on another host $ agy mic-serve # Update agy CLI $ agy update ``` ### Headless & CI/CD Formats ```bash # Plain text output $ agy -p "check repo for vulnerabilities" --output-format text # JSON output for tooling pipelines $ agy -p "extract exported API endpoints" --output-format json # NDJSON streaming for real-time consumers $ agy -p "generate OpenAPI spec" --output-format stream-json # Enforce structured output via JSON Schema $ agy -p "list todos" --json-schema schema.json --output-format json ``` --- ## Model Selection & Reasoning {.cols-2} ### Models & Reasoning Effort {.row-span-2} ```bash # Check all available models $ agy models # Run with Gemini 3.8 Flash with high reasoning (fast & deep) $ agy --model gemini-3.8-flash-high # Run with Gemini 3.1 Pro for complex architectures $ agy --model gemini-3.1-pro-high # Run with Claude Sonnet 4.6 (Thinking) $ agy --model claude-sonnet-4-6 # Specify reasoning effort level $ agy --effort high $ agy --effort medium $ agy --effort low ``` ### Model Reference | Model Identifier | Display Name | Recommended Use | | --- | --- | --- | | `gemini-3.8-flash-high` | Gemini 3.8 Flash (High) | Daily coding, rapid agent turns, default | | `gemini-3.8-flash-medium` | Gemini 3.8 Flash (Medium) | Balanced speed and thinking tokens | | `gemini-3.8-flash-low` | Gemini 3.8 Flash (Low) | Fastest latency, lightweight queries | | `gemini-3.7-flash-high` | Gemini 3.7 Flash (High) | Previous generation high reasoning | | `gemini-3.1-pro-high` | Gemini 3.1 Pro (High) | Massive refactors, cross-repo design | | `claude-sonnet-4-6` | Claude Sonnet 4.6 | Thinking-enabled coding assistant | | `claude-opus-4-6-thinking` | Claude Opus 4.6 | Deep complex multi-step reasoning | | `gpt-oss-120b-medium` | GPT-OSS 120B | Open-weights reasoning tier | --- ## Interactive Slash Commands {.cols-3} ### Slash Commands `/` {.row-span-3} | Slash Command | Purpose | | --- | --- | | `/help` | Show available slash commands and keybindings | | `/plan` | Formulate a multi-step design & plan before execution | | `/goal` | Autonomous mode: runs until goal is completed | | `/boost` | Deep thinking, multi-angle exploration, rigorous checks | | `/browser` | Web automation, page inspection, and live testing | | `/grill-me` | Interactive interview to settle design decisions | | `/schedule` | Set a one-off timer or recurring cron schedule | | `/teamwork-preview` | Autonomous multi-agent collaboration | | `/learn` | Persist developer preferences and lessons | | `/exit` | Exit the CLI session | | `/quit` | Alias for `/exit` | ### Goal & Boost Modes ```bash # Inside interactive agy: > /goal Implement end-to-end tests for billing API and verify they pass # Boost mode for mission-critical changes: > /boost Review security implications of session token rotation ``` ### Interactive Interviews ```bash # Challenge your assumptions before writing code > /grill-me I want to migrate our database from MongoDB to Postgres ``` --- ## Keyboard Shortcuts {.cols-3} ### General Controls {.row-span-2} | Keybinding | Action | | --- | --- | | `Ctrl+D Ctrl+D` | Exit agy CLI session | | `Ctrl+C` | Cancel currently running agent turn or streaming response | | `Enter` | Submit prompt / send message | | `Shift+Enter` | Insert a newline into multiline input | | `Alt+Enter` | Insert a newline into multiline input | ### Input Navigation | Keybinding | Action | | --- | --- | | `Up` / `Down` | Browse prompt history | | `Ctrl+A` | Move cursor to beginning of line | | `Ctrl+E` | Move cursor to end of line | | `Ctrl+U` | Delete from cursor to start of line | | `Ctrl+K` | Delete from cursor to end of line | | `Ctrl+L` | Clear terminal screen | ### Agent Control | Action | How | | --- | --- | | **Accept Edit** | Press `Enter` or click Approve on tool prompt | | **Reject Edit** | Press `Esc` or type feedback | | **Interrupt** | `Ctrl+C` halts tool call immediately | --- ## Subagents & Delegation {.cols-2} ### Subagent Architecture {.row-span-2} Antigravity CLI can invoke specialized subagents that execute concurrently with their own contexts and workspaces: ```mermaid flowchart TD Parent[agy CLI Main Agent] --> Sub1[research Subagent] Parent --> Sub2[self Subagent] Parent --> Sub3[Custom Subagents] Sub1 -->|Insights| Parent Sub2 -->|Code Diffs| Parent ``` - **Isolated Context**: Subagents keep the main turn's context window clean and concise. - **Parallel Work**: Background subagents report results automatically without polling. - **Workspace Modes**: - `inherit`: Shares current project workspace. - `branch`: Creates an isolated git worktree branch. - `share`: Uses shared repository cache without copying storage. ### Built-in Subagent Types | Subagent | Scope | Purpose | | --- | --- | --- | | `research` | Read-only | Web search, codebase exploration, documentation analysis | | `self` | Full tools | Inherits parent tools to run parallel branch edits | | `custom` | Configurable | Defined dynamically via `define_subagent` | --- ## MCP Servers (Model Context Protocol) {.cols-2} ### Managing MCP Servers {.row-span-2} Antigravity natively integrates MCP servers to connect your agent to external databases, APIs, and devtools: ```bash # List configured MCP servers $ agy mcp list # Add local process (stdio) MCP server $ agy mcp add postgres npx -y @modelcontextprotocol/server-postgres "postgresql://localhost/db" # Add HTTP / SSE MCP server $ agy mcp add weather https://api.weather-mcp.internal/sse # Disable an MCP server temporarily $ agy mcp disable postgres # Re-enable an MCP server $ agy mcp enable postgres # Remove an MCP server $ agy mcp remove postgres ``` ### Configuration & Tool Loading Servers are stored in `~/.gemini/antigravity-cli/mcp//`: - **Eager Tools**: Automatically loaded into native agent tool registry. - **Lazy Tools**: Registered on-demand via schemas (`.json`) to conserve prompt tokens. - **Instructions**: Optional `instructions.md` guide agent when and how to call tools. --- ## Customization: Rules & Skills {.cols-3} ### Hierarchical Rules {.row-span-2} Rules guide coding standards and instructions automatically: - **Project Root**: `GEMINI.md`, `AGENTS.md` - **Scoped Rules**: `.agents/rules/*.md` or `.gemini/rules/` - **Hierarchical Discovery**: Traverses from active file up to git root. ```markdown # Project Guidelines - Always use TypeScript strict mode. - Write tests with Vitest in tests/ directory. ``` ### Agent Skills Skills teach reusable workflows and procedures: - Located in `.agents/skills//SKILL.md` or `~/.gemini/config/skills/`. - Loaded dynamically via **Progressive Disclosure** (only activated when relevant). ```yaml --- name: deploy-preview description: Deploy branch to preview environment and run smoke tests --- # Runbook steps here... ``` ### Precedence Order 1. Workspace Project (`.agents/`) 2. Workspace Declared (`skills.json`, `plugins.json`) 3. Global User Config (`~/.gemini/config/`) 4. Built-in Applications & Skills 5. Global Declared Config --- ## Plugins & Extensions {.cols-2} ### Managing Plugins {.row-span-2} Plugins bundle skills, rules, hooks, and MCP servers into installable units: ```bash # List all installed plugins $ agy plugin list # Install from registry or marketplace $ agy plugin install security-auditor@marketplace # Install local plugin package $ agy plugin install ./my-plugin # Import plugins from Claude or Gemini configs $ agy plugin import gemini $ agy plugin import claude # Validate plugin manifest and schema $ agy plugin validate ./my-plugin # Enable / Disable a plugin $ agy plugin enable security-auditor $ agy plugin disable security-auditor # Uninstall plugin $ agy plugin uninstall security-auditor ``` ### Plugin Structure ``` my-plugin/ ├── plugin.json # Manifest (name, version, entrypoints) ├── skills/ # Custom agent skills │ └── audit/SKILL.md ├── rules/ # Custom rules and guidelines │ └── security.md └── mcp_config.json # Bundled MCP server definitions ``` --- ## Configuration & Brain Storage {.cols-2} ### Configuration Locations {.row-span-2} | Scope | Path | Purpose | | --- | --- | --- | | **CLI Settings** | `~/.gemini/antigravity-cli/settings.json` | Global CLI preferences, default model, reasoning | | **Global Config** | `~/.gemini/config/` | User-wide skills, rules, and plugins | | **Workspace Config** | `.agents/` or `.gemini/` | Project-scoped rules and agent configurations | | **Sessions & Brain** | `~/.gemini/antigravity-cli/brain//` | Transcripts, tasks, and generated artifacts | ### Example `settings.json` ```json { "model": "gemini-3.8-flash-high", "effort": "high", "mode": "accept-edits", "telemetry": false } ``` ### Transcripts & Artifacts - Transcripts stored in `brain//.system_generated/logs/transcript.jsonl`. - Markdown artifacts and diff reports stored in `brain//`. --- ## Also see {.cols-1} - [Official Antigravity Documentation](https://antigravity.google/docs) _(antigravity.google)_ - [CLI Reference Guide](https://antigravity.google/docs/cli/reference) _(antigravity.google)_ - [CLI Features & Subagents](https://antigravity.google/docs/cli/features) _(antigravity.google)_ - [Skills Documentation](https://antigravity.google/docs/skills) _(antigravity.google)_ - [Rules & Guidelines Guide](https://antigravity.google/docs/rules-workflows) _(antigravity.google)_ - [Model Context Protocol (MCP)](https://antigravity.google/docs/mcp) _(antigravity.google)_ - [Antigravity Python SDK](https://github.com/google-antigravity/antigravity-sdk-python) _(github.com)_