Antigravity CLI 빠른 시작 — 5분 안에 전환 공식 문서 #

2026-06-18 마감 전에 옮겨야 합니다. npm 패키지가 아니라 단일 Go 바이너리로 배포되며, 명령 이름은 antigravity가 아니라 agy입니다. 기존 GEMINI.md·MCP·Skills를 거의 그대로 인식하므로 환경 자체는 부드럽게 이어집니다.

설치 (1단계)

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

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

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

설치 위치:

• Unix — ~/.local/bin/agy (PATH 추가 필요할 수 있음)
• Windows — %LOCALAPPDATA%\Antigravity\agy.exe

설치 확인·인증 (2단계)

# 설치 확인
agy --version

# 첫 실행 — 인증 안내
agy
# → Google OAuth 또는 Google Cloud Project 중 선택
#   → 브라우저로 로그인 후 인증 코드 입력

OAuth가 일반 개인 사용자에게 가장 간단합니다. 기업 환경이거나 비용 청구가 분리된 GCP 프로젝트를 사용하면 "Google Cloud Project"를 선택합니다.

핵심 슬래시 명령 (REPL 안에서)

설정 파일 위치 (Gemini CLI와 일부 다름)

Extensions → Plugins 자동 마이그레이션

업계 용어를 따라 Extensions가 Plugins로 개명됐습니다. 첫 실행 시 기존 Extensions가 자동으로 변환되지만, 안 되면 수동으로:

agy plugin import gemini

제거 (참고)

rm "$HOME/.local/bin/agy"
rm -rf "$HOME/.cache/antigravity"
# PATH 추가 했다면 ~/.zshrc, ~/.bashrc에서 관련 라인 제거

아래 본문은 옛 gemini 명령 기준의 가이드입니다. 2026-06-18 이후로는 동작이 멈추지만 패턴·개념은 그대로 활용 가능합니다 — REPL 흐름, 파이프 사용, 단축 명령 등 대부분의 사용 패턴은 agy에서도 그대로 적용됩니다. 개념 학습용으로 계속 참고하세요.

1. 왜 Antigravity와 Gemini CLI를 함께 쓰는가? #

Antigravity는 편집기 안의 풀-에이전트, Gemini CLI는 터미널의 명령줄 AI입니다. 두 도구는 같은 모델·같은 설정을 공유하면서도 사용 시점이 다르기 때문에 보완 관계가 만들어집니다.

1.1 함께 쓰면 좋은 이유 5가지

• ✅ 설정 공유 — 둘 다 ~/.gemini/settings.json과 GEMINI.md를 읽습니다. 한 번 작성한 규칙·MCP·권한이 양쪽에서 그대로 적용됩니다.
• ✅ 워크플로 분리 — IDE를 켜기 부담스러운 빠른 질문("이 정규식 뭐 잡아?")은 터미널에서 1초로, 본격 코드 작업은 Antigravity로.
• ✅ 스크립트화·자동화 — Gemini CLI는 셸 파이프(cat foo.log | gemini "에러 원인 분석")와 비대화형 모드를 지원합니다. CI·cron·git hook에 집어넣기 좋습니다.
• ✅ SSH·서버 환경 — 원격 서버나 컨테이너 안에는 IDE가 없으므로 CLI가 유일한 선택지입니다.
• ✅ 비용 효율 — 동일한 무료 티어 할당량을 공유합니다. 가벼운 작업을 CLI로 분담시키면 IDE 세션의 컨텍스트 비용을 아낄 수 있습니다.

1.2 주요 AI 코딩 도구 비교 (제미나이 CLI · 안티그래비티 · 클로드 · 커서 · 코파일럿)

최근 실무에서 함께 자주 거론되는 도구를 같은 관점에서 비교합니다. 각 도구의 정확한 사양은 빠르게 변하므로 큰 흐름 위주로 정리했습니다.

2. 설치 방법 #

Gemini CLI는 Node.js 기반입니다. 시스템에 Node.js 20 이상이 설치되어 있어야 합니다 (없다면 먼저 개발 환경 설치 가이드 — Node.js를 참고).

2.1 npm으로 전역 설치 (권장)

# 전역 설치
npm install -g @google/gemini-cli

# 설치 확인
gemini --version

2.2 한 번만 실행 — npx

설치 없이 바로 한 번만 써보고 싶다면 npx를 쓰세요.

npx @google/gemini-cli

2.3 Homebrew (macOS)

brew install gemini-cli

2.4 인증 (Google 계정 OAuth)

처음 gemini 명령을 실행하면 브라우저가 열리고 Google 계정 로그인을 요구합니다. Antigravity에서 이미 로그인했다면 같은 계정을 사용해 무료 티어 할당량을 공유하세요.

gemini
# → 브라우저 자동 오픈 → Google 계정 선택 → "허용" 클릭
# → 터미널로 돌아오면 대화형 REPL 시작

export GEMINI_API_KEY="your-api-key"

3. 실행 & 기본 사용 #

3.1 대화형 REPL 모드

가장 단순한 사용법입니다. 프로젝트 디렉터리로 이동한 뒤 gemini만 입력합니다.

cd ~/projects/my-data-analysis
gemini

> src/etl.py 코드 리뷰해줘. 메모리 누수 가능성 있는지 봐.
> sales.csv 첫 5행만 보여줘
> pytest 실행 결과 요약해줘

REPL 안에서 자주 쓰는 슬래시 명령입니다.

3.2 단발성 실행 — 파이프와 함께

스크립트나 셸 파이프에서 한 번만 실행하고 결과를 받으려면 인자로 프롬프트를 직접 전달합니다.

# 직접 프롬프트 전달
gemini "이 파이썬 함수의 시간 복잡도 알려줘: def f(n): return [i*i for i in range(n)]"

# 표준 입력으로 파일 내용 전달
cat error.log | gemini "에러 원인을 한국어로 요약해줘. 가장 가능성 높은 원인 3개"

# git diff 결과를 코드 리뷰 시키기
git diff main...HEAD | gemini "이 PR을 보안 관점에서 검토해줘"

# 출력을 파일로 저장
gemini "REST API 모범 사례를 마크다운 표로 정리" > api-best-practices.md

3.3 자주 쓰는 옵션

4. Antigravity와의 시너지 활용 패턴 #

두 도구가 같은 설정·같은 모델·같은 계정을 공유한다는 점이 시너지의 핵심입니다. 아래 5가지 패턴이 가장 즉시 효과를 봅니다.

4.1 같은 GEMINI.md로 일관된 행동

워크스페이스 루트의 GEMINI.md에 정의한 규칙(예: "한국어 응답", "matplotlib import 시 koreanize_matplotlib 먼저")이 Antigravity와 Gemini CLI 양쪽 모두에서 자동 적용됩니다.

# 프로젝트 컨벤션

- 한국어로 응답하되, 코드 주석·변수명은 영어
- pandas import 시 한국어 컬럼명을 사용한다면 인덱스 정렬 명시
- 차트 작성 시 koreanize_matplotlib을 import 순서 맨 앞에

위 규칙은 IDE에서 코드 작성 중에도, 터미널에서 gemini "이 데이터 시각화 코드 만들어줘" 했을 때도 동일하게 적용됩니다. 한 번 정의 → 두 도구 자동 공유.

4.2 같은 MCP 서버 공유

~/.gemini/settings.json의 mcpServers 블록은 두 도구가 모두 사용합니다. GitHub MCP를 한 번 설정하면 Antigravity에서도, gemini CLI에서도 PR 조회·이슈 작성을 동일하게 호출할 수 있습니다.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
      }
    }
  }
}

4.3 역할 분담 — IDE는 작성, CLI는 검증

Antigravity에서 작성한 코드를 git commit 직전에 CLI로 한 번 더 검증하는 패턴입니다.

# .git/hooks/pre-commit (실행 권한 필요)
#!/usr/bin/env bash
diff=$(git diff --cached)
if [ -z "$diff" ]; then exit 0; fi

review=$(echo "$diff" | gemini --prompt "이 변경에서 보안 이슈·논리 오류만 짚어줘. 없으면 '문제 없음'만 출력")

if echo "$review" | grep -q "문제 없음"; then
  exit 0
else
  echo ">>> Gemini 리뷰 결과:"
  echo "$review"
  read -p "그래도 커밋할까요? (y/N): " ok
  [ "$ok" = "y" ] || exit 1
fi

Antigravity로 만든 코드 → git add → 커밋 시도 → CLI가 자동으로 한 번 더 검토 → 사용자 결정. 두 번째 의견(second opinion)을 자동화한 사례입니다.

4.4 빠른 일회성 작업은 CLI로 토큰 절약

"이 정규식이 어떤 패턴을 잡지?", "1GB CSV 첫 100행만 보여줘" 같은 단순 질문을 IDE 세션에 넣으면 그 컨텍스트가 이후 대화 내내 따라다닙니다. 이런 자투리 질문은 CLI에서 끝내고 IDE 세션은 본 작업에 집중시키세요.

# 나쁨 — 세션이 길어질수록 비용 증가
[Antigravity 채팅] "정규식 ^\d{3}-\d{4}$ 의미가 뭐야?"

# 좋음 — 터미널에서 단발 처리
$ gemini "정규식 ^\d{3}-\d{4}$ 의미가 뭐야?"

4.5 SSH·CI 환경에서의 단일 인터페이스

Antigravity는 데스크톱 앱이라 원격 서버에서 직접 쓸 수 없습니다. 하지만 CLI는 SSH로 접속한 서버에서도 똑같이 동작하므로, 로컬·원격에서 같은 모델·같은 규칙으로 작업할 수 있습니다.

• SSH 서버에서 로그 분석: tail -n 1000 /var/log/app.log | gemini "5xx 패턴 추출"
• CI 워크플로: GitHub Actions에서 gemini --prompt "테스트 실패 요약"으로 PR 코멘트 자동 생성
• 도커 컨테이너 디버깅: docker exec ... bash -c 'gemini "왜 이 컨테이너가 OOM 나?"'

5. 트러블슈팅 #