# How do you migrate from Gemini CLI to Antigravity CLI?

Canonical: https://clawdocx.com/docs/antigravity-migrate-from-gemini-cli
Author: Theo Marsh
Difficulty: INTERMEDIATE
Published: 2026-02-24
Updated: 2026-10-05

> Gemini CLI stopped serving free, Pro and Ultra users on June 18, 2026. Install agy, import your extensions, move your skills and rewrite your MCP config.

Install the Antigravity CLI, run `agy` once inside a project that still carries Gemini CLI configuration, and accept the checklist it offers: that is the whole automatic part of the migration. Three things it does not do for you, and they are the three that break a working setup: converting extensions into plugins with `agy plugin import gemini`, relocating workspace skills from `.gemini/skills/` to `.agents/skills/`, and moving MCP servers out of `settings.json` into `mcp_config.json` with `serverUrl` in place of `url`. If your organisation holds a Gemini Code Assist Standard or Enterprise licence, or you drive Gemini CLI with a paid API key, you do not have to move at all.

## Do you have to migrate at all?

Google announced the transition on May 19, 2026, in a post by Dmitry Lyalin and Taylor Mullen on the Google Developers Blog. The sentence that decides it for consumers reads: "On June 18, 2026, Gemini CLI and Gemini Code Assist IDE extensions will stop serving requests for Google AI Pro and Ultra, as well as those using it free of charge using Gemini Code Assist for individuals."

Enterprise access was carved out in the same post: "If your organization uses Gemini CLI or our IDE extensions via a Gemini Code Assist Standard or Enterprise license, or if your organization uses Gemini Code Assist for GitHub through Google Cloud, your access remains unchanged." It adds that "Gemini CLI will remain accessible via paid Gemini and Gemini Enterprise Agent Platform API keys."

| How you use Gemini CLI | What happened on June 18, 2026 | What to do |
|---|---|---|
| Free Gemini Code Assist for individuals | Requests stopped being served | Migrate to Antigravity CLI |
| Google AI Pro or Ultra subscription | Requests stopped being served | Migrate to Antigravity CLI |
| Gemini Code Assist Standard or Enterprise licence | Access unchanged | Nothing required |
| Paid Gemini or Gemini Enterprise Agent Platform API key | Remains accessible | Nothing required |
| Gemini Code Assist for GitHub through Google Cloud | No new installations on GitHub organizations; Google said requests would stop being served "in the following weeks" | Plan a move |

That last row is the one worth reading twice. Google gave a hard date for new installations and a vaguer one for existing requests, so if you still have the GitHub app on an organisation, treat it as already gone rather than as still supported.

## What carries over, and what does not?

Google's framing is that "Antigravity CLI keeps the most critical features of Gemini CLI: Agent Skills, Hooks, Subagents, and Extensions (now as Antigravity plugins)", while admitting "there won't be 1:1 feature parity right out of the gate". The migration page is more specific about what moves itself.

| What | Gemini CLI | Antigravity CLI | Moves itself? |
|---|---|---|---|
| Extensions | `gemini extensions install` | Plugins | No: run `agy plugin import gemini` |
| Global configuration | `~/.gemini/` | Converted on first run | Yes, if you accept the checklist |
| Session tokens | Gemini CLI's own store | Operating system keyring | Yes, on first run |
| Workspace skills | `.gemini/skills/` | `.agents/skills/` | No: move the folder yourself |
| Global skills | `~/.gemini/skills/` | `~/.gemini/antigravity-cli/skills/` | No |
| MCP servers | Inline in `~/.gemini/settings.json` | `~/.gemini/config/mcp_config.json` or `.agents/mcp_config.json` | No |
| Context files | `GEMINI.md`, `AGENTS.md`, `~/.gemini/GEMINI.md` | Same files, same places | Nothing to do |
| Terminal themes and visual overlays | Yours | May be gone | No |

On that last row, the migration page's own note says: "While Antigravity CLI preserves support for workspace skills, rules, and MCP servers, certain customized terminal themes or experimental visual overlays from Gemini CLI might not be supported." That is a "might", not a list, so budget time to rebuild a heavily themed terminal rather than expecting a specific breakage.

## How do you install the Antigravity CLI?

Google's installation page says the CLI "runs natively on macOS, Linux, Googlebook, and Windows".

On macOS, Linux and Googlebook, the installer puts the executable at `~/.local/bin/agy`:

```bash
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows the binary is registered to `C:\Users\<username>\AppData\Local\agy\bin`. In PowerShell:

```powershell
irm https://antigravity.google/cli/install.ps1 | iex
```

In a standard Command Prompt:

```bat
curl -fsSL https://antigravity.google/cli/install.cmd -o install.cmd && install.cmd && del install.cmd
```

Two flags are worth knowing before you run any of them, because both scripts edit your shell profile by default:

- `--skip-aliases` stops the script purging or updating legacy `agy` or `antigravity` shell aliases.
- `--skip-path` stops it appending to your shell profile's PATH.

If you manage dotfiles in version control, pass both and add `~/.local/bin` to PATH yourself.

## What happens the first time you run agy?

Run `agy` in a directory that already has Gemini CLI configuration and the CLI detects your existing profiles, then offers an interactive checklist. Google's migration page describes three things on it:

1. **Auto-conversion.** You pick which extensions and global configurations to convert.
2. **Keyring storage.** Active session tokens move into your operating system's native keyring.
3. **Settings alignment.** Default visual parameters and rendering buffers map to the new settings profile.

The checklist is a one-time prompt tied to finding legacy configuration, so run it on a machine that still has your Gemini CLI setup intact. On a clean machine there is nothing to detect and nothing to offer.

## How do you turn extensions into plugins?

Extensions are the one concept that changed name. Google's reasoning on the migration page is blunt: "Since Gemini CLI launched, the industry has standardized on the term plugins." The conversion is one command:

```bash
agy plugin import gemini
```

It searches your legacy local directories, parses your extension manifests, and converts the files into native layout blocks. The documented output looks like this, and it is worth reading line by line rather than scrolling past:

```text
[ok] conductor-tools
  - skills       : skipped (none detected)
  - agents       : skipped (none detected)
  ✔ commands     : 4 legacy commands converted to skills
  - mcpServers   : skipped (none detected)
[ok] google-workspace
  ✔ skills       : 5 skills processed
  - agents       : skipped (none detected)
  ✔ commands     : 2 legacy commands converted to skills
  ✔ mcpServers   : 1 server definition migrated to mcp_config.json
```

Two details in that output matter later. Legacy commands become skills, so a custom command you typed as `/deploy` arrives as a skill of the same name. And an extension that bundled an MCP server has its server definition written into `mcp_config.json` for you, which means the manual MCP work below applies to the servers you configured yourself, not to the ones that came in with an extension.

Imported plugins land at `~/.gemini/antigravity-cli/plugins/<plugin_name>/`. Each one needs a `plugin.json` at its root, and the CLI is stricter here than the desktop app: Google's plugin reference lists `name` as required when you manage plugins with Antigravity CLI commands, where Antigravity 2.0 and the IDE fall back to the folder name. Check what arrived with:

```bash
agy plugin list
```

The same subcommand family handles `install`, `disable`, `enable` and `uninstall`, so a plugin that imported badly can be removed without touching the filesystem.

## Where do your skills have to move to?

Skills are where a migration quietly half-works, because the CLI finds global skills in a new place and workspace skills in a folder you have to rename.

| Scope | Gemini CLI | Antigravity CLI |
|---|---|---|
| Workspace | `.gemini/skills/` | `<workspace-root>/.agents/skills/<skill-folder>/` |
| Global | `~/.gemini/skills/` | `~/.gemini/antigravity-cli/skills/<skill-folder>/` |
| From a plugin | Bundled in an extension | `~/.gemini/antigravity-cli/plugins/<name>/skills/` |

Google's instruction for the workspace case is explicit: "If your project contains custom workspace skills defined in `.gemini/skills/`, you must manually rename or relocate the folder to `.agents/skills/` for the Antigravity agent to recognize them as active slash commands."

There is a shortcut nobody tells you about on that page. Gemini CLI's own Agent Skills documentation already lists `.agents/skills/` as an alias it reads, alongside `~/.agents/skills/` for user scope, and says that "within the same tier (user or workspace), the `.agents/skills/` alias takes precedence over the `.gemini/skills/` directory". So if you had already adopted the interoperable path in Gemini CLI, your workspace skills are where Antigravity CLI expects them and there is nothing to move. Check before you start renaming folders:

```bash
ls -d .agents/skills .gemini/skills 2>/dev/null
```

Once the folder is in the right place, every skill becomes a slash command again without any extra step. Google's skills page states that the CLI "automatically converts it into a slash command inside the interactive TUI", so a skill named `deploy-staging` is `/deploy-staging` in the prompt box. If you want the wider picture of how skill folders are laid out, see [Understanding Skills](/docs/skills-explained) and the [Agent Skills hub](/ai-agents/agent-skills).

## How do you rewrite your MCP configuration?

This is the step most likely to leave you staring at a server that will not connect. Gemini CLI declared MCP servers inline inside `~/.gemini/settings.json`. Antigravity CLI pulls them out into a file of their own:

- Global servers: `~/.gemini/config/mcp_config.json`
- Workspace servers: `.agents/mcp_config.json`

Then there is the key rename. Google's MCP page puts it as a hard requirement: "When declaring remote SSE, Streamable HTTP, or WebSocket-based MCP connections, you must define the `serverUrl` field. Legacy fields like `url` or `httpUrl` aren't supported."

So a remote server that read like this under Gemini CLI:

```json
{
  "mcpServers": {
    "remote-indexer": {
      "url": "https://mcp.internal.enterprise.com/sse"
    }
  }
}
```

becomes this, in `mcp_config.json`:

```json
{
  "mcpServers": {
    "remote-indexer": {
      "serverUrl": "https://mcp.internal.enterprise.com/sse",
      "env": {
        "AUTH_TOKEN": "secure_alpha_token"
      }
    }
  }
}
```

Local stdio servers keep `command`, `args`, `env` and `cwd`, so they usually survive a copy and paste. The documented optional properties are `args`, `env`, `cwd`, `headers`, `authProviderType`, `oauth`, `disabled` and `disabledTools`, and each entry must carry exactly one transport: `command` for stdio or `serverUrl` for a remote server.

Once the file is in place, type `/mcp` in the prompt panel to open the interactive MCP manager, which shows live status rings for active, disconnected and loading servers and lets you reload configurations or read connection logs. That is the fastest way to find out whether a rename took. For background on the protocol itself, see the [MCP hub](/ai-agents/mcp).

## Do GEMINI.md and AGENTS.md still work?

Yes, and this is the one part of a Gemini CLI setup you can leave completely alone. The migration page says both CLIs "use identical workspace context rules" and that "no modifications are needed to your existing rule documents". The agent keeps parsing `GEMINI.md` and `AGENTS.md` in your active directory, and keeps consulting `~/.gemini/GEMINI.md` for global constraints.

Workflows are the exception in the other direction: they are a separate deprecation with its own deadline, and converting them is a different job from this migration. See [Antigravity workflows retire on November 1, 2026](/blog/antigravity-workflows-to-skills).

## How do you sign in when there is no browser?

On a laptop, signing in is invisible: the CLI reads your operating system keyring, which Google names as Apple Keychain, Linux Secret Service over D-Bus, or Windows Credential Manager, and authenticates silently if a valid token profile is there. With no saved session it opens your default browser.

Over SSH the CLI detects the remote environment and prints an authorization URL instead. You open it on your local machine, sign in, copy the alphanumeric code the browser shows, and paste it back into the remote prompt.

For CI, where there is no browser at all, use a Gemini API key. Two steps, and the order does not matter but both are required. Set the provider in `~/.gemini/antigravity-cli/settings.json`:

```json
{
  "modelProvider": "gemini"
}
```

Then export the key:

```bash
export GEMINI_API_KEY="your-api-key"
```

Google's installation page is unusually direct about the failure modes here, and they are the ones that cost an afternoon:

- Setting `GEMINI_API_KEY` on its own has no effect. Without `modelProvider`, the CLI signs in to an account and ignores the key.
- A key supplied through `GOOGLE_API_KEY`, or in a `.env` file, is not read. The CLI reads the credential only from `GEMINI_API_KEY` in the environment.
- `gemini` is the only accepted value for `modelProvider`. An unrecognised value is ignored and the CLI signs in normally.
- The CLI checks only that the key is non-empty at startup, so an invalid or revoked key surfaces as a generic model error on your first conversation rather than at launch.
- With a key in use, `/logout` does nothing, because there is no stored session to clear.

If you need to go back to account authentication, remove `modelProvider` from the settings file and restart. Do not unset `GEMINI_API_KEY` while `modelProvider` is still set to `gemini`: Google's note says the CLI cannot start in that state.

## Where Google's own pages disagree

One sentence on the migration page is at odds with the table printed directly beneath it. The prose says "while global shared skills remain in your user home directory, the target folder path for local workspace-specific skills has been updated", which reads as though only the workspace path changed. The table on the same page then gives the global path as `~/.gemini/skills/` for Gemini CLI and `~/.gemini/antigravity-cli/skills/` for Antigravity CLI, which is a change too.

This guide follows the table, for two reasons. The table is specific where the prose is general, and Google's separate Agent Skills page independently lists `~/.gemini/antigravity-cli/skills/<skill-folder>/` as the CLI's global location. Both are literally true if you read "remain in your user home directory" as meaning "still somewhere under `~`", but if you read it as "unchanged" you will leave your global skills in a folder the CLI no longer scans.

One date worth noting while you read both sites: the Gemini CLI documentation page cited here carries a "Last updated: Apr 30, 2026" line, which puts it before the May 19 transition announcement. Treat it as an accurate description of Gemini CLI and not as a statement about what Antigravity CLI does.

## What to check once you are done

Work through this in the project you migrated first, before you repeat it anywhere else:

1. `agy plugin list` shows every extension you expected, with its skills.
2. `/mcp` shows each server with an active status ring, not a disconnected one.
3. Typing `/` in the prompt box offers the slash commands you used to have, including the ones that were legacy commands before the import.
4. A prompt that used to trigger a workspace skill still triggers it, which confirms the folder is in `.agents/skills/` rather than `.gemini/skills/`.
5. Your `GEMINI.md` rules are still being honoured, which you can test by asking the agent to restate a constraint you wrote there.

Keep the old `~/.gemini/skills/` folder until all five pass. Nothing in the migration deletes it, and it is the cheapest rollback you have. For what else the platform supports, including hooks, subagents and the SDK, the [Antigravity platform hub](/ai-agents/antigravity) tracks the current state.

## Frequently asked questions

**Do I have to stop using Gemini CLI?**

Not if you pay for it a particular way. Google's announcement says Gemini CLI stopped serving Google AI Pro and Ultra users, and people on the free Gemini Code Assist for individuals, on June 18, 2026. Organisations on a Gemini Code Assist Standard or Enterprise licence keep unchanged access, and Google says Gemini CLI remains accessible through paid Gemini and Gemini Enterprise Agent Platform API keys.

**Does the migration move everything for me?**

No. The first run of agy offers to convert your extensions and global configuration and to move your session tokens into your operating system keyring. Converting extensions into plugins, relocating workspace skills to .agents/skills/, and rewriting MCP servers into mcp_config.json are separate steps you run yourself.

**What happens to my GEMINI.md file?**

Nothing. Google's migration page says the agent still parses GEMINI.md and AGENTS.md in your working directory, and still consults the global file at ~/.gemini/GEMINI.md. There is no rename and no conversion step for context files.

**Why did my MCP servers stop connecting after the move?**

Most likely the URL key. Antigravity CLI reads remote servers from a serverUrl field, and its MCP page states that legacy url and httpUrl fields are not supported. Move each server out of settings.json into ~/.gemini/config/mcp_config.json or .agents/mcp_config.json and rename the key.

**Where do my global skills end up in the CLI?**

In ~/.gemini/antigravity-cli/skills/. That is the path both Google's GCLI migration table and its Agent Skills page give for the Antigravity CLI, and it is a different directory from the ~/.gemini/config/skills/ path that Antigravity 2.0 and the Antigravity IDE use.

**Can I run the CLI in CI, where there is no browser to sign in with?**

Yes, with a Gemini API key. Set modelProvider to gemini in ~/.gemini/antigravity-cli/settings.json and export GEMINI_API_KEY in the environment. Google's installation page is explicit that setting GEMINI_API_KEY on its own has no effect, and that a key supplied through GOOGLE_API_KEY or a .env file is not read.

## Sources

- [Antigravity docs: Migrating from Gemini CLI](https://antigravity.google/docs/cli/gcli-migration)
- [Google Developers Blog: An important update: Transitioning Gemini CLI to Antigravity CLI](https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/)
- [Antigravity docs: Installation and auth](https://antigravity.google/docs/cli/install/)
- [Antigravity docs: Model Context Protocol (MCP)](https://antigravity.google/docs/mcp/)
- [Antigravity docs: Agent skills](https://antigravity.google/docs/skills/)
- [Antigravity docs: Plugins](https://antigravity.google/docs/plugins/)
- [Antigravity changelog](https://antigravity.google/docs/changelog/)
- [Gemini CLI docs: Agent Skills](https://geminicli.com/docs/cli/skills/)
- [Gemini CLI docs: Extensions](https://geminicli.com/docs/extensions/)