Antigravity CLI (agy) — 터미널 에이전트 종합 가이드

1. 왜 신규 CLI가 필요했나? #

Google이 Gemini CLI에서 갈아탄 이유는 명확합니다.

• Go 기반 단일 바이너리 — Node.js·npm 의존성이 없어 시작이 더 빠르고 설치도 단순.
• 비동기·다중 에이전트 — 백그라운드 subagent를 기본 지원. 사용자가 다른 작업을 하는 동안 여러 에이전트가 동시에 진행 가능.
• 데스크톱과 같은 하네스 — Antigravity 2.0 데스크톱·SDK가 모두 같은 에이전트 엔진을 공유. 한곳에서 만든 Skill·MCP·Hooks가 모두에서 동작.
• 스케줄링 1급 지원 — /schedule로 일회성·반복 작업을 터미널에서 직접 등록.
• 플러그인 시스템 — Gemini CLI의 Extensions를 그대로 가져와 그 위에 신규 도구를 얹을 수 있음.

2. 설치 & 인증 #

2.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

2.2 설치 위치 & PATH

agy --version

2.3 인증 — 첫 실행 시 안내

agy
# → 인증 방식 선택:
#    1) Google OAuth (개인 사용자 권장)
#    2) Google Cloud Project (조직·비용 분리)
#  → 브라우저 자동 오픈 → 코드 복사 → 터미널에 붙여넣기

OAuth가 일반 사용자에게 가장 단순합니다. GCP 프로젝트는 비용 청구·감사 로그가 조직 단위로 필요한 환경에서 선택합니다.

3. 첫 실행 — TUI 구조 익히기 #

아무 프로젝트 폴더에서 agy를 입력하면 다음 구성의 TUI(Text-based UI)가 뜹니다.

• 대화 패널 — 스크롤 가능한 메시지 히스토리
• 입력 줄 — > 프롬프트. 자연어와 /명령 모두 입력 가능
• 상태 바 — 활성 모델·토큰 사용량·동작 중인 subagent 수 실시간 표시

가장 단순한 첫 대화

$ agy
> 이 디렉터리에 어떤 파일이 있는지 트리로 보여줘

> src/utils.py 함수 목록을 표로 정리해줘

> /quit       # Ctrl+D도 동일

비대화형 단발 실행 — 파이프 사용

# 직접 프롬프트 전달
agy "이 정규식 의미가 뭐야: ^\d{3}-\d{4}$"

# 표준 입력에 파일 내용 전달
cat error.log | agy "이 로그의 가장 가능성 높은 원인 3개를 한국어로"

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

4. 슬래시 명령 모음 #

REPL 안에서 /로 시작하는 명령들입니다. 공식 문서에 정리된 대표 명령:

4.1 기본 명령

4.2 작업 실행 명령

4.3 도구·환경 명령

5. 플러그인 · Subagent #

5.1 플러그인 — Extensions 후속

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

# Gemini CLI Extensions를 Antigravity 플러그인으로 변환
agy plugin import gemini

# 플러그인 목록 확인
agy plugin list

# REPL 안에서도 가능
> /plugins

5.2 Subagent — 백그라운드 병렬 에이전트

큰 작업을 하나의 에이전트가 끝까지 끌고 가지 않아도 됩니다. Antigravity CLI는 주 에이전트가 작업을 잘게 쪼개 Subagent에 위임하고, 사용자는 /agents 패널로 진행 상태를 확인합니다.

> /goal 새 React+TS 프로젝트를 초기화하고 인증·결제·관리자 페이지 골격을 만들어줘

# 주 에이전트가 3개 Subagent를 자동 생성
#   subagent-1: 인증 모듈
#   subagent-2: 결제 모듈
#   subagent-3: 관리자 페이지

> /agents     # Subagent 패널로 각자 진행 상태 확인

Subagent는 데스크톱 Antigravity 2.0의 다이내믹 Subagent와 동일한 개념이 터미널에서 제공되는 것입니다.

5.3 스케줄링 — /schedule

cron과 비슷하지만 자연어로 등록합니다. 등록한 작업은 사용자가 IDE·CLI를 꺼두어도 백그라운드에서 실행됩니다.

> /schedule "매일 오전 9시에 git log --since=yesterday 요약을 Slack #daily에 올려줘"

> /schedule "main 브랜치에 push 될 때마다 변경 영향 분석 리포트 생성"

6. Gemini CLI에서 마이그레이션 #

6.1 호환 사항 — 거의 모든 것이 그대로

• Context 파일 — ~/.gemini/GEMINI.md·AGENTS.md는 그대로 읽힘
• Skills — 위치만 이동: ~/.gemini/skills/ → ~/.gemini/antigravity-cli/skills/, 워크스페이스도 .gemini/skills/ → .agents/skills/
• MCP 서버 — 새 경로 ~/.gemini/antigravity-cli/mcp_config.json · .agents/mcp_config.json
• Extensions — agy plugin import gemini로 플러그인으로 자동 변환

6.2 변경 사항 — 직접 손봐야 할 부분

• 명령 이름 — gemini → agy
• MCP 필드 — 원격 서버 정의의 url·httpUrl은 폐지, serverUrl로 통일
• 커스텀 테마 — 자동 이전 안 됨. 새로 지정
• 스크립트 — gemini …를 단순 검색 치환으로 agy …로 바꾸면 대체로 동작. Dockerfile에서 GEMINI.md를 복사하는 경우만 AGENTS.md로 명시 매핑 필요

6.3 제거 (참고)

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