agy CLI Troubleshooting: PATH, Auth, Permissions and MCP

Diagnose agy by subsystem: installation, authentication, permissions, MCP, migration, or quota. The CLI has a supported command or config location for each one. This guide covers those CLI-specific checks and links to focused articles for quota and MCP timeout internals.

Route the Symptom First

Type /help to see commands in the installed client. The current official CLI reference documents /permissions, /mcp, /usage, /model, /config, and /logout.

Fix “agy: command not found”

Google's installer puts agy in ~/.local/bin on macOS and Linux and under the current user's local app-data directory on Windows. The official troubleshooting page identifies a missing PATH entry as the cause of the documented agy: command not found symptom.

command -v agy
ls -l "$HOME/.local/bin/agy"
export PATH="$HOME/.local/bin:$PATH"
agy --version

If the temporary export works, add the same PATH entry to the startup file for your shell, then open a new terminal. If the binary is absent, reinstall using the command on the official Installation and Auth page. Review a remote installer before piping it to a shell.

Fix Keyring and Sign-In Errors

Antigravity CLI stores authentication profiles in the native secure keyring: Apple Keychain, Linux Secret Service/dbus, or Windows Credential Manager. On a local machine, agy attempts silent sign-in from that keyring; otherwise it opens a browser. Over SSH, it prints a URL and asks you to paste the resulting authorization code. These flows are documented on the official auth page.

1. If the error says the keyring is locked, unlock or authorize the OS keyring. Do not delete unrelated credentials.
2. If you intentionally need a clean Antigravity session, run /logout. Google says this purges saved Antigravity authentication profiles from the keyring.
3. Restart agy and complete the documented local browser or remote SSH flow.

Fix Repeated Permission Prompts

Open /permissions and inspect the action that is prompting. Fine-grained rules live in ~/.gemini/antigravity-cli/settings.json. The official permissions guide defines allow, ask, and deny lists and a strict precedence order: Deny, then Ask, then Allow.

{
  "permissions": {
    "allow": ["command(git status)", "command(npm run test)"],
    "deny": ["command(sudo)", "write_file(.git/)"],
    "ask": ["command(*)"]
  }
}

In that example, command(*) in Ask shadows the narrower Allow entries because Ask outranks Allow. Remove or narrow the conflicting Ask rule if you intend those exact commands to run without another prompt. Keep Deny rules for actions the agent should never perform.

Do not reach immediately for --dangerously-skip-permissions. The official CLI supports fine-grained rules and sandboxing; use the smallest grant that covers the task.

Fix an MCP Server That Is Missing or Disconnected

Open /mcp. The manager shows live status, supports reload, and exposes connection logs. Current Antigravity CLI supports both:

• global servers in ~/.gemini/config/mcp_config.json;
• workspace servers in .agents/mcp_config.json.

Those locations and the schema come from the official MCP guide. A remote server must use serverUrl; legacy url and httpUrl fields are not supported.

{
  "mcpServers": {
    "example": {
      "serverUrl": "https://api.example.com/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

1. Validate that the JSON parses.
2. For a local stdio server, run its configured command directly to expose startup errors.
3. For a remote server, confirm serverUrl and authentication.
4. Reload from /mcp and review the logs.

If the server connects but initialization exceeds its deadline, use the focused MCP context-deadline guide. If it exits or closes stdout during startup, run the exact configured command directly and fix the first concrete launch error before changing credentials or state.

Fix Migration Configuration Errors

After migrating from Gemini CLI, check paths before assuming a runtime bug. Google's migration guide documents these changes:

• workspace skills move from .gemini/skills to .agents/skills;
• MCP definitions move out of the legacy settings file into dedicated global or workspace mcp_config.json files;
• remote MCP fields move from url or httpUrl to serverUrl.

For the end-to-end transition, see our Gemini CLI to Antigravity CLI migration guide.

Route Quota and Capacity Messages Elsewhere

If the terminal says RESOURCE_EXHAUSTED, MODEL_CAPACITY_EXHAUSTED, “Individual quota reached,” or UNAVAILABLE, first run /usage (alias /quota). Google says this panel refreshes quota status from the backend for each supported model. Then use the model-capacity and quota decision tree. It explains why the full message matters more than 429 versus 503 alone.

This CLI article intentionally does not duplicate reset timing, plan limits, or capacity analysis. The official Model Quotas command page is the primary reference for the live panel.

Escalation Checklist

If the supported path does not resolve the problem, collect a minimal reproducible report:

• agy --version and operating system;
• the exact, unedited error text and timestamp;
• the command or slash command that triggered it;
• the relevant config fragment with secrets removed;
• whether it reproduces in a new empty directory or only one workspace;
• for MCP, the server's direct startup output and /mcp status.

Use Google's Antigravity support page for current channels. Never include OAuth tokens, API keys, bearer headers, or complete credential files.

Frequently Asked Questions

Where is the agy settings file?

Persistent CLI settings live at ~/.gemini/antigravity-cli/settings.json. Open the supported settings UI with /config or /settings.

Why does an allowed command still prompt?

Check for a matching Ask or Deny rule. The documented precedence is Deny, then Ask, then Allow, so a broad command(*) Ask rule can shadow a narrow Allow rule.

Where does workspace MCP config go?

Use .agents/mcp_config.json. The global equivalent is ~/.gemini/config/mcp_config.json.

Will /logout fix RESOURCE_EXHAUSTED?

No. /logout clears authentication profiles. Use /usage for quota and model-capacity diagnostics.

All Sources and Links

Primary Google Antigravity documentation

• CLI Troubleshooting — PATH, keyring, and updater symptoms
• Installation and Auth — install paths, keyrings, SSH, and logout
• CLI Reference — slash commands and settings
• CLI Permissions — actions, matching, and precedence
• MCP — config locations, schema, auth, and manager
• Gemini CLI Migration — current skills and MCP paths
• Model Quotas (/usage and /quota)