Gemini CLI에서 Antigravity CLI로 마이그레이션하기: 가이드

2026년 5월 19일, Google은 6월 18일에 Free, Pro, Ultra 요금제의 기존 Gemini CLI를 종료한다고 발표했습니다. 이 가이드가 게시된 지 2주 후면 gemini 명령이 요청 처리를 중단합니다. Google 도구를 계속 사용하려면 agy 명령으로 Gemini CLI에서 Antigravity CLI로 마이그레이션해야 합니다. agy는 Go로 제작되어 실행 속도가 수십 배 빠릅니다.

CI 스크립트, 야간 cron 작업, Gemini Code Assist IDE 확장 프로그램 등 Gemini CLI에서 실행 중인 것이 있다면, 이 가이드에서 아무것도 망가뜨리지 않고 저녁 한 번에 마이그레이션하는 방법을 설명합니다.

2026년 6월 18일에 정확히 무엇이 작동을 멈추나요?#

이는 “프로젝트 전체의 완전한 종료”가 아니라 가장 인기 있는 세 요금제의 서비스 중단입니다. 영향을 받는 항목은 다음과 같습니다.

Google Developers Blog의 공식 발표입니다.

대부분의 개인 개발자처럼 Free 요금제를 사용하면서 “하지만 나는 유료 계정이 있는데”라고 생각한다면, API 키가 정확히 어떻게 청구되는지 확인하세요. AI Pro는 Cloud 청구가 아닙니다. 개인 Google AI 구독이며 비활성화됩니다. 유료 프로젝트를 통한 Cloud 청구는 비활성화되지 않습니다.

Google은 왜 Gemini CLI를 종료하나요?#

기존 gemini가 “수백 밀리초” 만에 시작된 이유는 Node.js가 준비되는 데 시간이 걸렸기 때문입니다. 새 agy는 단일 정적 Go 바이너리로 빌드되어 “밀리초” 만에 시작됩니다. 실행할 때마다 CLI를 수백 번 호출하는 CI 및 스크립트에서는 차이가 큽니다.

속도와 그 이유에 관해 Google은 다음과 같이 설명합니다.

Gemini CLI의 주요 기능은 모두 이전되었습니다.

• Agent Skills — .gemini/skills/ 폴더는 이제 .agents/skills/에 있습니다.
• Hooks — 같은 이벤트(PreToolUse, PostToolUse 등)를 사용하며 구문은 거의 바뀌지 않았습니다.
• Subagents — 이전과 동일하게 작동하며 구성이 자동으로 마이그레이션됩니다.
• 확장 프로그램 — Antigravity 플러그인으로 이름이 바뀌었고, 명령 하나로 가져올 수 있습니다.

매끄럽게 마이그레이션되지 않은 항목은 MCP 서버와 .gemini/config.json에 직접 접근하는 기존 스크립트입니다. GitHub 토론에 따르면 일부 사용자는 MCP 구성이 작동하지 않아 수동으로 다시 작성해야 한다고 보고했습니다. 이에 대해서는 아래에서 별도로 다룹니다.

Google은 Gemini CLI 오픈 소스 프로젝트를 종료하지 않습니다.

즉, 프로젝트를 포크해 자체 Gemini API 키로 계속 사용할 수 있습니다. 하지만 이제 Cloud 청구를 이용하는 유료 설정이며, 무료 Code Assist 방식은 종료됩니다.

Antigravity CLI 설치 방법: macOS, Linux, Windows용 명령#

시작하기 전에 간단히 확인해 보세요. 어떤 요금제를 사용하나요? 6월 18일 마감이 적용되지 않는 유료 Cloud 프로젝트를 사용한다면 마이그레이션은 유용하지만 긴급하지는 않습니다. Free/Pro/Ultra 요금제를 사용하고 CLI에서 무언가를 실행 중이라면, 요금제가 아직 활성화되어 있을 때 지금 전환해 같은 작업에서 동작을 비교하세요.

macOS 및 Linux

curl을 사용하는 한 줄 명령:

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

스크립트는 플랫폼을 감지하고 agy 바이너리를 다운로드해 체크섬을 확인한 다음 ~/.local/bin에 저장합니다. 이 폴더가 PATH에 없다면 추가하세요.

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

바이너리가 보이는지 확인하세요.

which agy
agy --version

Windows (PowerShell)

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

바이너리는 C:\Users\[your_name]\AppData\Local\agy\bin에 설치됩니다. 설치 프로그램이 PATH를 자동으로 업데이트하지만, 변수를 다시 불러오려면 새 PowerShell 창을 여세요.

Windows (CMD)

회사 정책으로 PowerShell이 차단된 경우:

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

설치 확인

어떤 OS에서든 설치 후 다음을 실행하세요.

agy doctor

이 명령은 바이너리 버전, 구성 파일의 존재 여부, 인증 상태, antigravity.google에 대한 네트워크 액세스를 확인합니다. Google에 연결할 수 없다면 지역 또는 프록시 문제입니다.

인증

인수 없이 agy를 처음 실행하면 설정 마법사가 시작됩니다.

1. 인터페이스 테마를 선택합니다.
2. 인증 방법을 선택합니다. 개인 계정용 Google OAuth 또는 API 키 중에서 고릅니다.
3. 원한다면 .gemini/의 구성을 바로 가져옵니다.

OAuth를 선택하면 브라우저가 열리고 accounts.google.com으로 리디렉션됩니다. 데이터 공유에 동의해야 합니다. 그 후 CLI를 사용할 수 있습니다.

.gemini에서 .agents로 구성과 플러그인을 마이그레이션하는 방법#

단계별로 살펴보겠습니다.

1. agy plugin import gemini

   어느 폴더에서든 이 명령을 실행할 수 있습니다. 전역 플러그인을 ~/.gemini/에서 ~/.agents/로 마이그레이션합니다. 프로젝트별 플러그인을 마이그레이션하려면 프로젝트 폴더에서 명령을 실행하세요.

2. mv .gemini/skills/ .agents/skills/

   폴더 이름을 직접 바꿔 스킬을 옮기세요. 내부 파일 형식은 같으므로 마크다운을 다시 작성할 필요가 없습니다.

3. agy inspect

   활성화된 플러그인, 스킬, hook, subagent를 보여줍니다. Gemini CLI에서 사용하던 목록과 비교해 누락된 항목이 없는지 확인하세요.

4. agy config --edit

   기본 편집기($EDITOR)에서 구성을 엽니다. 자동으로 가져오지 못한 항목이 있다면 직접 편집하세요.

5. agy doctor

   최종 점검 항목은 바이너리, 인증, 플러그인, 네트워크입니다. 네 항목이 모두 정상이라면 구성 마이그레이션이 완료된 것입니다.

혹시 빠뜨린 항목이 있을 수 있으니 기존 .gemini/ 폴더를 백업용으로 한 달간 그대로 두는 편이 좋겠습니다. Antigravity를 일주일간 사용하고 모든 항목이 있는지 확인한 뒤 삭제할 수 있습니다.

모든 AI 도구의 공통 구성으로 AGENTS.md를 사용한다면 이 파일은 손댈 필요가 없습니다. Antigravity CLI는 Claude Code 또는 Codex와 같은 폴더에서 AGENTS.md를 읽습니다.

어떤 환경 변수를 바꿔야 하나요?#

전체 교체 표:

secret을 전달하는 GitHub Actions가 있다면 Settings -> Secrets -> Actions를 열고 키 이름을 바꾸세요. 값은 그대로 유지됩니다(마이그레이션 중 Google API 키는 바뀌지 않았습니다).

GEMINI_가 있을 만한 모든 위치를 확인하세요.

# 프로젝트 전체에서 언급된 항목 찾기
grep -rn "GEMINI_" . --include="*.yml" --include="*.yaml" --include="*.sh" --include=".env*" 2>/dev/null

# dotfile에서 찾기
grep -nE "GEMINI_" ~/.zshrc ~/.bashrc ~/.bash_profile ~/.config/fish/config.fish 2>/dev/null

변수를 바꾼 뒤 터미널을 다시 시작하고 비밀 값을 출력하지 않는 방식으로 존재 여부를 확인하세요. 셸 추적을 켜거나 키를 로그에 복사하지 마세요. 존재 여부만으로 인증은 입증되지 않으므로 agy doctor를 별도로 확인하세요.

if [ -n "${AV_API_KEY:-}" ]; then
    printf 'AV_API_KEY is set\n'
else
    printf 'AV_API_KEY is missing or empty\n'
fi
agy doctor        # “authorized”가 표시되어야 함

전환 중 흔히 발생하는 문제와 해결 방법#

초기에 발생할 수 있는 문제의 점검 목록:

1. MCP 서버. .gemini/config.json에서 mcp_servers를 사용했다면 agy plugin import gemini 후에도 가져와지지 않을 수 있습니다. agy inspect로 확인하세요. mcp 섹션이 표시됩니다. 비어 있거나 오류가 있으면 agy config --edit로 직접 다시 작성하세요. 형식은 공식 Antigravity 문서의 MCP 섹션에 설명되어 있습니다.

2. 사용자 지정 hook. $GEMINI_API_KEY를 읽는 bash 스크립트를 .gemini/hooks/에 두었다면 작동하지 않습니다. 해당 위치를 찾으세요: bash

   grep -rn "GEMINI_" .agents/hooks/ 2>/dev/null
   

   변수를 바꾸세요.

3. CI/CD. GitHub Actions 또는 GitLab CI에서 gemini 명령을 사용하는 단계를 agy를 사용하도록 변경하세요. 설치 프로그램에 표시되는 바이너리 이름은 다를 수 있으므로 $CLI_CMD 변수를 사용해 추상화하세요.

4. IDE 확장 프로그램. VS Code용 Gemini Code Assist 확장 프로그램은 CLI와 함께 비활성화됩니다. 대체 제품은 별도의 VS Code 포크인 Antigravity IDE 또는 다른 AI 편집기에서 사용하는 AGENTS.md입니다.

5. @[file] 로드. Antigravity CLI 초기 빌드에서는 컨텍스트에 파일을 불러오는 @src/file.ts 명령에 버그가 있었습니다. 최신 버전으로 업데이트하세요: agy update.

중요한 기능이 중단되어 한 시간 안에 해결할 수 없다면, Free 요금제의 임시 해결책으로는 마이그레이션을 별도의 저장소 브랜치에서 준비하는 동안 6월 18일까지 Gemini CLI를 계속 사용하는 방법이 있습니다. 시간 제한은 14일입니다.

6월 18일 이후에도 Google 도구를 계속 사용하는 게 좋을까요?#

주 도구(Claude Code 또는 Codex)가 적합하지 않은 경우 Antigravity 2.0을 보조 옵션으로 고려할 수 있습니다. 장단점을 자세히 살펴보려면 Google Antigravity 2.0 가이드를 참조하세요.

상황에 따라 무엇을 해야 하는지 간단히 정리하면 다음과 같습니다.

15분 만에 마이그레이션하는 체크리스트#

1. Antigravity CLI 설치

   curl -fsSL https://antigravity.google/cli/install.sh | bash (macOS/Linux) 또는 irm https://antigravity.google/cli/install.ps1 | iex (Windows PowerShell).

2. agy를 시작하고 인증

   인수 없이 agy를 실행합니다. OAuth 또는 API 키를 선택하세요.

3. .gemini에서 플러그인 가져오기

   agy plugin import gemini—확장 프로그램을 전역으로 마이그레이션합니다. 프로젝트별 플러그인을 가져오려면 프로젝트 폴더에서 다시 실행하세요.

4. 스킬 이동

   mv .gemini/skills/ .agents/skills/. 파일 내용은 그대로 유지됩니다.

5. 환경 변수 교체

   ~/.zshrc/~/.bashrc와 .env 파일에서 GEMINI_API_KEY → AV_API_KEY, GEMINI_PROJECT_ID → AV_PROJECT_ID, GEMINI_REGION → AV_REGION으로 바꾸세요. 터미널을 다시 시작합니다.

6. 설치 확인

   agy doctor를 실행합니다. 네 항목(바이너리, 인증, 플러그인, 네트워크)이 모두 정상이어야 합니다.

7. 테스트 작업 실행

   agy "write a README for the project in the current folder"—결과가 Gemini CLI에서 얻은 결과와 비슷한지 확인하세요.

8. GitHub Actions / GitLab CI 업데이트

   명령 이름을 바꾸고 secret을 GEMINI_*에서 AV_*로 변경하세요.

9. .gemini/를 백업으로 유지

   모든 것이 작동하는지 확인한 뒤 1–2주 후 삭제할 수 있습니다.

마지막으로, 6월 18일이 모든 프로젝트의 작동 중단을 뜻하지는 않습니다. 무료 채널이 비활성화된다는 뜻입니다. 유료 Cloud API 액세스는 계속 제공되고, Gemini CLI 저장소도 유지되며 포크도 가능합니다. Free 요금제를 사용했다면 6월 18일 전에 결정해야 합니다. 그렇지 않으면 다음 gemini "something" 명령이 인증 오류를 반환합니다.