Antigravity CLI (agy) In-Depth Guide & CI/CD Automation

#!/usr/bin/env bash
set -euo pipefail

echo "==> [AGY-CI] Initializing Antigravity Automation Runner..."
agy --version || { echo "Error: agy CLI not found in PATH"; exit 1; }

echo "==> [AGY-CI] Running environment preflight checks..."
agy doctor --json > /tmp/agy-doctor.json

echo "==> [AGY-CI] Executing non-interactive agentic validation..."
agy run "Run unit test suite. If failures occur, pinpoint root cause and self-heal with minimal diffs." \
  --non-interactive \
  --timeout 300 \
  --max-turns 15

echo "==> [AGY-CI] Workflow completed with exit code 0."

Understanding the agy CLI

agy is the primary command-line interface for orchestrating the Antigravity agentic engine. It serves both as an interactive developer companion in local terminal workflows and as a headless execution runner inside continuous integration environments (GitHub Actions, GitLab CI).

---

Command Matrix & Option Reference

Category	Command	Key Flags	Typical Use Case
Diagnostics	agy doctor	--verbose, --json	Verify MCP server connections, Python/Node runtimes, and permissions
Execution	agy run [prompt]	--non-interactive, --timeout, -m	Launch single-objective autonomous agent execution
Sessions	agy session	--resume [id], --list	Manage long-lived multi-turn conversations and checkpoints
Scaffolding	agy init	--template [web|api]	Generate .agents/ workspace customization scaffold
Config	agy config get/set	--global, --workspace	Manage model routing policies, tool limits, and endpoints

---

Command Walkthroughs

1. agy doctor: Preflight Health Diagnostics

Before delegating multi-file refactoring or running automated tests, execute agy doctor to verify system prerequisites:

# Run formatted diagnostic check
agy doctor

# Output raw JSON for programmatic CI assertion
agy doctor --json | jq '.mcp_servers'

2. agy run: Headless Autonomous Execution

agy run delegates a structured coding objective to the agent. With --non-interactive, the agent explores context, applies diffs, executes test suites, and verifies syntax without requiring human keystrokes:

# Automatically resolve TypeScript compile errors and verify build
agy run "Fix all TypeScript lint warnings and verify npm run build passes" \
  --max-turns 10 \
  --timeout 180

[!TIP] In automated pipelines, always supply --max-turns to prevent runaway token expenditure and --timeout to bound execution duration.

3. Session Resume (agy session)

Antigravity automatically journals execution steps into structured JSONL transcripts. If a build task is paused, developers can resume state seamlessly:

# List recent sessions
agy session --list --limit 5

# Resume a specific session ID
agy session --resume <session-id>

---

GitHub Actions CI Integration

Save the downloadable artifact above to scripts/run-agy-ci.sh and wire it into your workflow:

name: Antigravity Automated Regression
on: [pull_request]

jobs:
  agentic-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Run Antigravity Autonomous Test
        env:
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
        run: |
          chmod +x ./scripts/run-agy-ci.sh
          ./scripts/run-agy-ci.sh