antigravity-cli

# Antigravity CLI (`agy`) Operator guide for the Antigravity CLI, invoked as `agy`. Run all `agy` commands through the Sonic `terminal` tool; inspect its config and logs with `read_file`. This skill is reference + procedure — it does not wrap a network API, so there is nothing to authenticate from Sonic itself. ## When to Use - Installing, updating, or smoke-testing the `agy` binary - Driving non-interactive `agy --print` / `agy -p` one-shots - Debugging Antigravity auth, sandbox, permissions, or plugin state - Reading Antigravity settings, keybindings, conversations, or logs ## Mental model Antigravity has two layers — keep them distinct or the guidance will be wrong: 1. **Shell wrapper commands** — `agy help`, `agy install`, `agy plugin`, `agy update`, `agy changelog`. Run these through the `terminal` tool. 2. **Interactive in-session slash commands** — `/config`, `/permissions`, `/skills`, `/agents`, etc. These only exist inside a running `agy` TUI session, not on the shell wrapper. `agy help` shows the shell wrapper surface, NOT the in-session slash commands. ## Prerequisites - The `agy` binary on PATH. Verify through the `terminal` tool: `command -v agy && agy --version`. - No env vars or API keys required by this skill — Antigravity manages its own auth via the OS keyring / browser sign-in (see Authentication below). ## How to Run Invoke every `agy` command through the `terminal` tool. Examples: ``` terminal(command="agy --version") terminal(command="agy help") terminal(command="agy plugin list") terminal(command="agy --print 'Summarize the repo in 3 bullets'", workdir="/path/to/project") ``` For an interactive multi-turn TUI session, launch `agy` with `pty=true` (and tmux for capture/monitoring), the same pattern the `codex` / `claude-code` skills use. For one-shot smoke tests and scripted prompts, prefer `agy --print` (non-interactive). To inspect Antigravity's own files, use `read_file` on the paths under Core paths below — do not `cat` them through the terminal. ## Delegation patterns `agy` is a coding-agent backend in the same family as `codex` / `claude-code`, so the same delegation shapes apply. Use these when handing real work (features, fixes, reviews, second opinions) to Antigravity rather than just smoke-testing. ### One-shot (preferred for scripted prompts and second opinions) ``` terminal(command="agy -p 'Review this diff for bugs and security issues' --model 'Gemini 3.1 Pro (High)'", workdir="/path/to/repo", timeout=300) ``` `-p` is non-interactive: it runs the prompt and exits. Pick the engine with `--model` (run `agy models` for the exact display strings, e.g. `'Gemini 3.1 Pro (High)'`, `'Claude Opus 4.6 (Thinking)'`). Add extra context roots with repeatable `--add-dir`. ### Long / bounded runs (tests, builds, multi-file changes) Background it and get notified on completion, the same as the `codex` skill: ``` 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>) ``` ### Interactive multi-turn (PTY + tmux) For a conversational session, launch `agy -i` (or bare `agy`) under `pty=true` with tmux for `capture-pane` / `send-keys`, exactly the pattern documented in the `codex` / `claude-code` skills. Resume later with `--continue` / `-c` or a specific `--conversation <id>`. ### Parallel instances (batch sub-issue / worktree fan-out) Create one git worktree per task and launch an independent `agy -p` in each (background), then collect results — same worktree fan-out the `codex` skill uses for batch issue fixing. Bound concurrency to what the machine and your review capacity can absorb. ### Output + bounding caveat (differs from Claude Code) - `agy -p` returns **plain text** — there is **no `--output-format json`** and no result envelope with `session_id` / cost / turn count. Parse stdout directly; don't expect a JSON object. - There is **no `--max-turns`**. A print run is bounded by **`--print-timeout`** (default `5m`). Raise it for long tasks: `--print-timeout 20m`. Pair with the `terminal` `timeout=` so the outer call doesn't cut the run short. ### Orchestration boundary Antigravity is a **worker execution backend or third-opinion reviewer** — an execution detail owned by the agent/profile running a task, NOT a first-class orchestration primitive. Do not put `agy` on a kanban board as its own card or treat it as a coordination layer; route work through the normal task graph and let the assigned worker choose `agy` (vs. codex/claude-code/direct tools) as its method. Reach for it explicitly only when the user asks, when a worker is configured to wrap it, or when you want a Gemini-family cross-check against another agent's plan or diff. ## Core paths - Binary / entrypoint: `agy` - App data dir: `~/.gemini/antigravity-cli/` - Settings file: `~/.gemini/antigravity-cli/settings.json` - Keybindings file: `~/.gemini/antigravity-cli/keybindings.json` - Logs: `~/.gemini/antigravity-cli/log/cli-*.log` - Conversations: `~/.gemini/antigravity-cli/conversations/` - Brain artifacts: `~/.gemini/antigravity-cli/brain/` - History: `~/.gemini/antigravity-cli/history.jsonl` - Plugin staging: `~/.gemini/antigravity-cli/plugins/<plugin_name>/` ## Quick Reference ### Wrapper commands - `agy changelog` - `agy help` - `agy install` - `agy plugin` / `agy plugins` - `agy update` ### Useful flags - `--add-dir` - `--continue` / `-c` - `--conversation` - `--dangerously-skip-permissions` - `--print` / `-p` - `--print-timeout` - `--prompt` - `--prompt-interactive` / `-i` - `--sandbox` - `--log-file` - `--version` ### Plugin subcommands (`agy plugin --help`) - `list`, `import [source]`, `install <target>`, `uninstall <name>`, `enable <name>`, `disable <name>`, `validate [path]`, `link <mp> <target>`, `help` ### Install flags (`agy install --help`) - `--dir`, `--skip-aliases`, `--skip-path` ### In-session slash commands - **Conversation control:** `/resume` (`/switch`), `/rewind` (`/undo`), `/rename <name>`, `/clear`, `/fork`, `/reset`, `/new` - **Settings & tools:** `/config`, `/settings`, `/permissions`, `/model`, `/keybindings`, `/statusline`, `/tasks`, `/skills`, `/mcp`, `/open <path>`, `/usage`, `/logout`, `/agents` - **Prompt helpers:** `@` path autocomplete, `esc esc` clears the prompt (when not streaming), `!` runs a terminal command directly, `?` opens help ## Settings and permissions ### Common settings keys (`settings.json`) - `allowNonWorkspaceAccess` - `colorScheme` - `permissions.allow` - `trustedWorkspaces` ### Permission modes `request-review`, `always-proceed`, `strict`, `proceed-in-sandbox`. ### Sandbox behavior - `enableTerminalSandbox` is a boolean in `settings.json`; default `false`. - Launch-time overrides (`--sandbox`, `--dangerously-skip-permissions`) can supersede persistent settings for the current session. ## Authentication behavior - The CLI tries the OS secure keyring first. - With no saved session, it falls back to browser-based Google sign-in. - Locally it opens the default browser; over SSH it prints an authorization URL and expects the auth code pasted back. - `/logout` removes saved credentials. ## Plugins - Plugins stage under `~/.gemini/antigravity-cli/plugins/<plugin_name>/`. - They can bundle skills, agents, rules, MCP servers, and hooks. - `agy plugin list` returning no imported plugins is a valid empty state. ## Pitfalls - `agy help` shows wrapper commands, not interactive slash commands. - `agy --version` is the safe non-interactive version check; `agy version` is interactive and can fail without a real TTY. - First place to look for failures: `~/.gemini/antigravity-cli/log/cli-*.log` (read with `read_file`). - Don't confuse persistent JSON settings with launch-time overrides. - `~/.gemini/antigravity-cli/bin/agentapi` is a thin wrapper to `agy agentapi`. - On WSL, token storage is file-based, so auth issues are usually local-file / session-state problems, not browser-only problems. - Workspace identity can depend on launch directory and the `.antigravitycli` project marker. - `agy -p` prints plain text only — no `--output-format json`, no result envelope. Don't try to parse a JSON object out of it (unlike `claude-code`). - Bound print runs with `--print-timeout` (default `5m`), not `--max-turns` (which does not exist on `agy`). ## Verification Confirm the install is real and usable, all through the `terminal` tool (read files with `read_file`): 1. `terminal(command="command -v agy")` 2. `terminal(command="agy --version")` 3. `terminal(command="agy help")` 4. `terminal(command="agy plugin list")` 5. `read_file` on `~/.gemini/antigravity-cli/settings.json` 6. `read_file` on the latest `~/.gemini/antigravity-cli/log/cli-*.log` 7. If needed, `read_file` on `~/.gemini/antigravity-cli/keybindings.json` ## Support files - `references/cli-docs.md` — condensed notes from the getting-started, usage, and features docs.