Antigravity CLI (agy) Operator Reference

This guide covers the Antigravity CLI (agy), a coding-agent backend for installing, updating, smoke-testing, debugging, and driving non-interactive prompts. All commands run through the Hermes terminal tool; inspect configuration and logs with read_file. Antigravity does not wrap a network API, so no Hermes authentication is needed.

When to Use agy

Use agy when you need to:

• Install, update, or smoke-test the agy binary
• Drive non-interactive one-shot prompts with agy --print or agy -p
• Debug Antigravity authentication, sandbox, permissions, or plugin state
• Read Antigravity settings, keybindings, conversations, or logs

Prerequisites

• The agy binary must be on PATH. Verify with:

  terminal(command="command -v agy && agy --version")
  

• No environment variables or API keys are required. Antigravity manages its own authentication via the OS keyring or browser sign-in.
• All commands run through the Hermes terminal tool. Configuration and logs are inspected with read_file.

Verification Procedure

Follow these steps to verify an agy installation:

1. Run terminal(command="command -v agy")
2. Run terminal(command="agy --version")
3. Run terminal(command="agy help")
4. Run terminal(command="agy plugin list")
5. Use read_file on ~/.gemini/antigravity-cli/settings.json
6. Use read_file on the latest ~/.gemini/antigravity-cli/log/cli-*.log
7. If needed, use read_file on ~/.gemini/antigravity-cli/keybindings.json

Shell Wrapper Commands

These are the top-level commands shown by agy help:

• agy help - Display help for shell wrapper commands
• agy install - Install or update the binary
• agy plugin - Manage plugins
• agy update - Update agy
• agy changelog - Show the changelog

Note: agy help shows only shell wrapper commands, not interactive slash commands. For interactive slash commands, see the section below.

Interactive Slash Commands

The following slash commands are available only inside a running agy TUI session:

• /config - View or edit configuration
• /permissions - Manage permissions
• /skills - List or manage skills
• /agents - List or manage agents
• /resume - Resume a conversation
• /switch - Switch conversation
• /rewind - Rewind conversation
• /undo - Undo last action
• /rename - Rename conversation
• /clear - Clear conversation
• /fork - Fork conversation
• /reset - Reset conversation
• /new - Start new conversation
• /settings - Open settings
• /model - Change model
• /keybindings - View keybindings
• /statusline - Configure status line
• /tasks - Manage tasks
• /mcp - MCP commands
• /open - Open a file
• /usage - Show usage
• /logout - Log out

Additional behaviors: path autocomplete, for file paths, clears the prompt (when not streaming), to clear input, and runs a terminal command directly, to execute shell commands.

Running One-Shot Non-Interactive Prompts

Use agy --print or agy -p for non-interactive prompts. The output is plain text only, with no JSON envelope.

terminal(command="agy --print 'Summarize the repo in 3 bullets'", workdir="/path/to/project")

For more complex prompts with model selection and timeout:

terminal(command="agy -p 'Review this diff for bugs and security issues' --model 'Gemini 3.1 Pro (High)'", workdir="/path/to/repo", timeout=300)

Parameters for One-Shot Runs

• --print / -p - Non-interactive mode: run prompt and exit
• --prompt - Specify the prompt text
• --model - Select engine (use exact display string from agy models)
• --print-timeout - Timeout for print runs (default 5m)
• --add-dir - Add extra context roots (repeatable)
• --dangerously-skip-permissions - Skip permission prompts for the session
• --sandbox - Enable sandbox for the session
• --log-file - Specify log file path
• --version - Print version and exit (non-interactive)
• workdir - Working directory for the command
• timeout - Outer timeout for the terminal call (should be >= --print-timeout)

Constraints for One-Shot Runs

• agy -p returns plain text only. There is no --output-format json flag, no result envelope with session_id, cost, or turn count.
• There is no --max-turns flag. Bound print runs with --print-timeout (default 5m). Use --print-timeout 20m for longer runs.
• The terminal timeout= must be greater than or equal to --print-timeout, or the print run will be cut short.

Running Long or Bounded Tasks in Background

For tasks that take a long time, run in background and monitor:

terminal(command="agy -p 'Implement the change described in TASK.md and run the tests' --dangerously-skip-permissions", workdir="/path/to/repo", background=true, notify_on_complete=true)
# then: process(action="poll"/"log"/"wait", session_id=<id>)

Parameters for Background Runs

• background=true - Run command in background
• notify_on_complete=true - Notify when background command completes
• Use process(action="poll"/"log"/"wait", session_id=<id>) to monitor

Running Interactive Multi-Turn Sessions

Launch an interactive session under pty=true with tmux for capture-pane and send-keys:

• Use agy -i (or bare agy) with pty=true
• Resume later with --continue / -c or --conversation

Parameters for Interactive Sessions

• --prompt-interactive / -i - Start interactive session
• --continue / -c - Resume a previous conversation
• --conversation - Specify a conversation to resume
• pty=true - Use PTY for interactive sessions

Running Parallel Instances

For batch sub-issues or worktree fan-out:

1. Create one git worktree per task
2. Launch an independent agy -p in each (background)
3. Collect results
4. Bound concurrency to machine and review capacity

Plugin Management

Use agy plugin for plugin operations. Get help with agy plugin --help.

Plugin Subcommands

• list - List installed plugins
• import [source] - Import a plugin
• install - Install a plugin
• uninstall - Uninstall a plugin
• enable - Enable a plugin
• disable - Disable a plugin
• validate [path] - Validate a plugin
• link - Link a plugin
• help - Show plugin help

Plugin Staging Directory

Plugin staging directory: ~/.gemini/antigravity-cli/plugins//

Note: agy plugin list returning no imported plugins is a valid empty state.

Installation Help

Use agy install --help for installation options:

• --dir - Installation directory
• --skip-aliases - Skip alias creation
• --skip-path - Skip PATH update

Settings and Permissions

Persistent settings are stored in ~/.gemini/antigravity-cli/settings.json. Key settings include:

• allowNonWorkspaceAccess - Allow access outside workspace
• colorScheme - UI color scheme
• permissions.allow - Permission mode (request-review, always-proceed, strict, proceed-in-sandbox)
• trustedWorkspaces - List of trusted workspaces
• enableTerminalSandbox - Enable sandbox for terminal (default false)

Do not confuse persistent JSON settings with launch-time overrides.

Authentication

Antigravity manages its own auth via OS keyring or browser sign-in. On WSL, token storage is file-based; authentication issues are usually local-file or session-state problems.

Model Selection

Use --model with the exact display string from agy models. Examples:

• 'Gemini 3.1 Pro (High)'
• 'Claude Opus 4.6 (Thinking)'

Logging and Data Locations

All paths are under ~/.gemini/antigravity-cli/:

• ~/.gemini/antigravity-cli/settings.json - Persistent settings
• ~/.gemini/antigravity-cli/keybindings.json - Keybindings
• ~/.gemini/antigravity-cli/log/cli-*.log - Log files (first place to check for failures; use read_file, not cat)
• ~/.gemini/antigravity-cli/conversations/ - Conversation storage
• ~/.gemini/antigravity-cli/brain/ - Brain data
• ~/.gemini/antigravity-cli/history.jsonl - History file
• ~/.gemini/antigravity-cli/plugins// - Plugin staging
• ~/.gemini/antigravity-cli/bin/agentapi - Thin wrapper to agy agentapi

Workspace Identity

Workspace identity can depend on the launch directory and the .antigravitycli project marker file.

Failure Modes

• agy version fails without a real TTY. Use agy --version instead.
• Authentication issues on WSL due to file-based token storage.
• Print run cut short if terminal timeout= is less than --print-timeout.
• Parsing agy -p output as JSON fails (it is plain text only).
• Confusing persistent settings with launch-time overrides leads to unexpected behavior.
• Interactive slash commands are not available outside a running TUI session.
• Workspace identity mismatch due to launch directory or missing .antigravitycli marker.

Important Caveats

• agy is a worker execution backend or third-opinion reviewer, not a first-class orchestration primitive. Do not put it on a kanban board as its own card.
• Reach for agy explicitly only when the user asks, when the worker is configured to wrap it, or for Gemini-family cross-check.
• Bound concurrency to machine and review capacity for parallel instances.
• First place to look for failures: ~/.gemini/antigravity-cli/log/cli-*.log (use read_file, not cat).
• Workspace identity can depend on launch directory and .antigravitycli project marker.
• For reference, see references/cli-docs.md.