Migrate from Gemini CLI to Antigravity CLI: Complete Step-by-Step Guide 2026

How-To Guide·Jul 2, 2026·13 min read

Why You Must Migrate Before June 18, 2026

Google shipped Gemini CLI in 2025 to bring Gemini directly into the terminal, and by any measure it succeeded — over 100,000 GitHub stars, 6,000 merged pull requests, and millions of active users. The problem is that user workflows outgrew the original design. Single-agent, synchronous terminal sessions simply can't handle what developers now need: multiple agents communicating, splitting work, and operating asynchronously across complex pipelines.

Google's answer is Antigravity CLI, the terminal component of the Google Antigravity platform — their agent-first development environment. Rather than maintain two diverging codebases, Google is consolidating everything into Antigravity CLI and shutting down Gemini CLI on June 18, 2026.

⚠️ Hard Deadline: June 18, 2026. After this date, Gemini CLI stops serving requests entirely. No grace period, no read-only mode. If you haven't migrated, your terminal AI workflows go dark.

What Google Is Consolidating into Antigravity CLI

Antigravity CLI isn't a rebrand — it's a Go rewrite with a new architecture that shares the same agent harness as Antigravity 2.0, the new Antigravity desktop application. This means improvements to core agents propagate automatically to your terminal. The two biggest net-new capabilities are async background agent orchestration (run large-scale refactors without locking your terminal) and the unified backend shared with the desktop app.

Feature Mapping: What Carries Over

| Gemini CLI Feature | Antigravity CLI Equivalent | Notes | |---|---|---| | Agent Skills | Agent Skills | Direct equivalent, same concept | | Extensions (.gemini/extensions/) | Antigravity Plugins | Schema renamed and restructured | | Subagents | Subagents | Carried over, now async-capable | | Hooks (settings.json) | Hooks (antigravity.config.json) | Field names changed | | gemini binary | antigravity binary | Binary name change |

Google explicitly notes there won't be 1:1 feature parity at launch. That's an honest acknowledgment worth keeping in mind as you plan your migration timeline.

Prerequisites Checklist Before You Start

Before running a single install command, verify every item below. Skipping prerequisites — especially the config backup — is the most common reason migrations fail or lose custom work.

[ ] Operating system: macOS 12+, Ubuntu 20.04+/Debian 11+, Windows 10 21H2+ or Windows 11
[ ] Go runtime: Go 1.22 or later installed (go version to check) — required if you build any custom plugins from source
[ ] Google account: Signed in and associated with either a free Gemini tier or a Google One/Workspace plan
[ ] Antigravity access: Visit antigravity.google.dev and confirm your account has Antigravity CLI access enabled (enterprise customers go through Google Cloud console — different path)
[ ] Config exported: Run gemini config export > gemini-config-backup.json before touching anything
[ ] Hooks and extensions backed up: Copy your entire ~/.gemini/ directory to a safe location

Note: Enterprise customers have a different transition path. Your organization's Google Cloud admin needs to enable the Antigravity API in your GCP project and provision service account credentials. Individual/free users follow the OAuth flow described in Step 2. If you're unsure which tier you're on, check your Gemini CLI settings under gemini config list | grep tier.

API Key Warning: Gemini CLI used Gemini API keys stored in ~/.gemini/config. Antigravity CLI uses a separate credential system under ~/.config/antigravity/. Your old API keys do not auto-migrate — you must re-authenticate.

Estimated time: 25–40 minutes for individual users with existing extensions. Enterprise migrations may take longer depending on org policy review.

Step 1: Install Antigravity CLI on Your Machine

The binary name changes from gemini to antigravity. This is the most immediate breaking change — any shell aliases, scripts, or CI pipelines calling gemini will need updating. Install the new CLI first, then handle those references.

macOS via Homebrew

brew tap google/antigravity
brew install antigravity

Linux via Shell Script

curl -fsSL https://antigravity.google.dev/install.sh | sh
# Or via apt on Debian/Ubuntu:
echo "deb [signed-by=/usr/share/keyrings/google-antigravity.gpg] https://packages.antigravity.google.dev/apt stable main" | sudo tee /etc/apt/sources.list.d/antigravity.list
curl -fsSL https://packages.antigravity.google.dev/apt/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/google-antigravity.gpg
sudo apt-get update && sudo apt-get install -y antigravity

Windows via winget

winget install Google.AntigravityCLI
# Or download the MSI directly:
# https://antigravity.google.dev/releases/latest/antigravity-installer.msi

Verify the Installation

antigravity --version
# Expected output:
# Antigravity CLI v1.0.0 (go1.22.3 linux/amd64)
# Build: 20260519-release

If antigravity isn't found after install, check that your PATH includes /usr/local/bin (Linux/macOS) or the winget install directory (Windows). Do not uninstall gemini yet — you'll want it available while testing the migration in parallel.

Step 2: Authenticate and Connect Your Google Account

Antigravity CLI uses a completely separate credential store from Gemini CLI. Your old ~/.gemini/config file with its API keys is not read by Antigravity — you must run the auth flow fresh. This is intentional: Antigravity uses OAuth 2.0 tokens scoped specifically to the Antigravity API, not raw API keys.

antigravity auth login
# The CLI opens your browser to:
# https://accounts.google.com/o/oauth2/v2/auth?client_id=...&scope=antigravity.api
# After browser authorization, you'll see:
# ✓ Authenticated as your.email@gmail.com
# ✓ Credentials saved to ~/.config/antigravity/credentials.json
# ✓ Active plan: Gemini Advanced (quota: 1000 requests/day)

After login, compare the old and new config locations:

# OLD Gemini CLI config location
cat ~/.gemini/config
# {
#   "api_key": "AIzaSy...",
#   "model": "gemini-2.5-pro",
#   "theme": "dark"
# }

# NEW Antigravity CLI config location
cat ~/.config/antigravity/credentials.json
# {
#   "client_id": "...",
#   "client_secret": "...",
#   "token": "ya29.A0ARrda...",
#   "refresh_token": "1//0gx...",
#   "expiry": "2026-06-19T14:22:00Z",
#   "account": "your.email@gmail.com",
#   "scopes": ["https://www.googleapis.com/auth/antigravity"]
# }

The full config directory is ~/.config/antigravity/ — this is where your project context, plugin configs, and hook definitions will also live. Verify your quota and plan with:

antigravity auth status
# Account: your.email@gmail.com
# Plan: Gemini Advanced
# Quota used: 0/1000 today
# Antigravity access: ✓ enabled

Note: If antigravity auth status shows Antigravity access: ✗ not enabled, visit the Antigravity dashboard at antigravity.google.dev/dashboard and enable CLI access for your account. Enterprise users need their GCP admin to grant the roles/antigravity.user IAM role.

Step 3: Migrate Your Gemini CLI Configuration and Workflows

This is the meatiest part of the migration. You have four artifacts to move: project context files, extensions (now plugins), hooks, and subagent definitions. None of these migrate automatically — Antigravity CLI does not read from ~/.gemini/ at all.

Translating GEMINI.md Context Files

Gemini CLI used GEMINI.md files in your project root for persistent context. Antigravity CLI reads ANTIGRAVITY.md instead. The format is identical Markdown — rename and move:

cp GEMINI.md ANTIGRAVITY.md
# If you have nested GEMINI.md files in subdirectories:
find . -name "GEMINI.md" -exec sh -c 'cp "$1" "$(dirname $1)/ANTIGRAVITY.md"' _ {} \;

Converting Extensions to Antigravity Plugins

Gemini CLI extensions lived in .gemini/extensions/<name>/manifest.json. Antigravity plugins use a YAML-first format named antigravity-plugin.yaml. Here's a real side-by-side diff:

// BEFORE: .gemini/extensions/code-reviewer/manifest.json
{
  "name": "code-reviewer",
  "version": "1.2.0",
  "description": "Automated code review with style enforcement",
  "gemini_version": ">=2.0.0",
  "entrypoint": "./index.js",
  "permissions": ["read_files", "write_comments"],
  "hooks": {
    "pre_prompt": "./hooks/pre.js",
    "post_response": "./hooks/post.js"
  },
  "skills": ["review", "lint", "suggest"]
}

# AFTER: .antigravity/plugins/code-reviewer/antigravity-plugin.yaml
apiVersion: antigravity.google.dev/v1
kind: Plugin
metadata:
  name: code-reviewer
  version: 1.2.0
  description: Automated code review with style enforcement
spec:
  antigravityVersion: ">=1.0.0"
  entrypoint: ./index.js
  permissions:
    - read_files
    - write_comments
  skills:
    - review
    - lint
    - suggest
  # Hooks are now declared separately in antigravity.config.json
  # See hooks migration below

Key changes: gemini_version → antigravityVersion, the hooks block moves out of the manifest entirely, and the file format switches from JSON to YAML with an apiVersion/kind header (Kubernetes-style).

Porting Custom Hooks

Gemini CLI hooks were defined inside settings.json. Antigravity externalizes them into antigravity.config.json in your project root:

// BEFORE: ~/.gemini/settings.json (hooks section)
{
  "hooks": {
    "pre_prompt": {
      "command": "node ./hooks/pre.js",
      "timeout_ms": 3000
    },
    "post_response": {
      "command": "node ./hooks/post.js",
      "timeout_ms": 5000
    }
  }
}

// AFTER: antigravity.config.json (hooks section)
{
  "$schema": "https://antigravity.google.dev/schemas/config/v1.json",
  "hooks": {
    "onBeforePrompt": {
      "run": "node ./hooks/pre.js",
      "timeoutMs": 3000,
      "failOnError": false
    },
    "onAfterResponse": {
      "run": "node ./hooks/post.js",
      "timeoutMs": 5000,
      "failOnError": true
    }
  }
}

Critical renames: pre_prompt → onBeforePrompt, post_response → onAfterResponse, command → run, timeout_ms → timeoutMs (camelCase throughout). The new failOnError field determines whether a failing hook aborts the agent run — default is false.

Re-registering Subagent Definitions

Subagent definitions that lived in .gemini/subagents/ move to .antigravity/subagents/ with an updated YAML schema. The core fields (name, model, instructions, skills) remain the same but require the apiVersion: antigravity.google.dev/v1 header and kind: Subagent.

# Bulk copy and rename to the right directory structure
mkdir -p .antigravity/subagents
for f in .gemini/subagents/*.yaml; do
  cp "$f" ".antigravity/subagents/$(basename $f)"
done
# Then manually add the apiVersion/kind headers to each file

Step 4: Validate Your Migrated Workflows End-to-End

Don't assume the migration worked — run deliberate validation tests before you decommission Gemini CLI. Start with the simplest possible check, then escalate to your most complex workflows.

Basic Connectivity Check

antigravity run "What is 2 + 2? Reply with just the number."
# Expected: 4

If this fails with a model error, your auth token is stale — re-run antigravity auth login.

Testing Async Multi-Agent Workflows

The async workflow capability is Antigravity's flagship feature. Here's a complete example invoking a ported plugin with two subagents running in the background:

antigravity run --async \
  --plugin .antigravity/plugins/code-reviewer \
  --subagent .antigravity/subagents/linter.yaml \
  --subagent .antigravity/subagents/security-scanner.yaml \
  --output json \
  "Review the files in ./src for code quality and security issues"

Expected structured output (the async job returns a job ID immediately, then you poll or stream results):

{
  "job_id": "ag-job-7f3a2c1d",
  "status": "running",
  "created_at": "2026-06-01T10:22:14Z",
  "agents": [
    { "name": "linter", "status": "running", "progress": 0.42 },
    { "name": "security-scanner", "status": "running", "progress": 0.17 }
  ],
  "stream_url": "https://antigravity.google.dev/jobs/ag-job-7f3a2c1d/stream"
}
# Poll for completion:
antigravity jobs get ag-job-7f3a2c1d --watch

This non-blocking behavior is the core async advantage — your terminal is free while agents run in Antigravity's server-side harness.

Smoke-Testing Hooks and Plugins with --dry-run

antigravity run --dry-run --plugin .antigravity/plugins/code-reviewer "test prompt"
# Output shows which hooks fire, in what order, without executing the model call:
# [dry-run] onBeforePrompt hook: node ./hooks/pre.js → would execute
# [dry-run] Plugin: code-reviewer v1.2.0 → would load
# [dry-run] Model call: gemini-2.5-pro → skipped (dry-run)
# [dry-run] onAfterResponse hook: node ./hooks/post.js → would execute

Common Issues & Fixes

| Error / Symptom | Cause | Fix | |---|---|---| | command not found: gemini | You uninstalled Gemini CLI before updating all scripts | Audit scripts with grep -r "gemini" ~/.bashrc ~/.zshrc ./ and replace with antigravity. Set alias gemini=antigravity temporarily. | | Plugin schema version mismatch: expected v1, got legacy | Extension manifest.json hasn't been converted to antigravity-plugin.yaml format | Add apiVersion: antigravity.google.dev/v1 and kind: Plugin to plugin definition. Rename gemini_version to antigravityVersion. | | 401 Unauthorized on first run after auth login | OAuth scopes on the token don't include antigravity.api — happens with cached browser sessions | Run antigravity auth logout && antigravity auth login in a private browser window to force fresh OAuth consent. | | Async job hangs at 0% indefinitely | First async run requires provisioning a server-side agent container — cold start can take 60–90 seconds | Wait 2 minutes before assuming failure. Run antigravity jobs list to check actual status. If status stays pending beyond 5 min, run antigravity jobs cancel <job_id> and retry. | | Feature from Gemini CLI not present | Google explicitly states no 1:1 feature parity at launch | Check the Antigravity CLI GitHub issues tracker and search for your feature. If it's not there, file a new issue — the team is actively prioritizing based on community demand. |

Error: 'command not found: gemini' after Uninstalling Old CLI

If you removed Gemini CLI before updating your aliases and scripts, any automation that calls gemini will break immediately. Quick fix:

# Temporary alias while you audit your scripts
echo 'alias gemini=antigravity' >> ~/.bashrc && source ~/.bashrc
# Find all references to update permanently
grep -r 'gemini ' ~/.bashrc ~/.zshrc ~/bin/ ./Makefile ./.github/workflows/ 2>/dev/null

Error: Plugin Not Loading — Schema Version Mismatch

This happens when you've moved plugin files to .antigravity/plugins/ but haven't updated the manifest format:

antigravity plugin validate .antigravity/plugins/code-reviewer/antigravity-plugin.yaml
# Outputs specific validation errors with line numbers

Error: Authentication 401 Unauthorized

If you're hitting 401s despite a successful auth login, your token may have been issued before Antigravity access was enabled on your account. Force a token refresh:

antigravity auth refresh --force
antigravity auth status  # Confirm the new token and expiry

Antigravity CLI vs Gemini CLI: What Actually Changed

Beyond the migration mechanics, it's worth understanding what's architecturally different — this shapes how you'll design new workflows going forward.

Performance: The Go Rewrite

Gemini CLI's original implementation had startup latency and memory overhead that developers noticed at scale. The Go rewrite in Antigravity CLI brings faster binary startup, lower memory footprint, and better concurrency handling — particularly relevant when orchestrating multiple subagents that were previously sequential.

Unified Architecture with Antigravity 2.0

The biggest structural change: Antigravity CLI and Antigravity 2.0 (the desktop app) share the same agent harness. When Google ships improvements to core agent capabilities — better planning, improved tool use, new model versions — those improvements hit both the desktop app and your terminal simultaneously. With Gemini CLI, the terminal lagged behind.

Async Background Agent Orchestration

Previously, complex multi-step agent tasks blocked your terminal session. Antigravity CLI offloads these to a server-side harness, returns a job ID immediately, and lets you check in via antigravity jobs get <id> --watch. You can close your terminal entirely and the job continues running.

| Feature | Gemini CLI | Antigravity CLI | |---|---|---| | Runtime | Node.js | Go | | Agent execution | Synchronous, blocking | Async, server-side harness | | Desktop app sync | None | Shared agent harness with Antigravity 2.0 | | Extension format | manifest.json (JSON) | antigravity-plugin.yaml (YAML) | | Config location | ~/.gemini/ | ~/.config/antigravity/ | | Hook definition | settings.json | antigravity.config.json | | Binary name | gemini | antigravity | | Multi-agent orchestration | Manual/sequential | Native async subagent coordination | | Feature parity at launch | Full (mature) | Partial (explicitly noted by Google) |

FAQ

Q: Will my existing Gemini CLI scripts break immediately on June 18, 2026?

Yes, on June 18, 2026, Gemini CLI stops serving requests — it won't be a gradual degradation. Any script, CI job, or alias calling gemini that relies on making model requests will fail with a connection error. Scripts that only call gemini config or other local subcommands may still technically run if the binary is installed, but they'll be useless for any AI interaction. Start auditing your automation now with grep -r 'gemini ' ./ across your repos.

Q: Do enterprise customers need to follow the same migration steps?

No. Enterprise customers using Gemini CLI through Google Workspace or Google Cloud maintain existing access through a separate transition path managed by their Google Cloud admin. Your org's GCP administrator needs to enable the Antigravity API, provision the appropriate IAM roles (roles/antigravity.user), and distribute service account credentials. If you're an enterprise developer waiting for your admin to act, follow up internally now — the June 18 deadline applies to individual/free users, but enterprise transition timelines are negotiated separately.

Q: Is Antigravity CLI open source like Gemini CLI was?

Gemini CLI earned its reputation as a genuine open-source project — 100,000 GitHub stars and 6,000 merged pull requests from hundreds of community contributors. Google has committed to maintaining Antigravity CLI's open-source community heritage. The repository is expected at github.com/google/antigravity-cli. The Go rewrite actually makes community contribution more accessible for systems developers. That said, the server-side agent harness that powers async workflows is a Google-managed cloud service, not open source — only the client binary and plugin SDK are open.