antigravity-cli

name	antigravity-cli
description	Expert guide for Google's Antigravity CLI (agy), the official successor to Gemini CLI. Use when the user mentions 'agy', 'antigravity', 'antigravity cli', 'gemini cli replacement', 'gemini cli migration', or any task involving the agy command-line tool including running prompts, managing plugins, resuming sessions, or automating agy in scripts and CI/CD pipelines.
version	1.1.8

Antigravity CLI (agy) Skill

Targets locally installed agy v1.1.8.

Use this skill to work with the agy CLI for coding tasks, multi-agent orchestration, and workspace management.

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 stops 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 differences from Gemini CLI:

• Go binary (not Node.js) -- faster cold startup, no npm dependency chain
• Plugin system replaces Gemini CLI Extensions (agy plugin import gemini to migrate)
• Unified platform -- shares the same agent harness as the Antigravity IDE desktop app
• Tool calls limit: Supports up to 512 tool calls per turn for Gemini models, allowing for highly complex, multi-step agentic tasks.
• Binary name: agy (primary), antigravity (some Linux distros). Env var ANTIGRAVITY_CLI_ALIAS overrides detection.
• Install location: typically ~/.local/bin/agy

Complete Flag Reference

Primary Command: agy

Flag	Alias	Description
--print	-p, --prompt	Runs a single prompt non-interactively and prints the response.
--output-format <fmt>		Output format for print mode (text (default), json, stream-json) (v1.1.8+).
--json-schema <schema>		Enforce JSON schema (string or file path) on print output (v1.1.8+).
--effort <level>		Reasoning effort for the current CLI session (low, medium, high) (v1.1.5+).
--prompt-interactive	-i	Runs an initial prompt interactively and continues the session.
--continue	-c	Continues the most recent conversation in the current workspace.
--conversation <id>		Resumes a specific conversation by its ID.
--dangerously-skip-permissions		CRITICAL for automation. Auto-approves all tool permission requests.
--add-dir <path>		Adds a directory to the workspace (repeatable).
--agent <agent>		Specifies a custom agent for the current CLI session (v1.1.1+).
--sandbox

Known Limitations (verified with installed v1.1.8)

[!CAUTION] This skill is verified against locally installed agy v1.1.8. Several legacy flags from Gemini CLI remain unsupported. Do NOT attempt these flags -- they will fail.

Missing Capability	Gemini CLI Equivalent	Status
Reset workspace context	N/A	Not available (verified v1.1.8)
Yolo shorthand	--yolo	Use --dangerously-skip-permissions
Session resume by flag name	--resume <id>	Use --conversation <id>
MCP server control	--allowed-mcp-server-names=	Not available
Config home isolation	GEMINI_CLI_HOME env var	Not available

Automation & Streaming: As of v1.1.8, agy -p fully supports structured NDJSON streaming via --output-format stream-json. The stream emits typed init, step_update, and terminal result events with token accounting (including cache_read_tokens), tool_info (canonical name, args, output), and subagent_info for nested agents. Use --json-schema to enforce schema constraints on the final output.

Execution Modes & Diff Review

Version v1.1.0 introduces cycling and persistent setting of agent execution modes.

The Three Execution Modes

• default (with request-review behavior): The default behavior. The agent automatically pauses before file write operations (write_to_file and replace_file_content / multi_replace_file_content) to show an interactive, line-level diff preview (accessible via f shortcut in TUI). Users can review, accept, or reject individual changes before they are saved to disk. New file creations are rendered as addition-only diff previews (also accessible via f shortcut v1.1.2+). As of v1.1.1, the default mode respects write_file permissions allowlisted in settings.json under permission.allow so pre-approved file writes do not prompt for review.
• accept-edits: Automatically accepts file edits and creations without prompting for individual line-level reviews, streamlining fast development.
• plan: Replaces the legacy /planning mode. Focuses the agent on producing a comprehensive plan (PLAN.md) first, requiring verification before execution. Note that /fast slash commands have been removed in favor of this simplified cycling model.

Configuring and Toggling Modes

• Startup flag: Start a session in a specific mode by passing --mode <mode> (e.g. agy --mode plan).
• TUI Cycling: Cycle through modes dynamically inside the TUI viewport using shift+tab.
• Persistent Setting: Set and persist your default mode directly via the Agent Mode option in the /settings TUI panel (persisted inside settings.json with real-time synchronization).

Subcommands

agent (alias: agents)

List available agents and manage custom agents (v1.1.1+).

• agy agent: List available agents.

plugin (alias: plugins)

Manage the capabilities of your agent. Downloaded plugins are stored directly in ~/.gemini/config/ for instant discoverability.

• agy plugin list: See what's installed.
• agy plugin install <target>: Add new powers (e.g., plugin@marketplace). Also supports installing directly from GitHub subpaths with branch resolution (e.g., owner/repo/subpath@branch). External plugin installation automatically resolves and initializes Git submodules (v1.0.9+).
• agy plugin import gemini: Migrate your Gemini CLI extensions to Antigravity plugins.
• agy plugin import claude: Import Claude Code extensions as plugins.
• agy plugin enable/disable <name>: Toggle specific functionality.
• agy plugin uninstall <name>: Remove a plugin.
• agy plugin validate [path]: Validate a plugin definition.
• agy plugin link <mp> <target>: Generate a link to a marketplace.

install

Configure environment paths and shell settings.

• agy install: Set up PATH and shell aliases.
• agy install --dir <path>: Custom directory target for PATH configuration.
• agy install --skip-path: Skip shell profile PATH appending.
• agy install --skip-aliases: Skip shell profile alias purging.

models

List available models for CLI sessions.

• agy models: Display a list of available model names.

update

agy update: Update the CLI to the latest version.

changelog

agy changelog: View version history and release notes.

Agentic Workflows & Best Practices

The "Print Mode" Trap (-p)

[!WARNING] Running agy -p is excellent for quick tasks, but it has critical caveats in an automated environment:

• Permissions: You MUST use --dangerously-skip-permissions or the command will hang silently waiting for approval.
• First run: agy may require initial interactive setup before print mode works. If -p hangs with zero output on a fresh install, run agy interactively first to complete auth/setup.
• Timeout: Print mode has a default 5-minute timeout (--print-timeout). For long-running tasks, increase it: --print-timeout 30m.
• Output: stdout may be buffered. Use --log-file if you need to track execution details. Print mode properly writes errors to stderr and returns a non-zero exit code if a request fails server-side (v1.1.1+). It also supports pasting OAuth authorization codes via the controlling terminal when stdin is consumed (v1.1.2+).

Spawning Subagents

You can use agy to spawn other agents to handle sub-tasks.

agy -p "Review this code: $(cat main.py)" --dangerously-skip-permissions

By nesting CLI calls, you can create hierarchical agent structures.

Defining Subagents

As of v1.1.0, custom subagents are defined using the Markdown format (agent.md) rather than the legacy JSON format (agent.json). Global custom subagents should be created in the shared configuration directory (~/.gemini/config/) where they are actively scanned during startup discovery. Subagents also support an "always proceeds" mode for auto-approving artifacts when the parent is blocked.

Resuming Conversations

To maintain context across different execution steps:

1. Start with a prompt: agy -i "Let's build a React app"
2. Follow up later: agy -c "Now add a login page"
3. Resume a specific session: agy --conversation <id>

Advanced Automation Patterns

Multi-turn Continuity (-c + -p)

You can chain non-interactive prompts by combining the continue flag (-c) with print mode (-p). This is the preferred way for agents to perform multi-step tasks without a TTY:

# Turn 1: Initial request
agy -p "Initialize a new project" --dangerously-skip-permissions

# Turn 2: Follow-up using context from Turn 1
agy -c -p "Now add a basic index.html" --dangerously-skip-permissions

[!NOTE] As of v1.0.9+, resuming in headless print mode (-c/-p or --conversation/-p) correctly prints only the newly generated response rather than dumping the entire historical conversation transcript.

Explicit Content Injection

To ensure the agent has the correct context (bypassing persistent workspace issues), inject file content directly into the prompt:

agy -p "$(cat README.md)\n\nBased on this file, what is the project goal?" --dangerously-skip-permissions

Targeted Workspace Addition

Use --add-dir to explicitly bring external directories into the current session context:

agy -p "Analyze this code" --add-dir ./src --dangerously-skip-permissions

Workspace Management & Persistent State

[!CAUTION] Persistent Workspace State Warning agy maintains its own persistent internal workspace context across sessions. It does NOT automatically scope itself to your shell's current working directory (CWD).

• cd-ing into a directory will not change the agent's focus.
• Running agy -p without explicit content may result in answers based on a previous, unrelated project.
• Silent Failure Mode: If no explicit files are provided, agy will answer from the last session context without warning.

To manage this:

1. Use --add-dir to explicitly scope the session.
2. Use the "Explicit Content Injection" pattern for small files.
3. Be aware that v1.0.12 has no native command to "reset" or "clear" the workspace context.

Environment Variables & Permissions Configuration

Environment Variables

• AGY_CLI_HIDE_ACCOUNT_INFO: Set to true or 1 to hide user email and plan tier details from the terminal header, preserving privacy during screen shares or CI/CD logs.
• ANTIGRAVITY_CLI_ALIAS: Overrides automatic binary name detection.
• AGY_CLI_DISABLE_LATEX: Set to true or 1 to globally disable LaTeX math rendering in the terminal viewport (added in v1.0.4).
• USE_ADC: Set to 1 to authenticate via Application Default Credentials (v1.0.11+).
• AGY_CLI_CMD_OUTPUT_PERCENTAGE: Customize max height of command outputs in the TUI as a percentage (v1.0.11+).

Tool Permissions & Sandbox Mode

• Sandbox Mode (--sandbox): Restricts terminal operations to a secure runtime environment. In v1.0.6+, --sandbox propagation is fixed in headless print mode (-p / --print), ensuring sandbox isolation is correctly enforced during non-interactive execution.
• Proceed-in-Sandbox Mode: Automatically approves terminal commands that run inside the secure sandbox. Manual approval is requested only when a command attempts to bypass the sandbox, making automated non-interactive tasks much smoother.
• Hardened Sandbox Checks (v1.0.9+): Enforces strict exact-match verification for PowerShell scripts, complex shell redirections (>, 2>&1), and unparseable strings. Additionally, the .git directory is added to the core list of dangerous paths to prevent unauthorized repository modifications.
• Optimized Customizations Permissions (v1.0.9+): Automatically grants read-only access to the built-in customizations directory, eliminating redundant permission prompts on startup.
• Permission & Flag Fixes (v1.0.10+): Escapes regex metacharacters in saved permission rules to prevent infinite loops, fixes environment flag parsing, ensures "ask" permissions in settings.json are preserved across configuration writes, and resolves bash mode argument escaping (defaulting shell resolution to PowerShell).
• Interactive Permissions Configuration (/permissions): Added in v1.0.5. Allows users to add, edit, or remove permission rules directly inside the TUI. Supports configuring permissions for workspace levels, shared settings, and CLI-specific configuration settings.
• Integrated Permissions System: Integrates CLI permissioning with the rest of the Antigravity system, merging project-level permissions, shared user settings, and CLI-specific configuration rules. In v1.0.12+, project-specific configurations (in ~/.gemini/config/projects/) take precedence over global settings.
• Strict Permission Rule Matching (v1.1.0): "Always Approve" command rules match via exact prefix strings by default. Users must explicitly opt-in to regex matching by prefixing a rule with regex:. Nested command substitutions (e.g. $(dirname ...)) also respect allowlists (v1.1.2+).

Interactive Interface & Commands

/codesearch (Aliases: /cs, /search)

Added in v1.1.3. Interactively search code across your workspace with live streaming results.

• Interprets queries as regex by default.
• Use -F or --literal for exact literal text matching.
• Filter paths using f: or file: globs (e.g. /codesearch f:*.py def main).
• Cancel in-flight searches with Esc (v1.1.6+).

Reasoning Effort Control (/effort & --effort)

Added in v1.1.5. View and adjust the reasoning effort level for supported models.

• Interactive /effort command renders a left/right timeline-gauge picker in the status line.
• Direct command syntax: /effort low, /effort medium, /effort high.
• Startup flag: agy --effort high.

Custom Markdown Agents (agent.md)

Added in v1.1.6. Custom agents and subagents are defined using Markdown files (agent.md) with YAML frontmatter:

---
name: code-reviewer
description: Rigorous code reviewer
mainAgent: false
subagent: true
hidden: false
inheritMcp: true
commandExecutionPolicy: ask
model: pro
---
# System Prompt Header
Detailed agent prompt goes here...

Frontmatter supports model pinning (flash, pro, inherit), subagent toggles, and commandExecutionPolicy.

Stacked Slash Commands

Added in v1.1.4. Allows prefixing a single prompt with multiple slash commands in chain, executing in order typed:

/plan /grill-me Refactor the database layer

/copy Enhancements

Added in v1.1.6. The /copy command accepts an optional numerical index:

• /copy: Copies the most recent response.
• /copy <n>: Copies the n-th most recent response to clipboard.

G1 Credits & /credits Panel

Version v1.0.3 adds full support for G1 credits:

• Automatic Credit Usage: When standard model quota runs out, the CLI can automatically utilize G1 credits.
• UseG1Credits Setting: A new TUI setting enables/disables automatic G1 credit usage.
• Real-Time Display: Remaining G1 credits are displayed in real-time in the terminal's status bar.
• /credits Panel: Open the in-CLI credits panel to view credit balance details and access a direct link to purchase additional G1 credits.

Keyboard Shortcuts & UI Updates

• Slash Commands Caret (>): All user slash commands and interactive shell inputs in message history are rendered with a caret prefix (>) to clearly distinguish them from agent-generated output.
• Slash Command History (v1.0.8+): Up arrow key in the TUI prompt editor replays previously entered slash commands.
• Paste Guard (v1.0.8+): A per-line guard replaces extremely long single-line TUI pastes with an expandable placeholder to prevent performance lag.
• Copy-on-Select Setting (v1.1.8+): copyOnSelect setting in /settings (default on) toggles auto-copying mouse text selections to the clipboard in altscreen mode.
• Improved Shortcuts: The /help shortcuts tab sorts all keybindings by their primary key.
  • New Keybindings: Additional built-in shortcuts include:
  • ctrl+r: Reload / Search history. As of v1.0.5, you can open this Artifact Review panel while answering pending questions or tool permission confirmations, preserving your current progress when toggling back.
  • ctrl+o: Open file/url
  • ctrl+g: Expanded AltScreen view for tool confirmations replacing inline edit (v1.0.11+). On the artifact detail view, opens $EDITOR (warns if there are unsent comments).
  • shift+n: Reverse diff cycling navigation in unified diff review mode (v1.0.12+).
  • alt+v: Windows alternate clipboard paste shortcut for reliable image pasting (v1.0.15+).
  • shift+tab: Cycle agent execution modes (default -> accept-edits -> plan) (v1.1.0).
  • / and n/N: In-file keyword search and jump navigation inside the artifact detail viewer (v1.1.1+).
  • alt+j / ctrl+k: UI focus and navigation overrides
• Scrolling Shortcuts: General scrolling (PageUp/PageDown/GoToTop/) is fully supported across both Commands and Shortcuts tabs.

LaTeX Math Rendering

Added in v1.0.4. Renders beautiful LaTeX mathematical formulas directly in the terminal viewport. You can disable this by setting the AGY_CLI_DISABLE_LATEX environment variable.

SQLite Conversation Storage & /resume Performance

As of v1.0.4, the CLI uses SQLite (.db and .db-wal) as its default conversation storage format. Performance of /resume is highly optimized in v1.0.5 through lazy loading conversation details, filtering of empty conversations, and fast scanning of SQLite database files.

• Subagent Filtering: Subagent conversations are automatically skipped from /resume to keep the picker focused solely on direct user-initiated conversations (v1.0.6+).
• Archival Timestamp: Conversation archiving now correctly saves the archival status timestamp (v1.0.7+).
• Redesigned Picker (v1.0.8+): /resume conversation picker aligned workspace columns and added adaptive column dropping (workspace, time, steps) for narrow terminals.
• Rename View Improvements (v1.1.0): Rename view dynamically scales the input editor width/padding and shifts metadata columns to prevent TUI layout shifts during rename operations.

Centralized Project Discovery

Decoupled in v1.0.4 from local workspace directories. Workspace-to-project mappings are centralized in ~/.gemini/antigravity-cli/cache/projects.json for clutter-free repositories and single-map lookups.

Autocomplete Alias Resolution

As of v1.0.5, tab completion for slash commands resolves to the matched alias (e.g., /se autocompletes to /settings instead of the primary /config command).

TUI & Autocomplete Enhancements

• Path Auto-Completion: Added in v1.0.6. Supports shell-style path auto-completion when typing path arguments for the /open and /add-dir commands in the interactive TUI.
• Fuzzy Slash Command Suggestions: Added in v1.0.6. Autocompletion for slash commands now supports fuzzy and partial substring matching (e.g., typing /el suggests /help and /model). Autocomplete prefix bugs (like /conv vs /conv-switch) are resolved (v1.0.8+).
• Unconditional @ Mentions Typeahead: Suggestions trigger whenever @ is typed without preceding whitespace (e.g., after opening parenthesis ().
• Optimistic Rendering: Added in v1.0.6. Implements optimistic rendering for user chat prompts, immediately displaying the user's prompt in the viewport to reduce perceived input lag.
• Esc Key Stream Interrupt: Entering a prompt immediately after pressing Esc (to interrupt stream) now accepts input without swallowing/rejecting it.
• Artifact Viewer Improvements: Gutter numbering and line mapping in the artifact viewer are revamped in v1.0.7+ to accurately align viewport lines with 1-based source line numbers, correctly handling wrapped lines and collapsed Mermaid diagrams. Layout boundary overflow and scrolling bugs in the detail view with inline comments are resolved. Gutter layout rendering complexity during long sessions is also optimized to prevent hangs (v1.0.8+).
• Dynamic Skill & Command Autocomplete: Custom skills and system slash commands are dynamically reloaded and instantly discovered upon conversation switch or /add-dir (v1.0.8+).
• Builtin Guide Skill (v1.0.10+): Includes the antigravity_guide builtin skill to provide instant, in-context reference guides for Antigravity 2.0, CLI, IDE, and SDK.
• Glamour Parsing Error Handling: Graceful fallback to raw text with a warning banner on bubbletea parsing errors (e.g. nested checkboxes inside list emphasis), preventing TUI crashes (v1.0.9+). Renders cleaner headings and block padding with upgraded Glamour v2.0.1 (v1.0.10+).
• : Scrolling in commit history navigation immediately loads/displays changed files and diffs; ASCII node graphs () are enabled for visual parity; short (6-char) commit hashes are matched to long (64-char) hashes; system errors/warnings use a dedicated alert message type; and CLI log file path is accessible in the menu.

Models & Quota Page (v1.0.8+)

• Redesigned Interface: Enabled by default, replacing the legacy usage page. It handles disabled quota buckets by displaying a dimmed "Disabled" status and omitting progress bars.
• Settings Inheritance: CLI inherits the use_ai_credits setting from global user settings on startup.
• Transient Statusline Errors: Propagates configuration write failures as transient error flashes on the TUI status line.
• Hook Configurations: /hooks command now correctly writes to the shared configuration directory (~/.gemini/config/hooks.json).

/tasks and /btw Updates (v1.0.8+)

• /tasks Redesign: Redesigned list and detail views with start times on the left, right-aligned status, and capped panel height for better readability.
• /btw Optimization: Improved token efficiency, streaming responses, and fixed premature truncation.
• Local Timezone Conversion (v1.1.0): Agent-initiated background task timestamps (time.Time) are converted from UTC to the local timezone.
• Log Auto-scrolling (v1.0.16+): The /tasks detail panel automatically scrolls to the bottom as new logs stream in, defaulting to the latest output.

Migrating from Gemini CLI

If you previously used Gemini CLI:

1. Import your extensions: agy plugin import gemini
2. Note flag differences (see Known Limitations table above)
3. Replace gemini -p with agy -p in scripts
4. Replace --yolo with --dangerously-skip-permissions
5. Replace --resume <id> with --conversation <id>

Gemini CLI Flag Mapping

Quick reference for translating Gemini CLI commands to agy:

Gemini CLI	agy Equivalent	Notes
gemini -p "prompt"	agy -p "prompt"	Same semantics
gemini --yolo	agy --dangerously-skip-permissions	Longer but same effect
gemini --resume	agy --conversation <id>	Different flag name
gemini -o stream-json	agy -p --output-format stream-json	NDJSON streaming supported in v1.1.8+
gemini -m	agy --model <model>	Supported in v1.0.5+
gemini --approval-mode plan	agy --mode plan	Fully supported since v1.1.0

Troubleshooting

• Hangs/Timeouts (print mode): Usually caused by missing --dangerously-skip-permissions. Can also indicate first-run setup is needed -- run agy interactively once to initialize.
• Hangs/Timeouts (long tasks): Increase --print-timeout beyond the default 5 minutes.
• Permission Denied: Check if --sandbox is restricting the operation, or if the OS requires manual approval.
• Lost Context: Use agy --conversation <id> to recover a specific session state.
• Extensions missing after migration: Run agy plugin import gemini to port Gemini CLI extensions.
• Binary not found: Check ~/.local/bin/agy or run agy install to configure PATH. On some Linux distros, the binary is named antigravity.