Gemini CLI 설치 방법: npm·Homebrew 비교와 인증 방식 3가지 고르는 기준

Gemini CLI 설치는 생각보다 싱겁게 끝납니다. Ubuntu 24.04 LTS에서 npm install -g @google/gemini-cli를 치니 added 7 packages in 9s가 뜨고, 새 터미널에서 gemini --version을 치니 0.59.0이 찍히더라고요. 그게 전부였어요.

정작 고민할 건 설치 다음입니다. 설치는 누구나 되지만, 설치한 뒤 실제로 쓸 수 있느냐는 어떤 계정으로 인증하느냐에 달려 있거든요.

Gemini CLI 메인테이너 Dmitry Lyalin은 2026년 5월 19일 공식 저장소 토론 글에서, 2026년 6월 18일부터 무료로 쓰는 사용자와 Google AI Pro·Ultra 구독자의 요청을 처리하지 않는다고 공지했습니다.

계속 쓸 수 있는 것은 조직의 Gemini Code Assist Standard·Enterprise 라이선스나 Google Cloud, 유료 Gemini API 키와 Gemini Enterprise Agent Platform API 키예요.

그러니 개인 무료 계정이나 AI Pro·Ultra 구독만 있다면 Gemini CLI를 설치해도 쓸 수 없습니다. 그 경우에는 Windows에서 Antigravity CLI(agy)를 설치하고 Gemini CLI 설정·GEMINI.md를 옮기는 순서부터 보세요.

한 가지 헷갈리는 점은, 저장소 README와 인증·할당량 문서가 2026년 9월 28일에도 무료 등급과 AI Pro·Ultra 이용을 안내하고 있어 공지와 어긋난다는 겁니다.

Gemini CLI는 Google이 배포하는 터미널 코딩 에이전트로, 프로젝트 폴더에서 말로 시킨 작업을 읽고 고치고 실행합니다. 설치는 2026년 9월 13일 Ubuntu 24.04 LTS · Gemini CLI 0.59.0 테스트 환경에서 직접 실행해 확인했고, 설치·인증 문서도 같은 날 공식 저장소에서 다시 봤습니다. 로그인 화면은 계정이 있어야 넘어갈 수 있어 열지 않았습니다.

npm 한 줄이면 설치는 끝

Node.js가 있으면 세 단계로 끝납니다.

1. Node.js 버전 확인

node --version이 20.0.0 이상이면 됩니다. 테스트 환경은 Node.js 22였습니다. 그 밖의 요구사항은 이렇습니다.

• 운영체제: macOS 15 이상, Windows 11(24H2 이상), Ubuntu 20.04 이상
• 메모리: 가벼운 작업은 4GB, 큰 코드베이스는 16GB 이상 권장
• 셸: Bash, Zsh, PowerShell
• 인터넷 연결, 그리고 Gemini Code Assist 제공 지역

2. 설치

npm install -g @google/gemini-cli

added 7 packages in 9s

3. 새 터미널에서 버전 확인

gemini --version

0.59.0

같은 날 npm 레지스트리의 latest도 0.59.0이었습니다. 버전이 찍히면 설치는 끝난 거예요.

npm 말고 쓸 수 있는 방법

공식 문서의 설치 방법은 일곱 가지입니다. 저는 이미 쓰는 패키지 관리자를 따라가는 걸 권해요. 그래야 업데이트까지 맡길 수 있거든요.

방법	명령	맞는 경우
npm	npm install -g @google/gemini-cli	세 운영체제 공통
Homebrew	brew install gemini-cli	macOS·Linux에서 brew 사용
MacPorts	sudo port install gemini-cli	macOS에서 MacPorts 사용
npx	npx @google/gemini-cli	설치 없이 한 번만

macOS에서 Homebrew를 쓰고 있다면 brew install gemini-cli로 업데이트까지 맡기는 편이 손이 덜 갑니다. 다만 아래 공개 사례에 나오는 첫 실행 권한 오류는 미리 알아 두세요.

설치 없이 한 번만 써 보고 싶다면 npx @google/gemini-cli로 됩니다. 제가 직접 돌려 본 건 npm 전역 설치뿐이에요.

나머지 셋은 쓰임이 좁습니다. Docker·Podman은 공식 샌드박스 이미지나 gemini --sandbox로 컨테이너 안에서 돌릴 때, Anaconda는 가상 환경 안에서 npm으로 설치해 Python 환경과 함께 관리할 때, 소스 빌드(npm run start·npm run start:prod)는 저장소를 직접 고칠 때 씁니다.

설치하고 나서 알아 둘 명령

인자 없이 gemini를 실행하면 대화형 세션이 열립니다(로그인 필요). 관리용 하위 명령은 다섯 가지예요.

• gemini mcp: MCP 서버 추가·삭제·목록·켜기·끄기
• gemini extensions: 확장 설치·삭제·업데이트·만들기
• gemini skills: 에이전트 스킬 설치·켜기·끄기
• gemini hooks migrate: Claude Code에 걸어 둔 훅을 Gemini CLI로 옮기기
• gemini gemma: 로컬 Gemma 모델 라우팅 관리

옵션은 처음부터 다 볼 필요 없고, 세 개만 손에 익혀 두면 됩니다. --approval-mode(도구 승인 방식: default 매번 묻기, auto_edit 편집만 자동, yolo 모두 자동, plan 읽기 전용), -o·--output-format(text·json·stream-json), -w·--worktree(새 git worktree에서 시작)예요.

인증 방식은 계정 따라 갑니다

인증을 정하지 않고 gemini -p "hello"를 실행하면 CLI가 고를 수 있는 값을 알려 줍니다.

Please set an Auth method in your ~/.gemini/settings.json or specify one
of the following environment variables before running: GEMINI_API_KEY,
GOOGLE_GENAI_USE_VERTEXAI, GOOGLE_GENAI_USE_GCA

세 값이 세 가지 인증 방식에 하나씩 대응하고, 설정 파일은 ~/.gemini/settings.json입니다. 공식 인증 문서는 GEMINI_API_KEY 말고는 변수 이름으로 설명하지 않아서, 아래 표의 나머지 이름은 이 메시지에서 가져왔습니다.

방식	맞는 경우	필요한 것
Google 로그인(GOOGLE_GENAI_USE_GCA)	조직의 Code Assist 라이선스	브라우저 로그인
API 키(GEMINI_API_KEY)	브라우저 없는 CI	Google AI Studio의 유료 키
Vertex AI(GOOGLE_GENAI_USE_VERTEXAI)	Google Cloud를 쓰는 조직	프로젝트 + ADC·서비스 계정 키·Cloud API 키

고르는 기준은 단순합니다. 회사의 Gemini Code Assist 라이선스가 있으면 Google 로그인, Google Cloud 프로젝트가 있으면 Vertex AI, 브라우저가 없는 CI라면 API 키나 Vertex AI예요.

“그냥 개인 Google 계정으로 로그인하면 되지 않나” 하는 분이 많을 텐데, 여기가 제일 헷갈리는 지점입니다. 공식 문서는 여전히 Google 로그인을 가장 간단한 방법으로 소개하지만, 개인 무료 계정과 AI Pro·Ultra 계정은 공지 이후 이 길로 요청이 처리되지 않습니다.

Google 로그인을 쓴다면 Google Cloud 프로젝트도 챙겨야 할 수 있습니다. 회사·학교·Workspace 계정, Google Developer Program 라이선스, Gemini Code Assist 구독은 프로젝트를 따로 설정합니다. 조직의 Code Assist Standard·Enterprise 라이선스 사용은 공지 이후에도 계속 지원되고요.

대부분의 개인 계정은 필요 없다고 문서에 나오지만 “대부분”이라 예외가 있습니다. GOOGLE_CLOUD_PROJECT를 넣어야 하는 경우와 지워야 하는 경우는 Gemini CLI 인증 오류를 종료 코드로 가르는 순서에 정리했어요.

다른 사람들이 설치·로그인에서 막힌 곳

다른 사용자가 GitHub에 올린 이슈 가운데 설치·로그인 단계에서 자주 보이는 세 가지를 골랐습니다.

This account requires setting the GOOGLE_CLOUD_PROJECT env var

Neinndall은 개인 무료 Google 계정으로 “Login with Google”을 눌렀는데 This account requires setting the GOOGLE_CLOUD_PROJECT or GOOGLE_CLOUD_PROJECT_ID env var 오류로 넘어가지 못했다고 보고했습니다(2025-12-03, Windows 11, 이슈 #14443).

이슈 안에 원인 설명이나 공식 우회는 없습니다. 이 오류가 나는 조건은 인증 오류 글의 GOOGLE_CLOUD_PROJECT 절에 소스 기준으로 적어 뒀어요.

Cloud Code Private API has not been used in project …

labibhussain0-gif는 Gemini Advanced 구독 계정으로 gemini auth login의 브라우저 인증까지 마쳤는데 Cloud Code Private API has not been used in project 276287556352 before or it is disabled라는 403으로 끊겼다고 보고했습니다(2026-04-28, Gemini CLI 0.38.2·0.39.1, 이슈 #26105).

보고자는 OAuth 경로가 GOOGLE_CLOUD_PROJECT 값을 싣지 못하고 OAuth 클라이언트 자체의 내부 프로젝트 번호로 요청을 보낸다고 분석했습니다. 메인테이너가 이를 확정하지는 않았고, 이슈는 “계획 없음(not planned)“으로 닫혔어요.

보고자는 GEMINI_API_KEY로 바꾸자 정상 동작했다고 적었는데, 공지 전인 4월 보고라는 점은 감안해야 합니다. 지금 계속 쓸 수 있는 키는 유료 키입니다.

EACCES: permission denied, mkdir ‘/Library/Application Support/GeminiCli’

ahundt는 macOS 14.7에서 Homebrew로 설치한 뒤 첫 실행에 Error: EACCES: permission denied, mkdir '/Library/Application Support/GeminiCli'로 멈췄다고 보고했습니다(2025-11-21, Gemini CLI 0.16.0, 이슈 #13547).

보고자는 관리자 권한이 필요한 시스템 경로가 코드에 고정된 탓이라고 지적했고, 이슈는 “계획 없음”으로 닫혀 확인된 수정이 없습니다.

주의: Homebrew로 설치한다면 첫 실행에서 이 권한 오류를 만날 수 있다는 것을 알고 시작하세요.

마치며

설치 명령은 한 줄이고, 테스트 환경에서는 9초 만에 끝났습니다. 그래서 오히려 설치 전에 내 계정이 계속 지원되는 쪽인지부터 확인하시길 권해요. 개인 무료 계정이나 AI Pro·Ultra 구독뿐이라면 설치에 시간을 쓰지 말고 처음부터 Antigravity CLI로 가는 게 맞습니다.

조직 라이선스나 Google Cloud, 유료 API 키가 있다면 Gemini CLI는 여전히 쓸 만합니다. 그다음은 설정 파일인데, 사용자·프로젝트·시스템 파일이 어떻게 겹치는지는 Gemini CLI settings.json 네 파일의 우선순위에서 이어집니다.