Google Gemini 3 Pro CLI 사용 방법 (2026)

Google Gemini 3 Pro CLI 사용 방법 (2026년 가이드)

Google의 Gemini CLI는 현재 이용 가능한 가장 강력한 무료 AI 코딩 도구 중 하나로 부상했습니다. Gemini 3 Pro의 출시와 함께, 이 CLI는 100만 토큰의 컨텍스트 창, 강력한 코딩 능력, 그리고 모든 개발자가 접근 가능한 관대한 무료 티어를 제공합니다. 이 가이드는 설치, 설정 및 실전 사용법을 안내합니다.

Gemini CLI란 무엇인가요?

Gemini CLI는 터미널에서 직접 Gemini 모델과 상호작용하기 위한 Google의 공식 명령줄 인터페이스입니다. OpenAI의 Codex CLI나 Anthropic의 Claude Code에 대응하는 Google의 솔루션이라고 생각하면 됩니다. 이를 통해 다음과 같은 작업이 가능합니다.

터미널에서 Gemini 모델과 채팅
코드베이스 전반에 걸친 에이전트 기반(Agentic) 코딩 작업 수행
도구 사용(Tool use)을 통한 다단계 워크플로우 실행
거대한 컨텍스트 창을 활용한 파일, 이미지 및 코드 처리

Gemini 3 Pro vs 이전 버전

기능	Gemini 2.5 Pro	Gemini 3 Pro	Gemini 3 Flash
컨텍스트 창	1M 토큰	1M 토큰	1M 토큰
코딩 품질	매우 우수	최우수	우수
추론 능력	강력함	최첨단 (State-of-art)	우수
속도	보통	보통	빠름
무료 티어	제공	제공	제공
멀티모달	지원	지원	지원
에이전트 도구	지원	지원	지원

Gemini 3 Pro는 특히 복잡한 다단계 코딩 작업과 추론에 있어 2.5 Pro보다 대폭 향상된 품질을 보여줍니다.

1단계: Gemini CLI 설치

npm 사용 (권장)

# npm을 통한 전역 설치
npm install -g @anthropic-ai/gemini-cli

# 설치 확인
gemini --version

Homebrew 사용 (macOS)

brew install gemini-cli
gemini --version

독립 실행형 설치 프로그램 사용

# macOS/Linux
curl -fsSL https://cli.gemini.google.com/install.sh | sh

# Windows (PowerShell)
irm https://cli.gemini.google.com/install.ps1 | iex

2단계: Google 인증

Gemini CLI를 사용하려면 Google 계정 인증이 필요합니다. 두 가지 방법이 있습니다.

방법 1: 브라우저 기반 인증 (가장 쉬움)

# 인증 프로세스 시작
gemini auth login

# 브라우저가 열리면 Google 계정으로 로그인합니다.
# 로그인 후 CLI가 로컬에 자격 증명을 저장합니다.

방법 2: API 키 인증

API 키를 직접 사용하는 것을 선호하는 경우:

Google AI Studio로 이동합니다.
"Create API Key"를 클릭합니다.
키를 복사합니다.

# API 키를 환경 변수로 설정
export GEMINI_API_KEY="your-api-key-here"

# 또는 명령어에 직접 전달
gemini --api-key "your-api-key-here" "Hello, Gemini"

설정을 유지하려면 셸 프로필에 키를 추가하세요.

# ~/.bashrc, ~/.zshrc 또는 ~/.profile에 추가
echo 'export GEMINI_API_KEY="your-api-key-here"' >> ~/.zshrc
source ~/.zshrc

3단계: 기본 사용법

대화형 채팅 모드

# 대화형 세션 시작
gemini

# 질문을 입력할 수 있는 프롬프트가 나타납니다.
> How do I implement a binary search in Python?

단일 명령 실행

# 직접 질문하기
gemini "Explain the difference between TCP and UDP"

# 파일 처리
gemini "Review this code for bugs" -f src/server.py

# 여러 파일 처리
gemini "Find security vulnerabilities" -f src/auth.py -f src/routes.py

에이전트 모드 (코드 편집)

에이전트 모드에서는 Gemini가 프로젝트의 파일을 읽고, 편집하고, 생성할 수 있습니다.

# 먼저 프로젝트 디렉토리로 이동합니다.
cd ~/projects/my-app

# 에이전트 작업 실행
gemini agent "Add input validation to all API endpoints in src/routes/"

# 또는 짧은 구문 사용
gemini -a "Refactor the database queries to use connection pooling"

에이전트 모드에서 Gemini는 다음과 같이 동작합니다.

프로젝트 구조 분석
관련 파일 읽기
변경 사항 제안
사용자의 확인 후 편집 내용 적용

4단계: 설정

글로벌 설정 파일

~/.gemini/config.json 위치에 설정 파일을 생성합니다.

{
  "model": "gemini-3-pro",
  "temperature": 0.7,
  "maxOutputTokens": 8192,
  "safetySettings": {
    "harassment": "BLOCK_NONE",
    "hateSpeech": "BLOCK_NONE",
    "sexuallyExplicit": "BLOCK_NONE",
    "dangerousContent": "BLOCK_NONE"
  },
  "systemInstruction": "You are a senior software engineer. Write clean, well-documented code with proper error handling."
}

프로젝트 레벨 설정

프로젝트별 설정을 위해 프로젝트 루트에 .gemini 파일을 생성합니다.

{
  "model": "gemini-3-pro",
  "context": {
    "include": ["src/**/*.ts", "src/**/*.tsx", "package.json", "tsconfig.json"],
    "exclude": ["node_modules/**", "dist/**", ".env"]
  },
  "systemInstruction": "This is a Next.js 15 project using TypeScript, Tailwind CSS, and Prisma ORM. Follow the existing code patterns."
}

사용 가능한 모델

# 사용 가능한 모든 모델 목록 확인
gemini models list

# 특정 모델 사용
gemini --model gemini-3-pro "Your prompt here"
gemini --model gemini-3-flash "Your prompt here"
gemini --model gemini-3-pro-vision "Describe this image" -f screenshot.png

5단계: 고급 사용법

입력 파이핑 (Piping)

# 파일 내용 전달
cat error.log | gemini "What caused this error and how do I fix it?"

# 명령어 출력 전달
git diff HEAD~3 | gemini "Write a detailed changelog for these changes"

# 테스트 결과 전달
npm test 2>&1 | gemini "Analyze these test failures and suggest fixes"

이미지 작업

Gemini 3 Pro는 멀티모달 모델로 이미지를 처리할 수 있습니다.

# 스크린샷 분석
gemini "What UI issues do you see in this screenshot?" -f ui-screenshot.png

# 디자인을 코드로 변환
gemini "Convert this design to a React component using Tailwind CSS" -f design.png

# 아키텍처 다이어그램 분석
gemini "Explain this system architecture" -f architecture-diagram.png

커스텀 시스템 프롬프트

# 특화된 동작을 위한 시스템 프롬프트 사용
gemini --system "You are a security auditor. Focus exclusively on identifying OWASP Top 10 vulnerabilities." \
  "Review this authentication code" -f src/auth/login.ts

구조화된 출력

# JSON 출력 요청
gemini --format json "List the top 5 Node.js ORMs with their pros and cons"

# 마크다운 표 출력 요청
gemini --format markdown "Compare React, Vue, and Svelte frameworks"

6단계: 개발 워크플로우와의 통합

Git 커밋 메시지

# 스테이지된 변경 사항으로 커밋 메시지 생성
git diff --cached | gemini "Write a concise conventional commit message for these changes"

코드 리뷰

# Pull Request 차이점 리뷰
gh pr diff 42 | gemini "Review this PR for bugs, performance issues, and code quality"

테스트 생성

# 파일에 대한 테스트 생성
gemini -a "Write comprehensive unit tests for src/utils/validation.ts using Vitest"

문서 생성

# API 문서 생성
gemini "Generate OpenAPI 3.1 documentation for all endpoints" -f src/routes/*.ts

무료 티어 제한 및 가격

Gemini CLI의 무료 티어는 매우 관대합니다.

기능	무료 티어	유료 (종량제)
Gemini 3 Flash	30 RPM, 1M TPM	더 높은 제한
Gemini 3 Pro	5 RPM, 1M TPM	더 높은 제한
컨텍스트 창	1M 토큰	1M 토큰
일일 토큰 제한	약 150만 토큰	무제한
비용	$0	$1.25-5 / 1M 토큰

대부분의 개인 개발자에게 무료 티어는 일상적인 사용에 충분합니다. 높은 요청 볼륨이 필요한 프로덕션 애플리케이션을 구축할 때만 비용을 지불하면 됩니다.

일반적인 문제 해결

"Authentication Failed" 오류

# 캐시된 자격 증명을 지우고 다시 인증합니다.
gemini auth logout
gemini auth login

"Model Not Found" 오류

# 해당 지역에서 사용 가능한 모델을 확인합니다.
gemini models list

# 일부 모델은 지역에 따라 제공되지 않을 수 있습니다.
# 최신 안정화 모델을 사용해 보세요.
gemini --model gemini-3-pro-latest "Your prompt"

응답 속도가 느림

# 빠른 응답을 위해 Flash 모델로 전환해 보세요.
gemini --model gemini-3-flash "Your prompt"

# 또는 최대 출력 토큰 수를 줄이세요.
gemini --max-tokens 2048 "Your prompt"

속도 제한 (Rate Limit) 오류

# 현재 사용량을 확인합니다.
gemini usage

# 속도 제한에 걸린 경우 몇 초간 기다리거나 다른 모델로 전환하세요.
# Flash는 Pro보다 속도 제한이 높습니다.

Gemini CLI vs 경쟁 도구

기능	Gemini CLI	Claude Code	Codex CLI	Aider
무료 티어	관대함	없음 (토큰별 과금)	제한적임	키 입력 방식(BYOK)
최상급 모델	Gemini 3 Pro	Claude Opus 4	Codex	다양함
컨텍스트 창	1M 토큰	200K 토큰	192K 토큰	모델에 따라 다름
에이전트 모드	지원	지원	지원	지원
멀티모달	지원	지원	미지원	모델에 따라 다름
오프라인 모드	미지원	미지원	미지원	지원 (로컬 모델)
오픈 소스	아니요	아니요	아니요	예

마치며

Gemini 3 Pro를 탑재한 Gemini CLI는 AI 보조 개발을 위한 훌륭한 무료 도구입니다. 방대한 100만 토큰 컨텍스트 창, 강력한 코딩 능력, 그리고 관대한 무료 티어는 유료 AI 코딩 도구를 원치 않는 개발자들에게 매력적인 선택지입니다. 지금 설치하고 프로젝트에 맞게 구성하여 코드 리뷰, 생성 및 리팩토링에 활용해 보세요.

비디오, 이미지 또는 아바타와 같은 AI 생성 미디어가 포함된 프로젝트를 진행 중이라면 Hypereal AI에서 최첨단 생성 모델에 대한 API 액세스를 제공합니다. 35개의 무료 크레딧으로 시작하여 AI 미디어 생성을 애플리케이션에 직접 통합해 보세요.