Gemini CLI 사용법 — 무료로 어디까지 되나, 직접 써보고 정리

AI 코딩 도구가 늘면서 Gemini CLI를 한번 깔아만 두고 방치하는 경우가 많습니다. "무료라고 하니 일단 받아두자"로 그치면, 막상 필요한 순간에 인증에서 막히거나 무료 할당량을 엉뚱한 데 소진합니다.

Claude Max와 Gemini Pro 두 유료 플랜을 병행 사용 중인 사용자로서 Gemini CLI 사용법을 Windows 환경 기준으로 정리했습니다.

이 글을 끝까지 읽으면 설치 → 인증 → 첫 프롬프트 실행까지 약 5분, 무료 티어로 어디까지 가능한지, Claude Code와의 실무 차이 3가지, 그리고 처음 쓰는 사람들이 자주 만나는 트러블 포인트 한 개를 건져갈 수 있습니다.

1. Gemini CLI가 뭔지부터

Gemini CLI는 구글이 공개한 오픈소스 터미널용 AI 에이전트입니다. google-gemini/gemini-cli GitHub 저장소에서 소스를 공개하며, Apache 2.0 라이선스입니다.
"터미널에서 파일을 읽고/고치고/명령을 실행하는" 에이전틱 CLI 카테고리에 속하고, 내부 모델만 Gemini 계열(2.5 Pro / Flash 등)로 바뀐다고 이해하면 시작점으로는 충분합니다.

Claude Code도 같이 써본 입장에서 Gemini CLI를 처음 깔 때 가장 먼저 체감하는 차이 3가지입니다.

• 무료 티어가 명시적으로 존재. 개인 구글 계정 로그인만으로 일정 요청까지 과금 없이 쓸 수 있다.
• .gemini/ 디렉터리 기반 설정. .claude/처럼 프로젝트 루트에 자체 설정을 둔다.
• MCP(Model Context Protocol)를 공식 지원. 같은 MCP 서버를 Claude Code와 공유해서 사용 가능합니다.

2. 설치 — Windows 11 + Node.js v24 기준

사전 준비물은 단 하나, 최신 Node.js입니다. 공식 저장소는 Node 20 이상을 요구하며, 저는 Node v24로 검증했습니다.

node --version
# v24.x.x 이상이면 OK

설치 명령은 한 줄입니다.

npm install -g @google/gemini-cli

설치가 끝나면 아무 디렉터리에서 gemini 실행 파일이 인식되는지 확인합니다.

gemini --version

버전 번호가 출력되면 성공입니다. 저는 0.x 대 버전에서 작업했고, 빠르게 바뀌는 도구라 설치한 시점의 버전을 README에 같이 적어두는 습관을 추천합니다. 팀원이 "안 된다"고 물을 때 버전 차이로 원인을 빠르게 좁힐 수 있습니다.

3. 인증 — 무료 티어로 시작하는 Gemini CLI 사용법

Gemini CLI 사용법에서 가장 중요한 선택 지점이 인증 방식입니다. 선택지는 두 가지입니다.

1. 개인 구글 계정 로그인 (무료 할당 포함)
2. API 키 직접 발급 (Google AI Studio 또는 Vertex AI)

처음이라면 1번을 권장합니다. 프로젝트 루트에서 그냥 gemini를 치면 브라우저로 OAuth 로그인 창이 뜨고, 로그인을 마치면 터미널 프롬프트로 돌아옵니다.

cd my-project
gemini

API 키를 쓰는 경우 환경 변수로 주입합니다. PowerShell 기준은 아래와 같습니다.

$env:GEMINI_API_KEY="여기에_발급받은_키"
gemini

팀 공용 PC라든가 여러 프로젝트에서 서로 다른 계정을 써야 한다면 API 키 방식이 편합니다. 개인 학습·사이드 프로젝트라면 무료 로그인이 마찰이 훨씬 적습니다.

4. 첫 세션 — 자주 쓰는 명령 5개

인증이 끝나면 대화형 프롬프트가 뜹니다. 이 상태에서 자연어로 지시하면 되고, 슬래시 커맨드로 세션을 제어합니다.

명령	역할	자주 쓰는 상황
/help	사용 가능한 슬래시 커맨드 목록	세션 처음 켰을 때
/tools	현재 활성화된 도구/MCP 확인	파일 접근이 안 될 때 원인 점검
/memory	컨텍스트 메모리 관리	장시간 작업 중 누적 정리
/chat save <이름>	현재 대화 스냅샷 저장	작업 중단 전
/quit	세션 종료	안전한 정리 종료

프롬프트 예시는 딱 Claude Code랑 동일한 감각으로 갑니다.

> 이 저장소의 README.md 기반으로 CONTRIBUTING.md 초안을 만들어줘.
  커밋 메시지 규칙 섹션은 Conventional Commits로.

내부적으로 파일을 읽고 diff를 만들어 제안합니다. 실행 전 확인 단계가 있으니 그 때 검토 후 승인하면 됩니다.

5. 트러블슈팅 — Windows에서 인증 루프에 빠지는 경우

Gemini CLI 공식 이슈 트래커와 개발 커뮤니티에 자주 올라오는 패턴 중 하나입니다. Windows + 사내 네트워크 조합에서 가장 빈번하게 보고됩니다.

증상

gemini 첫 실행 후 브라우저 OAuth 창이 떠서 로그인은 완료되는데, 터미널로 돌아오면 다시 로그인 URL만 반복 출력됩니다. 세션이 붙질 않습니다.

Please open the following URL in your browser to log in:
https://accounts.google.com/o/oauth2/...

원인

OAuth 콜백이 로컬 루프백 포트로 들어오는데, Windows Defender 방화벽이나 사내 VPN이 해당 포트를 차단하는 경우가 있습니다. 로그인은 끝났지만 CLI가 응답 토큰을 받지 못해 타임아웃 되는 구조입니다.

해결

두 가지 중 하나로 우회합니다. 사내 네트워크처럼 방화벽 정책을 바꿀 수 없는 환경이면 2번이 더 빠릅니다.

1. 방화벽에서 Node.js 실행 파일 예외 허용 후 재시도.
2. Google AI Studio에서 API 키를 직접 발급해 GEMINI_API_KEY 환경 변수로 주입. 이 방식은 OAuth 콜백 자체를 쓰지 않습니다.

[System.Environment]::SetEnvironmentVariable("GEMINI_API_KEY","<키>","User")
# 새 터미널 열고 다시 gemini 실행

6. 무료 티어를 가장 빠르게 소진시키는 패턴

Gemini CLI를 처음 쓰는 사람들이 가장 많이 빠지는 함정 중 하나가 "한 세션에 큰 컨텍스트를 몽땅 밀어 넣고 계속 끌고 가는" 사용법입니다. 토이 프로젝트 리팩토링이나 대규모 코드베이스 탐색을 할 때 특히 자주 발생합니다.

 

증상은 간단합니다. 세션이 길어질수록 같은 파일을 여러 번 다시 읽는 비효율이 쌓이고, 체감상 응답 속도가 느려지면서 무료 할당량이 빠르게 줄어듭니다. 원인은 /memory와 /chat save를 거의 안 쓰고 한 세션을 계속 끌고 가는 데 있습니다. 세션 컨텍스트가 커질수록 토큰 소모가 누적되기 때문입니다. 해결은 단순합니다. 큰 작업 단위마다 /chat save로 스냅샷을 찍고, 새로운 맥락은 새 세션을 시작하는 습관 하나면 됩니다.

 

팀에서 500건+ 코드 리뷰하면서 본 패턴도 같습니다. CLI든 IDE든 "컨텍스트를 작게 끊어 쓰는 사람"이 결국 가장 오래, 싸게 씁니다.

7. Claude Code vs Gemini CLI — 실무 관점 트레이드오프

두 CLI를 같은 저장소에서 번갈아 쓰면서 느낀 지점들입니다. 단일 정답은 없고 프로젝트 성격에 따라 갈립니다.

항목	Claude Code	Gemini CLI
무료 사용	별도 플랜 필요	개인 구글 로그인 무료 티어 존재
설정 디렉터리	.claude/	.gemini/
MCP 지원	공식	공식
강점 체감	긴 리팩토링·리뷰 연속성	빠른 탐색·문서화·요약
약점 체감	유료 허들	대규모 코드 변경 시 호흡이 다름

장점은 Gemini CLI의 무료 진입 장벽이 낮다는 점이고, 단점은 동일한 에이전틱 CLI라도 출력 스타일·툴 호출 패턴이 달라서 "Claude Code처럼 쓰면 Claude Code만큼 나온다"는 기대가 깨질 때가 있다는 점입니다.
팀 단위 도입을 고민 중이라면, 팀원 3명 미만이고 개인 학습 위주이면 Gemini CLI부터 깔아 보고, 팀이 5명을 넘고 동일 저장소에 여러 명이 동시에 에이전트를 붙이는 구조라면 두 CLI 모두 .gitignore 규칙을 맞춰 병행 운용하는 쪽이 낫다고 판단합니다.

8. 팀 공유 설정 — .gemini/ 규칙 잡기

저장소 루트에 .gemini/ 디렉터리를 두고, 팀 공용 프롬프트·MCP 설정을 Git에 커밋합니다. 개인 토큰·인증 캐시는 반드시 .gitignore로 따로 빼주세요.

# 개인 인증·캐시 (커밋 금지)
.gemini/oauth_creds.json
.gemini/.cache/

# 팀 공용 설정은 커밋
!.gemini/settings.json
!.gemini/GEMINI.md

GEMINI.md에는 "이 저장소에서 에이전트가 지켜야 할 규칙"을 써둡니다. Claude Code의 CLAUDE.md와 같은 역할이라 두 파일을 각각 두면 두 CLI를 같은 저장소에서 안전하게 병행할 수 있습니다.

9. 마무리 — Gemini CLI 사용법, 언제 쓰면 좋은가

정답은 없습니다. 다음 기준으로 판단하면 선택이 쉬워집니다.

• 개인 학습·사이드 프로젝트라서 과금 허들을 먼저 없애고 싶다 → Gemini CLI
• 이미 Claude Code 워크플로우(gstack 등)가 자리잡혔고 장시간 리팩토링이 주 업무다 → Claude Code 유지
• 두 가지 다 필요하다 → 위 .gitignore 규칙으로 병행

Gemini CLI 사용법 자체는 단순합니다. 설치 → 로그인 → 프롬프트, 3단계면 됩니다. 중요한 건 세션을 작게 끊는 습관, 그리고 Claude Code와의 차이점을 머릿속에서 미리 구분해 두는 것입니다. 이 부분만 잡혀 있으면 같은 터미널에서 두 에이전트를 상황에 맞게 바꿔 쓰는 경험이 꽤 매끄러워집니다.

 

블로그에 Claude·Gemini 등 다른 AI 도구 세팅 가이드도 같이 올려뒀으니, 에이전틱 CLI를 팀에 도입하는 흐름을 같이 보고 싶으면 AI 활용법 카테고리 쪽도 한번 둘러봐 주세요.

자주 묻는 질문

Q. Gemini CLI는 무료로 어디까지 쓸 수 있나요?
A. 개인 구글 계정 OAuth 로그인만으로 일정 요청까지 무료 사용이 가능합니다. 정확한 일일 한도는 시점마다 변동되며, 무료 한도를 넘기면 응답이 느려지거나 큐에 들어가는 식으로 제한이 걸립니다. 본격적으로 쓰려면 Google AI Studio에서 API 키를 발급받아 GEMINI_API_KEY 환경 변수로 주입하는 방식이 안정적입니다.

Q. Claude Code와 Gemini CLI는 뭐가 다른가요?
A. 둘 다 "터미널에서 파일을 읽고 고치고 명령을 실행하는" 에이전틱 CLI 카테고리에 속합니다. 가장 큰 차이는 무료 진입 장벽으로, Gemini CLI는 개인 구글 계정 무료 티어가 명시적으로 존재합니다. 반면 Claude Code는 긴 리팩토링·연속 코드 리뷰 호흡에서 강한 편이라는 후기가 많습니다. 두 도구는 같은 저장소에서 병행 사용이 가능합니다.

Q. Windows에서 OAuth 인증 루프에 빠지면 어떻게 해결하나요?
A. 사내 네트워크나 Windows Defender 방화벽이 OAuth 콜백 포트를 차단해서 발생하는 경우가 흔합니다. 두 가지 우회 방법이 있습니다. 첫째, 방화벽에서 Node.js 실행 파일 예외를 허용한 뒤 재시도. 둘째, Google AI Studio에서 API 키를 발급해 GEMINI_API_KEY 환경 변수로 주입하면 OAuth 콜백 자체를 쓰지 않습니다.

Q. Gemini CLI 설치 전에 어떤 준비물이 필요한가요?
A. 최신 Node.js만 있으면 됩니다. 공식 저장소는 Node 20 이상을 요구하며, Node v24에서 동작이 검증되어 있습니다. 설치 명령은 npm install -g @google/gemini-cli 한 줄이고, 설치 후 gemini --version으로 확인하면 됩니다.

Q. 무료 티어 할당량을 빠르게 소진시키지 않으려면?
A. 한 세션에 큰 컨텍스트를 몽땅 밀어 넣고 계속 끌고 가지 마세요. 큰 작업 단위마다 /chat save로 스냅샷을 찍고, 새로운 맥락은 새 세션을 시작하는 습관 하나면 토큰 누적을 크게 줄일 수 있습니다.

📎 이 카테고리의 다른 글

• Google Antigravity 사용법 — 설치부터 첫 워크스페이스까지 핵심 정리 — 발행 예정

같은 AI 활용법 카테고리에서 이어서 읽기

---

설치 환경: Windows 11, Node.js v24, Gemini CLI 0.x