diff --git a/source/_posts/antigravity-cli.md b/source/_posts/antigravity-cli.md new file mode 100644 index 0000000..8b7c68d --- /dev/null +++ b/source/_posts/antigravity-cli.md @@ -0,0 +1,464 @@ +--- +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)_ diff --git a/source/assets/icon/agy.svg b/source/assets/icon/agy.svg new file mode 100644 index 0000000..b3851f2 --- /dev/null +++ b/source/assets/icon/agy.svg @@ -0,0 +1,7 @@ + + + + + + + diff --git a/source/assets/icon/antigravity-cli.svg b/source/assets/icon/antigravity-cli.svg new file mode 100644 index 0000000..b3851f2 --- /dev/null +++ b/source/assets/icon/antigravity-cli.svg @@ -0,0 +1,7 @@ + + + + + + +