Antigravity CLI(agy)로 넘어가는 기초 사용법과 마이그레이션 : Gemini CLI 종료(2026년 6월 18일)

 

 

안녕하세요! 갓대희 입니다.

Antigravity 시리즈

1편: 설치·입문 튜토리얼 2편: IDE 복구 가이드 3편: CLI 기초 사용 & alias (현재 글)

Antigravity CLI를 설치는 했는데, 막상 터미널을 열면 "그래서 뭘 입력하지?" 싶은 순간이 온다.

명령어 이름부터 antigravity가 아니라 agy라 한 번 막히고, 옵션은 많아 보이는데 정작 매일 쓰는 건 두세 개뿐이다.

 

그래서 이번 글은 네 가지를 차례로 짚는다.

먼저 Gemini CLI가 왜 종료되는지 배경을 짧게 정리하고,

agy 기초 사용 문법,

나만의 alias(별칭) 세팅,

그리고 넘어온 분을 위한 마이그레이션까지다.

 

Gemini CLI에서 막 넘어온 분도, Antigravity CLI가 처음인 분도 이 글 하나로 바로 시작할 수 있게 하는 것이 목표다.

설치 과정은 1편 6섹션 — Antigravity CLI 설치 및 첫 사용에서 이미 다뤘으니, 사용법은 "설치한 다음"부터 시작한다.

먼저 용어부터 가볍게 잡고 가자

• agy: 터미널에서 Antigravity CLI를 실행하는 실제 명령어 이름. antigravity가 아니다.
• 대화형 세션(interactive session): agy만 입력하면 열리는, 자연어로 계속 주고받는 채팅형 모드.
• 플래그(flag): 명령 뒤에 붙여 동작을 바꾸는 옵션. 보통 -c(짧은 형) 또는 --continue(긴 형) 형태다.
• alias(별칭): 길고 자주 쓰는 명령을 짧은 이름으로 등록해 두는 셸 기능. 예: ag → agy.
• MCP(Model Context Protocol): AI 에이전트가 외부 도구·서비스와 연결하는 표준 프로토콜.
• ~/.zshrc: zsh 셸을 열 때마다 자동으로 읽는 설정 파일. alias·환경변수를 여기에 적어 둔다.(bash라면 ~/.bashrc)

목차

1. Gemini CLI 종료, 그리고 Antigravity CLI
2. 설치 다음에 할 것
3. 기초 사용법 — 자주 쓰는 명령어
4. 권한과 안전 — --dangerously-skip-permissions 이해하기
5. 나만의 alias 세팅
6. 안전하게 첫 작업 시켜보기
7. Gemini CLI에서 넘어오는 마이그레이션 4단계
8. 자주 묻는 질문 (FAQ)

1. Gemini CLI 종료, 그리고 Antigravity CLI

Antigravity CLI(agy)가 왜 갑자기 "넘어가야 하는" 도구가 됐는지부터 짧게 짚고 가자.

처음 쓰는 분은 배경만 알고 넘어가면 되고, Gemini CLI를 쓰던 분에게는 이 절이 전환 판단의 근거가 된다.

 

종료 일정과 영향 대상

2026년 5월 19일(Google I/O 2026 당일), Google은 개발자 블로그를 통해 Gemini CLI를 Antigravity CLI로 전환한다고 발표했다. 종료 일정은 딱 한 줄이다.

On June 18, 2026, Gemini CLI and Gemini Code Assist IDE extensions will stop serving requests.

(2026년 6월 18일부터 Gemini CLI와 Gemini Code Assist IDE 확장이 요청 처리를 중단한다.)

 

공지(5/19)에서 종료(6/18)까지 약 30일로, 전환 기간이 짧은 편이다. 영향을 받는 대상과 그렇지 않은 대상을 먼저 구분해 두자.

구분	6월 18일 이후
Google AI Pro / AI Ultra (개인)	요청 처리 종료
Gemini Code Assist for individuals (무료)	요청 처리 종료
Gemini Code Assist for GitHub (무료/개인)	신규 설치 불가 후 수 주 내 종료
Standard / Enterprise 라이선스	기존 접근 유지 — 변경 없음

 

개인·무료 사용자가 먼저 영향을 받고, Enterprise는 그대로 유지된다.

Antigravity CLI 얼리 액세스도 Enterprise에 먼저 제공됐다.

 

왜 논란이 됐나 (오픈소스 → 클로즈드소스)

논란의 핵심은 라이선스다.

Gemini CLI는 Apache 2.0 오픈소스(TypeScript)였지만, Antigravity CLI는 공개 소스 저장소가 확인되지 않는다 — The Register는 "Antigravity CLI GitHub 페이지에는 체인지로그·README·GIF 파일만 있다"고 전했다.

커뮤니티는 GitHub Issue #27304로 오픈소스 정신의 계승을 요청했으나, 2026-05-22 기준 낮은 우선순위(priority/p3)로 답변 없이 열려 있다.

유료·Enterprise는 유지되는데 무료·개인 사용자만 즉시 전환을 요구받는 구도라 형평성 비판도 나왔다.

 

무엇이 달라졌나

달라진 점 (공식 발표 기준)

• 언어: Node.js(TypeScript) → Go 재작성. 메모리 사용량이 낮고 시작 속도가 빠른 것이 특징으로 꼽힌다.
• 아키텍처: 비동기 멀티에이전트. 대규모 리팩터·리서치가 백그라운드 서브에이전트로 분리돼, 기다리는 동안에도 다음 명령을 입력할 수 있다.
• 명령어: agy (← antigravity 아님).
• 확장: Extensions → Plugins로 개명, Agent Skills·Hooks·Subagents 지원.
• Antigravity 2.0 데스크톱 앱과 동일한 에이전트 하네스(에이전트 실행 환경을 묶는 런타임)를 공유한다.
  
  

아직 초기 버전이다.
Google도 "처음부터 1:1 기능 동등성은 없다"고 밝혔다.
예를 들어 커스텀 테마는 플러그인 임포트 때 빠지고, gemini skills 같은 스킬 관리 명령은 아직 동등한 것이 없다.
아키텍처는 매력적이지만, 핵심 작업이라면 기대치를 조금 낮춰 잡고 중요한 환경에서는 충분히 검증한 뒤 옮기는 편이 안전하다.

 

2. 설치 다음에 할 것

설치가 끝났다면 가장 먼저 두 가지만 확인하고 넘어가자.

# 1) 설치·버전 확인
agy --version

# 2) 그냥 실행 → 대화형 세션이 열리면 준비 끝
agy

 

agy를 처음 실행하면 곧바로 작업이 시작되는 게 아니라, 색상 테마를 고르는 환영 화면이 먼저 나올 수 있다.

테마를 고르고 나면 자연어로 지시를 입력할 수 있는 대화형 세션이 열린다. 여기까지 됐다면 다음 절로 바로 넘어가도 좋다.

아직 설치 전이라면?
설치 명령과 OS별 절차는 1편 §6과 공식 CLI 시작 문서를 참고하자. 이 글은 설치 이후의 "사용법"에 집중한다.

 

3. 기초 사용법 — 자주 쓰는 명령어

Antigravity CLI는 크게 두 가지 방식으로 쓴다.

대화형(채팅처럼 주고받기)과 비대화형(명령 한 번에 결과만 받기)이다.

 

3.1 대화형으로 시작하기

가장 기본은 옵션 없이 agy 한 줄이다. 세션이 열리면 "이 파일에 유닛 테스트를 추가해줘"처럼 자연어로 자유롭게 지시한다.

# 대화형 세션 시작
agy

# 첫 프롬프트를 미리 주고, 그 뒤로 대화를 이어가기
agy -i "이 프로젝트 구조부터 설명해줘"

ex)

 

3.2 비대화형 — 한 번에 결과만

대화창을 열지 않고 프롬프트 하나만 던져 결과를 받고 싶을 때는 -p(또는 --print)를 쓴다. 스크립트나 빠른 단발 작업에 어울린다.

# 프롬프트 하나만 실행하고 응답을 출력
agy -p "이 디렉터리에서 가장 큰 파일 3개를 알려줘"

 

3.3 대화 이어가기

앞서 하던 작업을 다시 이어가고 싶을 때 쓰는 두 가지다. 최근 대화 하나만 빠르게 이어갈 거라면 -c, 여러 대화 중 특정 하나를 골라 재개할 거라면 --conversation이다.

# 가장 최근 대화를 이어서 시작
agy -c

# 특정 대화를 ID로 지정해 재개
agy --conversation <대화ID>

 ex) agy -c

ex) agy로 세션을 활성화한 후 /resume > 원하는 세션을 선택하여 원하는 대화를 이어 갈 수도 있다.

 

3.4 명령어 요약표

아래는 agy --help로 확인한 항목 중 자주 쓰는 것들이다(직접 확인: agy 1.0.0, 2026-05-25). 전부 외울 필요는 없고, 처음엔 agy로 시작했다가 필요할 때 표에서 찾아 쓰면 된다.

 

명령 / 플래그	하는 일
agy	대화형 에이전트 세션을 연다.
agy -p "..." (--print/--prompt)	대화창 없이 프롬프트 하나만 실행하고 결과를 출력한다(비대화형).
agy -i "..." (--prompt-interactive)	첫 프롬프트를 주고, 그대로 대화형 세션을 이어간다.
agy -c (--continue)	가장 최근 대화를 이어서 시작한다.
agy --conversation <ID>	특정 대화를 ID로 지정해 재개한다.
agy --add-dir <경로>	작업 대상 디렉터리를 추가한다(반복 가능). 여러 폴더를 함께 다룰 때 쓴다.
agy --sandbox	터미널 동작을 제한하는 샌드박스 모드로 실행한다.
agy update	CLI를 최신 버전으로 갱신한다.
agy plugin import gemini	기존 Gemini CLI의 설정·확장을 Antigravity 플러그인으로 가져온다(7절 참고).
agy changelog / agy help	변경 내역(릴리스 노트) 확인 / 서브커맨드 도움말 확인.

 

전체 옵션은 언제든 agy --help로 확인할 수 있다. 버전이 올라가면 항목이 바뀔 수 있으니, 표와 다르면 agy --help를 기준으로 삼자.

 

3.5 이미지 생성하기

예전 Antigravity 1.0가 초창기 강력했다고 평가 받았고, 그리고 Hermes 등에서 매우? 인기 있는 기능 중 하나가 CLI에서 이미지 생성하는 기능이었다. Antigravity CLI 에서 이 기능이 가능하니 매우 잘 활용하지 않을까? 

  - 생성 결과

 

4. 권한과 안전 — --dangerously-skip-permissions 이해하기

alias를 만들기 전에, 잠깐 권한 이야기를 먼저 하고 가자. 다음 절에서 만들 별칭 중 일부가 바로 이 플래그를 쓰기 때문이다.

기본적으로 Antigravity CLI는 파일 수정이나 명령 실행처럼 영향이 큰 작업을 하기 전에 사용자에게 승인을 묻는다.

이 "물어보는 단계"를 통째로 끄는 옵션이 --dangerously-skip-permissions다.

--dangerously-skip-permissions는 "빠른 모드"가 아니다.
agy --help 설명 그대로, 이 플래그는 모든 도구 권한 요청을 묻지 않고 자동 승인한다(직접 확인: agy 1.0.0, 2026-05-25). 즉 에이전트가 파일을 고치거나 명령을 실행하기 전에 더 이상 확인을 받지 않는다.

편하지만, 그만큼 로컬 파일·실행 명령·네트워크 요청이 사용자 확인 없이 진행될 수 있다는 뜻이다. 중요한 코드베이스에서는 쓰지 않는 편이 좋다. 꼭 써야 한다면 평소 작업 폴더가 아니라 사용 후 버리는 임시 디렉터리나 격리된 환경에서, 의미를 알고 쓰자.

더 안전한 중간 단계: --sandbox
격리된 환경에서 시험만 해보고 싶다면 agy --sandbox로 터미널 동작을 제한한 채 실행할 수 있다. "권한을 다 열어두기"와 "매번 일일이 승인하기" 사이에서 한 단계 안전한 선택지로 기억해 두면 좋다.

정리하면, 기본은 권한을 묻는 agy 그대로 쓰고, --dangerously-skip-permissions는 위험을 이해한 격리 환경에서만 쓴다. 이 전제를 깔고 다음 절의 alias를 만든다.

 

5. 나만의 alias 세팅

매번 agy --continue --dangerously-skip-permissions처럼 긴 명령을 치는 건 번거롭다.

자주 쓰는 조합은 alias(별칭)로 짧게 줄여두면 입력이 한결 빨라진다. Codex CLI에서 cdd 같은 별칭을 만들어 쓰던 것과 같은 방식이다.

 

5.1 기본 별칭 세 개

이름은 외우기 쉽게 ag(기본), agd(d = dangerous), agr(r = resume)로 잡았다.

alias ag='agy'                                              # 기본 실행 (대화형, 권한 확인 그대로)
alias agd='agy --dangerously-skip-permissions'             # 권한 자동 승인 (격리/일회성 환경 전용)
alias agr='agy --continue --dangerously-skip-permissions'  # 최근 대화 이어서 + 권한 자동 승인

 

ex) 보통 요즘은 ai 에게 요청하면 다 등록 해 준다. (직접 설정 하실 분들은 다음 섹션을 확인 하면 된다.)

 - 아직 권한 자동 승인 처리를 하지 않아 권한을 물어보는 모습

  - 설정 완료

 - cat ~/.zshrc

 

5.2 ~/.zshrc에 등록하기

macOS·Linux의 zsh를 쓴다면 ~/.zshrc 파일 끝에 위 세 줄을 추가한다(bash라면 ~/.bashrc). 직접 편집기로 열어 붙여 넣어도 되고, 아래처럼 터미널에서 한 번에 추가해도 된다.

# ~/.zshrc 끝에 alias 블록 추가
cat >> ~/.zshrc <<'EOF'

# Antigravity CLI (agy) aliases
alias ag='agy'
alias agd='agy --dangerously-skip-permissions'
alias agr='agy --continue --dangerously-skip-permissions'
EOF

# 현재 셸에 즉시 반영
source ~/.zshrc

# 잘 등록됐는지 확인
type ag agd agr

 

type ag agd agr를 실행했을 때 각 별칭이 어떤 명령으로 풀리는지 출력되면 성공이다.

새 터미널 창을 열면 그때부터는 source 없이도 바로 쓸 수 있다.

참고: agy install 서브커맨드는 환경 경로와 셸 설정을 자동으로 구성해 준다(agy --help 기준). 다만 이건 PATH·기본 설정을 잡아주는 용도이고, 위처럼 개인 취향의 별칭은 ~/.zshrc에 직접 적어두는 쪽이 관리하기 편하다.

 

5.3 만든 별칭으로 실행하기

ag                 # = agy            (대화형 시작, 권한 확인)
agd                # = agy --continue --dangerously-skip-permissions
agr                #   (아까 하던 작업을, 격리 환경에서 빠르게 이어갈 때)

 

평소 작업은 ag로 충분하다. agd·agr는 "이건 망가져도 되는 폴더"라는 확신이 있을 때만 꺼내 쓰는 카드로 남겨두자.

 

6. 안전하게 첫 작업 시켜보기

가장 먼저 "읽기만 하는 작업"부터.
설치만 하고 막막하다면, 파일을 바꾸지 않는 질문부터 던져보자. 권한 승인 걱정 없이 에이전트가 어떻게 움직이는지 감을 잡을 수 있다.

아래 순서대로 하면 어렵지 않게 첫 작업을 끝낼 수 있다.

1. 작업할 프로젝트 폴더로 이동한다.
2. ag(= agy)를 실행해 대화형 세션을 연다.
3. "이 프로젝트 구조를 설명해줘"처럼 읽기 위주 작업을 시킨다.
4. 답이 나오면, 에이전트가 어떤 단계를 거쳤는지 살펴본다. 여기까지 되면 한 번 성공한 것이다.
5. 익숙해지면 "이 함수에 주석을 달아줘"처럼 작은 수정 작업으로 넘어간다. 이때부터 권한 승인 프롬프트가 뜨므로, 내용을 확인하고 허용/거부를 누른다.

중요한 코드라면 작업 전에 git add -A && git commit으로 현재 상태를 저장(체크포인트)해 두면, 결과가 마음에 들지 않을 때 되돌리기 쉽다.

 

7. Gemini CLI에서 넘어오는 마이그레이션 4단계

Gemini CLI를 쓰던 분이라면 설정·스킬을 그대로 가져올 수 있다. 명령어 구조 자체는 거의 비슷하니, 핵심 절차만 간단히 정리한다.

 

사전 준비 — 설정 위치 확인 & 백업

먼저 Gemini CLI 설정이 어디에 있는지 확인하고 통째로 백업한다. 작업 중 실수가 있어도 이 백업으로 되돌릴 수 있다.

 

항목	macOS / Linux	Windows
글로벌 스킬	~/.gemini/skills/	%USERPROFILE%\.gemini\skills\
워크스페이스 스킬	.gemini/skills/ (프로젝트 루트)	.gemini\skills\ (프로젝트 루트)
글로벌 규칙	~/.gemini/GEMINI.md	%USERPROFILE%\.gemini\GEMINI.md
MCP 설정	~/.gemini/settings.json	%USERPROFILE%\.gemini\settings.json

 

# 1) 내 환경에 뭐가 있는지 먼저 확인 (macOS / Linux)
ls -la ~/.gemini/

# 2) 날짜를 붙여 통째로 백업
cp -r ~/.gemini ~/.gemini-backup-$(date +%Y%m%d)

 

출력에 안 보이는 항목은 원래 안 썼다는 뜻이니 마이그레이션 대상에서 빼면 된다. .gemini-backup-20260525 같은 폴더가 생기면 백업 성공이다.

 

4단계 요약

1. 설치 — 1편 §6 절차를 따르고, 끝나면 agy --version으로 확인한다. 최초 실행 시 OAuth 인증이 진행된다.
2. 설정·스킬 임포트 — agy plugin import gemini로 기존 Gemini CLI 설정·스킬을 가져온다.
   실행한 뒤 평소 쓰던 작업 하나를 바로 돌려보면 무엇이 옮겨졌고 무엇이 빠졌는지 가장 빠르게 파악된다.
3. 워크스페이스 스킬 이동 — 프로젝트별 .gemini/skills/를 .agents/skills/로 옮긴다(프로젝트마다 수동). 플러그인 임포트가 자동으로 처리하지 않는 부분이다. 이미 .agents/skills/가 있다면 디렉터리째 mv하지 말고 cp -R .gemini/skills/. .agents/skills/로 내용만 병합해야 폴더가 중첩되지 않는다.
4. MCP 설정 필드 — 원격 MCP 서버를 쓴다면 키 이름을 url → serverUrl로 바꾼다. 놓치면 오류 메시지 없이 무음으로 실패하니 주의한다.

// 원격 MCP 서버: 키 이름만 변경 (Antigravity 전용 mcp_config.json)
"mcpServers": { "my-server": { "url":       "http://localhost:3000" } }  // 변경 전 (Gemini CLI)
"mcpServers": { "my-server": { "serverUrl": "http://localhost:3000" } }  // 변경 후 (Antigravity CLI)

 

mcp_config.json 위치는 버전마다 달라질 수 있다(예: ~/.gemini/antigravity/ 등으로 보고됨). 헷갈리면 직접 찾으면 된다.

 

# mcp_config.json 위치 검색 (macOS / Linux)
find ~ -name "mcp_config.json" 2>/dev/null

 

CI 스크립트에서 gemini 바이너리를 직접 호출한다면 agy로 교체해야 하는데, 플래그·인증·종료 코드가 달라질 수 있으니 단순 치환은 피하고 하나씩 테스트한다. 더 깊은 절차와 정확한 경로는 공식 문서와 커뮤니티 마이그레이션 가이드를 agy --help와 대조해 확인하자.

막히면 여기부터

• MCP 서버 무응답: 4단계의 url → serverUrl을 빠뜨렸는지부터 본다(오류 없이 조용히 실패).
• 인증 오류(Error calling 'initialize': EOF, macOS): 인증 캐시를 삭제 대신 백업 이동한 뒤 재인증하면 풀리는 사례가 보고된다. [UNVERIFIED] 정확한 경로는 공식 문서에서 확인한다.
• SSH·CI 환경: 인증 흐름이 Gemini CLI와 달라 지연될 수 있다. 비대화형(API 키 등) 인증 방법을 공식 문서에서 확인하고, CI는 하나씩보다 한 번에 전환하는 편이 디버깅이 쉽다.
• 네트워크/VPN: *.googleapis.com 방화벽 허용을 확인하고, VPN을 잠시 끄거나 DNS를 1.1.1.1/8.8.8.8로 바꿔 시도한다.

 

8. 자주 묻는 질문 (FAQ)

Q. Gemini CLI는 언제 종료되나?

공식 발표 기준 2026년 6월 18일부터 Gemini CLI와 Gemini Code Assist IDE 확장이 요청 처리를 중단한다. 단, Standard·Enterprise 라이선스 조직은 접근이 유지된다.

Q. 지금 꼭 Antigravity CLI로 옮겨야 하나?

무료·Pro 사용자는 6월 18일 이후 선택지가 제한된다. 당장 옮기지 않더라도 설정 백업과 agy plugin import gemini 정도는 미리 해두면 안전하다. Enterprise 라이선스라면 기존 Gemini CLI를 계속 쓸 수 있다.

Q. 명령어가 antigravity가 아니라 agy인가?

그렇다. 터미널에서 실행하는 명령은 agy다. antigravity로 입력하면 동작하지 않으니 주의하자. 전체 옵션은 agy --help로 확인할 수 있다.

Q. agy -c와 agy --conversation은 무엇이 다른가?

-c(--continue)는 가장 최근 대화 하나를 자동으로 이어서 시작한다. --conversation <ID>는 특정 대화를 ID로 지정해 재개한다. 평소에는 -c가 빠르고, 여러 대화를 오갈 때만 --conversation을 쓰면 된다.

Q. --dangerously-skip-permissions는 언제 써도 되나?

모든 도구 권한 요청을 자동 승인하는 옵션이라, 중요한 코드베이스에서는 권하지 않는다. 사용 후 버리는 임시 디렉터리, 일회성 컨테이너처럼 망가져도 되는 격리 환경에서, 의미를 알고 쓰는 게 안전하다. 시험만 할 거라면 --sandbox를 먼저 고려하자.

Q. alias를 등록했는데 동작하지 않는다.

두 가지를 확인하자. ① ~/.zshrc에 추가한 뒤 source ~/.zshrc로 다시 읽었거나 터미널을 새로 열었는지. ② type ag로 별칭이 등록됐는지. 그래도 agy: command not found가 나오면 별칭 문제가 아니라 agy가 PATH에 없는 것이니, 설치 상태부터 점검한다(1편 §6 참고).

 

마무리

여기까지 따라왔다면 기본기는 거의 갖춰졌다. 정리하면:

• 배경: Gemini CLI는 6월 18일 종료, 후속은 Antigravity CLI(agy) — Go 재작성·비동기 멀티에이전트. Enterprise는 기존 유지.
• 기본: agy로 대화형, agy -p로 단발 실행, agy -c로 이어가기.
• 권한: 기본은 승인을 묻는 agy. --dangerously-skip-permissions는 격리 환경에서만, --sandbox는 안전한 중간 단계.
• alias: ag/agd/agr를 ~/.zshrc에 등록해 빠르게. --resume이 아니라 --continue인 점만 기억하자.
• 마이그레이션: 백업 → agy plugin import gemini → 스킬 경로 이동 → MCP url→serverUrl.

처음엔 ag 하나로 충분하다. 자주 쓰다 보면 자기만의 조합이 생기는데, 그때마다 별칭으로 줄여두면 터미널 작업이 한결 가벼워진다.

 

참고자료

• 직접 테스트: agy --help, agy --version (agy 1.0.0, macOS, 2026-05-25)
• Google Developers Blog: An important update — Transitioning Gemini CLI to Antigravity CLI (2026-05-19)
• The Register: Bye-bye Gemini CLI (2026-05-20)
• GitHub google-gemini/gemini-cli Issue #27304
• Antigravity 공식 CLI 시작 문서
• agentpedia.codes: Gemini CLI → Antigravity CLI 마이그레이션 가이드
• 갓대희 블로그: Antigravity 시리즈 1편 — 설치·입문 튜토리얼 (§6 CLI 설치)

 

작성일: 2026-05-21 (개정: 2026-05-25 — 종료 정리·CLI 기초·alias·마이그레이션으로 재구성)

대상 버전: Antigravity CLI 1.0 (agy 1.0.0 기준), Gemini CLI 종료 예정 2026-06-18

이 글의 명령어는 agy --help로 직접 확인했으나, 버전이 올라가면 옵션·경로가 달라질 수 있다. 적용 전 agy --help와 공식 문서로 최신 값을 확인하기 바란다.