Gemini CLI to Antigravity CLI migration for QA is not a copy-and-launch exercise. A migration can report success while a workspace skill loads from the wrong path, a remote MCP server keeps an obsolete URL field, a hook is missing, an extension command changes shape, or the target CLI uses different authentication and permission state.

Google announced that Gemini CLI stopped serving Google AI Pro, Google AI Ultra, and free-tier individual accounts on June 18, 2026, while describing enterprise users with Gemini Code Assist licenses and API-key authentication as unaffected. Google now directs affected terminal users to Antigravity CLI. This tutorial builds a disposable migration lab that proves a small QA workflow before any team changes its shared profile or CI runner.

What Google officially documents

The official Gemini CLI transition announcement says Antigravity CLI can detect an existing Gemini CLI directory and migrate skills, MCP servers, agents, and compatible memory files. Account eligibility still matters, so record the authentication path rather than assuming every Gemini CLI user has the same outcome.

Google’s current migration guide documents automatic first-launch conversion and the explicit agy plugin import gemini command. It also documents partial parity: some customized terminal themes or experimental visual overlays may not be supported.

The same guide keeps GEMINI.md and AGENTS.md context rules, but changes important locations. Global skills move from ~/.gemini/skills/ to ~/.gemini/antigravity-cli/skills/; workspace skills move from .gemini/skills/ to .agents/skills/. MCP servers leave Gemini CLI’s settings.json and move into a dedicated global or workspace mcp_config.json. Remote url or httpUrl keys become serverUrl.

Build a disposable migration lab

Create a private repository with synthetic data and one deterministic smoke-test command. Do not begin with a production profile or real credentials. The lab should contain:

  • a GEMINI.md rule that requires evidence IDs in every report;
  • a nested AGENTS.md rule for one test-fixture directory;
  • a small Gemini CLI extension with one namespaced smoke-planning command;
  • one workspace skill that summarizes a frozen test report;
  • one benign hook that writes a correlation marker inside the lab only;
  • one isolated MCP server exposing a read-only synthetic test-status tool; and
  • a deterministic script that validates the expected output schema and repository state.

Use secret canaries such as NOT_A_REAL_TOKEN, never live keys. The migration must not send data to production systems or modify files outside the disposable workspace.

Step 1: freeze the source identity

Before launching Antigravity CLI, capture a source manifest:

  • Gemini CLI build, operating system, shell, and installation source;
  • authentication method and account class without recording tokens;
  • repository URL, branch, commit SHA, and clean Git status;
  • hashes of settings.json, context files, extension manifests, skill files, hooks, and MCP configuration;
  • extension names, enabled state, commands, hooks, agents, skills, and MCP servers;
  • expected permission prompts and denied actions;
  • the deterministic smoke-test command, fixture hash, and expected result; and
  • a backup location and rollback owner.

Store only redacted configuration evidence. Hash secret-bearing files rather than copying their values into a report.

Step 2: define behavioral acceptance criteria

Write the migration contract before conversion:

Given a frozen Gemini CLI workflow and synthetic test fixture, Antigravity CLI must discover the intended context, plugin, skill, hook, agent, and MCP components; preserve the required safety decision; produce the same normalized QA evidence; and leave no unapproved filesystem, process, network, Git, or remote side effect.

Component Acceptance evidence Failure signal
Context rules Evidence IDs and nested rule appear in output Missing or wrong-scope instruction
Extension to plugin Expected components and command are listed Skipped, duplicated, or renamed behavior
Workspace skill Skill is discovered from .agents/skills Only legacy path works
MCP server One read-only tool returns the frozen fixture Schema, endpoint, auth, or permission error
Hook Exactly one scoped marker with correlation ID No marker, duplicate, or external write
Smoke test Normalized deterministic result matches baseline Changed tests hidden by plausible prose

Step 3: test first-launch automatic migration

Clone the frozen source profile into an isolated test account or disposable home directory. Launch agy for the first time and record every migration option shown. Select only the components in the approved test manifest.

Capture the target inventory immediately after onboarding. Compare component names, counts, hashes where formats remain identical, enabled states, and skipped items. If the screen says a component was skipped, record the reason; do not silently remove it from the acceptance matrix.

Inspect generated files before invoking any migrated tool. A converted plugin should have a required plugin.json plus only the expected optional skills, agents, rules, hooks, and MCP definitions. Flag unexpected executables, broad permissions, network targets, or secret values.

Step 4: test explicit extension import

Use a second clean target profile for the documented explicit path:

agy plugin import gemini
agy plugin list

Save standard output and standard error separately. Parse the import summary into expected, converted, skipped, and failed component counts. Then compare this result with automatic onboarding. The same source extension should not produce materially different active behavior without a documented reason.

Run the import a second time. The repeated trial must not create duplicate commands, hooks, skills, agents, or MCP servers. If the command is not idempotent, require a documented cleanup and rollback step before team use.

Step 5: verify context and skill paths

Start with the existing GEMINI.md and AGENTS.md files unchanged, as Google’s migration guide says both remain supported. Ask for a report from the repository root and then from the nested fixture directory. Confirm the expected root and nested evidence requirements apply in the right scope.

Next, test the path change deliberately:

  1. leave one workspace skill only under .gemini/skills/ and prove the target does not incorrectly pass the final discovery check;
  2. move the reviewed skill to .agents/skills/;
  3. restart or reload using the supported target workflow;
  4. confirm exactly one skill or slash command appears; and
  5. run it against the frozen test report and validate the output schema.

For global skills, verify the Antigravity-specific global directory. Do not copy every historical skill blindly; review scripts, references, and permissions before activation.

Step 6: migrate MCP configuration safely

Convert the isolated server definition from the legacy inline setting into mcp_config.json. Use the documented scope:

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

For a remote SSE or WebSocket fixture, replace legacy url or httpUrl with serverUrl. Then validate JSON shape, server identity, command or endpoint, environment-variable names, startup timeout, tool inventory, and the read-only response.

Test wrong-key, missing-key, malformed JSON, unavailable server, TLS failure, expired synthetic credential, duplicate server name, unexpected extra tool, and revoked permission cases. A model-generated statement that the server is connected is not enough; compare the visible tool inventory and the fixture response with independent server logs.

Step 7: validate plugins, commands, hooks, and agents

Google’s plugins and skills guide describes plugins as bundles that can contain skills, agents, rules, MCP definitions, and event hooks. Treat every component as executable supply-chain input.

Run one positive and one negative case for each migrated component. The smoke command should accept valid arguments and reject malformed or injected input. The hook should create one local marker for the intended event and none for a non-matching event. The agent should follow the synthetic evidence contract without editing files. Disabled components must remain disabled after restart.

Scan the target plugin directory and logs for the secret canary. Verify file permissions, unexpected downloads, child processes, network connections, Git status, and remote state independently.

Step 8: test authentication and permissions separately

Do not treat migration of configuration as migration of entitlement. Record whether the source user was on an individual account, Gemini Code Assist enterprise license, Google Cloud path, or approved API-key authentication. Verify the target login and quota path using official account screens or supported read-only commands without storing tokens.

Capture the effective target permission and sandbox state before the first tool call. Exercise an allowed read, an approval-required local marker, and a denied outside-workspace write. The outcome must match the reviewed matrix. If the imported workflow gains broader access, stop the rollout even when the smoke test passes.

Step 9: exercise failure, interruption, and rollback

Reliable migration testing includes:

  • missing legacy profile and empty profile;
  • malformed extension manifest and unsupported component;
  • duplicate plugin or skill name;
  • partial import followed by restart;
  • interrupted import and low-disk simulation in a disposable environment;
  • renamed workspace and changed repository path;
  • stale context, disabled hook, and unreachable MCP endpoint;
  • wrong authentication class and denied permission;
  • repeated import, downgrade, and clean uninstall; and
  • restoration of the preserved legacy profile.

Rollback should restore the source configuration without merging target-generated files into it. Hash the restored profile and rerun the deterministic source smoke test. Keep both CLIs isolated during comparison so one cannot mutate the other’s evidence.

Step 10: compare normalized results, not prose

Model wording may change across harnesses and models. Compare a small normalized contract instead:

{
  "case_id": "MIGRATION-QA-01",
  "fixture_hash": "reviewed-value",
  "tests_total": 4,
  "tests_failed": 1,
  "evidence_ids": ["E1", "E2"],
  "recommended_next_check": "fixture-date-boundary"
}

Validate required fields, types, evidence links, and deterministic totals. A fluent explanation cannot compensate for missing tools, changed guardrails, or a different test result.

Migration evidence matrix

Risk Test Independent proof
False parity Automatic and explicit import Source-target component diff
Skill not found Legacy and new workspace paths Discovery inventory and invocation
MCP drift Config split and URL-key conversion Tool list plus server log
Duplicate behavior Run import twice Unique component and hook counts
Privilege expansion Read, ask, and deny canaries Filesystem, process, and network state
Secret leakage Canary scan Redacted artifact and log inventory
Output regression Frozen smoke fixture Schema validator and test runner
Failed rollback Restore preserved source profile Hash and baseline rerun

Screenshot plan

Capture the official transition notice, source inventory and hashes, first-launch migration choices, explicit import summary, generated plugin layout, context-rule proof, workspace skill before and after relocation, MCP configuration diff with secrets redacted, plugin and tool inventories, permission canaries, deterministic source-target results, negative-case failure, rollback verification, and final human approval gate.

Final checklist

  • Confirm the account and authentication path affected by the transition.
  • Use a disposable profile and synthetic fixtures.
  • Freeze source builds, identities, inventories, hashes, and expected behavior.
  • Test automatic onboarding and explicit plugin import independently.
  • Record every converted, skipped, failed, and unsupported component.
  • Verify GEMINI.md and AGENTS.md scope.
  • Move workspace skills to .agents/skills/ and validate discovery.
  • Split MCP configuration and replace remote URL keys correctly.
  • Test plugins, commands, hooks, agents, permissions, and authentication separately.
  • Run duplicate, partial, malformed, restart, and rollback cases.
  • Scan evidence for secrets and check side effects independently.
  • Compare normalized deterministic results, not model prose.
  • Keep shared-profile, CI, defect, merge, and release decisions human-owned.

Conclusion

Antigravity CLI provides documented migration paths for Gemini CLI workflows, but compatibility must be demonstrated at the behavior boundary. Freeze the source, migrate in isolation, verify every component and permission, test the path and schema changes Google documents, compare deterministic evidence, and prove rollback. That turns a tool transition into a controlled QA change instead of a hopeful import.