Gemini CLI 설치와 첫 설정,
2026년 9월엔 먼저 확인할 것이 하나 있습니다

개인 구글 계정이라면 Gemini CLI가 아니라 Antigravity CLI입니다

2026년 5월 19일 Google Developers Blog의 “Transitioning Gemini CLI to Antigravity CLI” 공지가 기준입니다. 소비자용 일정은 명확합니다. 2026년 6월 18일부터 Gemini CLI와 Gemini Code Assist IDE 확장은 Google AI Pro·Ultra 구독자와 무료 Gemini Code Assist for individuals 사용자 요청을 더 이상 처리하지 않습니다. 같은 날 Gemini Code Assist for GitHub의 신규 설치도 중단됐습니다. 대신 Go로 다시 만든 Antigravity CLI(agy)가 누구나 쓸 수 있게 열렸고, Agent Skills·Hooks·Subagents·Extensions(플러그인으로 이름 변경)는 옮겨 왔지만 1:1 기능 대응은 아니라고 공지는 못 박습니다.

반대로 Gemini CLI가 계속 유지되는 경우도 같은 공지에 있습니다. 조직이 Gemini Code Assist Standard·Enterprise 라이선스로 쓰고 있다면 접근 권한이 그대로이고, 최신 Gemini 모델 지원도 이어집니다. 개인이라도 유료 Gemini API 키나 Gemini Enterprise Agent Platform API 키로는 계속 접근할 수 있습니다. geminicli.com 문서 사이트 상단에도 2026년 9월 8일 현재 “Unpaid tier and Google One users: Gemini CLI was replaced by Antigravity CLI on June 18th, 2026” 배너가 걸려 있고, Google 개발자 문서의 Code Assist 지원 지역 페이지는 “더 이상 Login with Google 옵션으로 Gemini CLI에 접근할 수 없다”고 적습니다. 즉 개인 계정은 로그인 자체가 막힌 상태입니다.

설치는 npx·npm·Homebrew 세 갈래, 요구사항은 Node 20 이상입니다

공식 설치 문서(geminicli.com/docs/get-started/installation)의 시스템 요구사항은 macOS 15 이상, Windows 11 24H2 이상, Ubuntu 20.04 이상, Node.js 20.0.0 이상, 4GB 이상 RAM(긴 세션은 16GB 권장), 인터넷 연결입니다. 위치 조건으로 “Gemini Code Assist 지원 지역” 링크가 걸려 있는데, 2026년 9월 8일 그 페이지를 열면 지역 목록 대신 개인 등급 서비스 종료 안내가 나옵니다.

세 방법은 결국 같은 gemini 실행 파일을 씁니다. npx는 ~/.npm/_npx 캐시에 임시로 받아 실행하므로 매번 최신 버전을 확인하는 대신 첫 실행이 느리고, 전역 설치는 npm install -g @google/gemini-cli@latest로 업데이트합니다. 릴리스 채널은 세 개로, 안정판(latest, 매주 화요일 UTC 20:00), 프리뷰(@preview, 화요일 UTC 23:59), 나이틀리(@nightly, 매일 UTC 00:00)입니다. 태그를 생략하면 안정판이 설치됩니다. MacPorts(sudo port install gemini-cli)와 Anaconda 환경 설치도 README에 있습니다.

이 Mac(Node v26.5.0, npm 11.17.0)에서 2026년 9월 8일 실제로 실행한 결과입니다. Homebrew는 이 환경에 없어서 npx로 확인했습니다.

--help 출력에서 눈여겨볼 옵션은 다음과 같습니다. 도움말 원문 그대로입니다. -p, --prompt는 “Run in non-interactive (headless) mode with the given prompt”, -i, --prompt-interactive는 프롬프트를 실행한 뒤 대화형으로 이어가기, -w, --worktree는 새 git worktree에서 시작, --approval-mode는 default·auto_edit·yolo·plan 네 값, -o, --output-format은 text·json·stream-json입니다. 서브커맨드로 gemini mcp, gemini extensions, gemini skills, gemini hooks, gemini gemma(로컬 Gemma 라우팅)가 있습니다. 예전 문서의 --allowed-tools는 도움말에서 “DEPRECATED: Use Policy Engine instead”로 표시됩니다.

인증은 세 가지, 아무것도 없으면 이 에러가 뜹니다

인증 문서(geminicli.com/docs/get-started/authentication)는 계정 유형별로 권장 방식을 표로 나눕니다. 개인 구글 계정과 조직 Workspace 계정은 Sign in with Google, AI Studio API 키 사용자는 Gemini API key, Google Cloud 사용자는 Vertex AI입니다. 헤드리스(스크립트) 실행은 캐시된 로그인이 없으면 반드시 환경변수 인증이어야 합니다. 이 Mac에는 로그인 캐시가 없어서 -p로 바로 질문을 던지자 다음 메시지로 종료됐습니다.

이 한 줄이 세 인증 방식의 환경변수 이름을 그대로 알려줍니다. GEMINI_API_KEY는 AI Studio 키, GOOGLE_GENAI_USE_VERTEXAI=true는 Vertex AI(추가로 GOOGLE_CLOUD_PROJECT·GOOGLE_CLOUD_LOCATION, 그리고 ADC·서비스 계정 JSON·GOOGLE_API_KEY 중 하나), GOOGLE_GENAI_USE_GCA는 Google 계정 로그인(Gemini Code Assist)입니다. 대화형으로 gemini만 실행하면 방식을 고르는 화면이 뜨고, 나중에 /auth로 바꿀 수 있습니다.

환경변수를 매번 치기 싫다면 두 가지입니다. ~/.zshrc에 export 줄을 추가하거나, ~/.gemini/.env(또는 프로젝트 폴더의 .gemini/.env)에 적어 두면 CLI가 현재 폴더부터 위로 올라가며 처음 찾은 .env 하나만 읽습니다. 문서가 “merged가 아니라 first file found”라고 강조하는 부분이라, 프로젝트 .env와 홈 .env에 다른 값이 있으면 프로젝트 쪽만 적용됩니다.

Google 계정 로그인이 되는 조직 계정이라도 조건이 붙습니다. 회사·학교 Workspace 계정, Google Developer Program의 Code Assist 라이선스, Code Assist 구독 라이선스는 GOOGLE_CLOUD_PROJECT(없으면 GOOGLE_CLOUD_PROJECT_ID)에 프로젝트 ID를 넣고, 그 프로젝트에 Gemini for Cloud API를 켜고 IAM 권한을 줘야 합니다. Vertex AI 방식에서 GOOGLE_API_KEY를 썼는데 “API keys are not supported by this API”가 나오면 조직 정책이 API 키를 막은 것이니 ADC나 서비스 계정 키로 바꾸라고 문서는 안내합니다.

한도 표는 남아 있지만, 개인 계정 줄은 이제 적용되지 않습니다

2026년 9월 8일 기준 할당량 문서의 표는 다음과 같습니다. Google 계정: Gemini Code Assist 개인 1,000회/일, Google AI Pro 1,500회/일, Google AI Ultra 2,000회/일. Gemini API 키: 무료 250회/일(Flash 모델만), 유료는 요금제에 따라 다름. Vertex AI: Express 모드는 결제 없이 90일, 이후 종량제. Workspace: Code Assist Standard 1,500회, Enterprise 2,000회, Workspace AI Ultra 2,000회. 분당 요청 제한도 별도로 있고, README는 개인 계정 기준 60회/분을 적고 있습니다.

여기서 두 가지를 걸러 읽어야 합니다. 첫째, Google 계정 줄의 개인 등급(1,000·1,500·2,000)은 6월 18일 이후 Gemini CLI에서는 더 이상 유효하지 않습니다. 문서 표가 갱신되지 않았을 뿐 상단 배너가 우선입니다. 둘째, README와 할당량 문서가 API 키 무료 한도를 다르게 적습니다. README는 “1000 requests/day with Gemini 3”, 할당량 문서는 “250 requests/day, Flash only”입니다. 실제 적용값은 Gemini API 자체의 요금제 문서(ai.google.dev/gemini-api/docs/rate-limits)가 결정하므로, API 키로 쓸 계획이면 그쪽 표를 기준으로 잡는 편이 안전합니다. 토큰 단가 자체는 Gemini API 가격 글에 정리돼 있습니다.

세션 중 사용량은 /stats model로 봅니다. 문서에 따르면 이 명령이 현재 세션의 토큰 사용량과 현재 할당량의 한도 정보를 함께 보여주고, 종료 시에도 모델 사용 요약이 출력됩니다.

설정 파일은 ~/.gemini 아래에 모입니다

사용자 전역 설정은 ~/.gemini/settings.json, 프로젝트별 설정은 <project>/.gemini/settings.json입니다. 대화형에서 /settings를 치면 같은 파일을 검증과 안내가 붙은 편집기로 고칠 수 있습니다. 프로젝트 규칙은 GEMINI.md에 적고, /init이 현재 폴더를 분석해 초안을 만들어 줍니다. 전역 규칙은 ~/.gemini/GEMINI.md이고, /memory list·/memory show·/memory refresh로 어떤 GEMINI.md가 어떤 순서로 읽히는지 확인합니다.

흥미로운 점은 이 Mac의 settings.json에 제가 쓴 적 없는 hooks 항목(BeforeAgent·AfterAgent·BeforeTool·AfterTool)이 들어 있었다는 것입니다. 네 훅 모두 ~/.orca/agent-hooks/gemini-hook.sh를 호출합니다. Orca IDE가 에이전트 사용량을 상태 표시줄에 띄우기 위해 Gemini CLI 훅을 설치해 둔 흔적입니다. 다른 도구를 먼저 깔았다면 Gemini CLI 첫 실행 전에 gemini hooks list나 /hooks list로 무엇이 등록돼 있는지 한 번 보는 게 좋습니다. 그 밖에 수동 체크포인트는 ~/.gemini/tmp/<project_hash>/, 커스텀 명령은 ~/.gemini/commands/*.toml, 서브에이전트는 ~/.gemini/agents, 스킬은 ~/.gemini/skills/에 놓입니다.

첫 세션에서 쓰는 명령은 열 개면 충분합니다

명령 참조 문서(geminicli.com/docs/reference/commands) 기준으로 추린 목록입니다. /help(또는 /?) 명령 목록, /auth 인증 방식 변경, /model set <model-name> --persist 모델 고정, /stats model 토큰·할당량, /chat save <tag>·/resume 대화 저장과 복원(둘은 같은 명령의 별칭), /compress 컨텍스트를 요약으로 교체, /clear 새 세션(Ctrl+L은 화면만 지우고 대화는 유지), /rewind(Esc 두 번) 대화와 파일 변경 되돌리기, /permissions trust 폴더 신뢰, /quit --delete 세션 기록까지 지우고 종료. 파일은 @경로로 프롬프트에 넣고(gitignore된 파일은 기본 제외), !명령은 셸을 그대로 실행하며 이때 서브프로세스에 GEMINI_CLI=1 환경변수가 붙습니다.

삭제는 설치 방식을 따라갑니다. 전역 설치는 npm uninstall -g @google/gemini-cli, Homebrew는 brew uninstall gemini-cli, npx만 썼다면 rm -rf "$(npm config get cache)/_npx"로 캐시를 비우는데 이 경우 npx로 실행한 다른 패키지도 함께 지워집니다. ~/.gemini 폴더는 어느 방법으로도 자동 삭제되지 않으므로 로그인 캐시까지 지우려면 직접 제거해야 합니다.

Antigravity CLI로 옮길 때 실제로 달라지는 것

Antigravity CLI는 npm 패키지가 아니라 네이티브 바이너리입니다. macOS·Linux는 curl -fsSL https://antigravity.google/cli/install.sh | bash 한 줄로 ~/.local/bin/agy에 설치되고 셸 프로필에 PATH를 추가합니다(--skip-path, --skip-aliases 플래그로 막을 수 있음). 첫 실행 시 OS 키링(macOS는 Keychain)에서 세션을 찾고, 없으면 브라우저를 열어 Google 로그인을 진행합니다. SSH 환경에서는 URL을 복사해 로컬 브라우저에서 로그인한 뒤 코드를 붙여 넣는 방식입니다. Gemini API 키로 쓰려면 ~/.gemini/antigravity-cli/settings.json에 { "modelProvider": "gemini" }를 넣고 GEMINI_API_KEY를 export해야 하며, 문서는 “GEMINI_API_KEY만 설정하는 것은 아무 효과가 없다”, “GOOGLE_API_KEY나 .env 파일로 넣은 키는 읽지 않는다”고 못 박습니다. Gemini CLI와 정반대 동작이라 옮길 때 가장 자주 걸리는 지점입니다.

마이그레이션 문서 기준으로 그대로 쓰이는 것은 GEMINI.md·AGENTS.md 워크스페이스 규칙과 ~/.gemini/GEMINI.md 전역 규칙입니다. 달라지는 것은 경로입니다. 전역 스킬은 ~/.gemini/skills/에서 ~/.gemini/antigravity-cli/skills/로, 프로젝트 스킬은 .gemini/skills/에서 .agents/skills/로 옮겨야 인식됩니다. 확장은 agy plugin import gemini가 플러그인으로 변환해 주고, MCP 서버 설정은 settings.json 안에 두지 않고 별도 mcp_config.json으로 분리됩니다. 첫 실행 온보딩이 기존 ~/.gemini 설정을 감지해 무엇을 옮길지 체크리스트로 묻습니다. 이 Mac에는 아직 agy가 설치돼 있지 않아 실제 온보딩 화면은 확인하지 못했고, 위 내용은 2026년 9월 8일 공식 문서 기준입니다.

Codex CLI·Claude Code와 설치·인증·무료 한도 비교

세 도구를 같은 축으로 놓으면 선택이 빨라집니다. 2026년 9월 8일 각 공식 문서 기준입니다.

정리하면, 돈을 내지 않고 터미널 에이전트를 써 보려는 개인에게 2026년 9월 현재 열려 있는 문은 Antigravity CLI(Google 계정)와 Gemini CLI의 API 키 무료 등급 두 개뿐입니다. Codex CLI와 Claude Code는 구독이나 API 과금이 전제입니다. 반대로 이미 Claude Code나 Codex를 쓰고 있다면 Gemini CLI를 굳이 추가할 이유는 Gemini 모델을 써야 하는 작업이거나 회사가 Code Assist 라이선스를 갖고 있을 때 정도입니다. 각 도구의 설치 절차는 Codex CLI 설치, Claude Code 설치 글에, 어떤 작업에 어느 도구가 맞는지는 바이브코딩 툴 비교에 있습니다.

자주 묻는 질문

Q. 설치는 됐는데 로그인하면 요청이 안 갑니다.
개인 Gmail 계정(무료 또는 AI Pro·Ultra)이라면 2026년 6월 18일 이후 정상 동작입니다. Gemini CLI가 아니라 Antigravity CLI를 설치하거나, AI Studio에서 API 키를 만들어 GEMINI_API_KEY 방식으로 바꿔야 합니다.

Q. “Please set an Auth method in your ~/.gemini/settings.json”이 뜹니다.
인증이 하나도 설정되지 않은 상태에서 -p로 실행했을 때 나오는 정상 메시지입니다. 대화형으로 gemini를 먼저 실행해 방식을 고르거나, 메시지에 적힌 세 환경변수 중 하나를 설정하면 됩니다.

Q. Windows에서도 되나요?
Gemini CLI는 Windows 11 24H2 이상에서 npm으로 설치되고 PowerShell을 지원합니다. Antigravity CLI도 PowerShell·CMD용 설치 스크립트가 있습니다.

Q. 기업 라이선스인데 “프로젝트를 설정하라”는 안내가 나옵니다.
Workspace 계정과 Code Assist 라이선스는 GOOGLE_CLOUD_PROJECT 환경변수에 프로젝트 ID를 넣고, 해당 프로젝트에서 Gemini for Cloud API를 활성화한 뒤 IAM 권한을 부여해야 합니다. 개인 계정에는 없던 단계입니다.