Gemini CLI

Gemini CLI는 구글이 만든 오픈소스 AI 에이전트예요. 터미널 안에서 바로 Gemini 모델을 쓸 수 있게 해주는데요, 굳이 IDE나 별도 앱을 띄울 필요 없이 프롬프트 한 줄에서 모델까지 가장 직접적인 경로를 제공하는 게 핵심이에요. 개인 Google 계정으로 로그인하면 무료 티어(분당 60회, 하루 1,000회 요청)로 바로 시작할 수 있고, Apache 2.0 라이선스로 완전히 오픈소스라 누구나 코드를 열어볼 수 있죠.

개발자들이 커맨드 라인에서 사는 사람이라면 특히 잘 맞아요. 코드베이스를 질문하고 수정하고, 이미지나 PDF에서 새 앱을 생성하고, GitHub PR 리뷰까지 자동화할 수 있어요. 문서화된 기능이 풍부하고 MCP(Mode Context Protocol)로 확장도 가능해서, 단순한 CLI 채팅이 아니라 개발 워크플로 전체를 맡길 수 있는 도구예요.

출처: 문서

본문

왜 Gemini CLI인가요?

다른 사람들이 Gemini CLI를 고르는 이유를 먼저 정리해 볼게요.

무료 티어: 개인 Google 계정으로 분당 60회, 하루 1,000회 요청을 쓸 수 있어요.
강력한 Gemini 3 모델: 향상된 추론 능력과 1M 토큰 컨텍스트 윈도우를 제공해요.
내장 도구: Google Search grounding, 파일 조작, 셸 명령어, 웹 페칭이 기본으로 들어 있어요.
확장 가능: MCP(Model Context Protocol)로 커스텀 통합을 추가할 수 있어요.
터미널 우선: 커맨드 라인에서 개발하는 사람을 위해 설계됐어요.
오픈소스: Apache 2.0 라이선스예요.

설치

권장 시스템 사양과 상세 설치 가이드는 공식 설치 문서에서 확인할 수 있어요. 빠르게 시작하는 방법부터 하나씩 볼게요.

npx로 바로 실행 (설치 불필요)

# Using npx (no installation required)
npx @google/gemini-cli

npm으로 전역 설치

npm install -g @google/gemini-cli

Homebrew (macOS/Linux)

brew install gemini-cli

MacPorts (macOS)

sudo port install gemini-cli

Anaconda (제한된 환경에서)

# Create and activate a new environment
conda create -y -n gemini_env -c conda-forge nodejs
conda activate gemini_env

# Install Gemini CLI globally via npm (inside the environment)
npm install -g @google/gemini-cli

설치 후에는 gemini 명령어로 실행하면 됩니다.

릴리스 채널

Gemini CLI는 Preview, Stable, Nightly 세 가지 채널로 배포돼요. 각자의 상황에 맞는 태그로 설치하면 돼요.

Preview — 매주 화요일 UTC 23:59에 발표되고, 완전히 검증되지 않아 회귀나 이슈가 있을 수 있어요. 테스트 목적이라면 preview 태그로 설치해요.

npm install -g @google/gemini-cli@preview

Stable — 매주 화요일 UTC 20:00에 발표되는데, 지난주 preview 릴리스를 정식 승격한 버전에 버그 수정이 더해진 거예요. latest 태그를 써요.

npm install -g @google/gemini-cli@latest

Nightly — 매일 UTC 00:00에 main 브랜치 기준으로 발표돼요. 검증이 진행 중인 변경이 있을 수 있다고 보면 돼요. nightly 태그를 써요.

npm install -g @google/gemini-cli@nightly

주요 기능

코드 이해 및 생성에서 할 수 있는 일이에요. 큰 코드베이스를 질문하고 수정할 수 있고, 멀티모달 기능으로 PDF·이미지·스케치에서 새 앱을 만들 수도 있어요. 자연어로 버그를 디버깅하고 트러블슈팅하는 데도 유용하죠.

자동화 및 통합도 강점이에요. PR 조회 같은 운영 작업이나 복잡한 rebase 처리 같은 걸 자동화할 수 있고, MCP 서버로 새 기능을 연결해요. 예를 들어 Imagen, Veo, Lyria로 미디어 생성이 가능해요. 스크립트 안에서 비대화형으로 실행해 워크플로 자동화에도 쓸 수 있어요.

고급 기능으로는 내장 Google Search grounding으로 실시간 정보를 얻을 수 있고, 복잡한 세션을 저장하고 이어서 하는 체크포인팅, 프로젝트마다 동작을 다르게 하는 커스텀 컨텍스트 파일(GEMINI.md)도 지원해요.

GitHub 통합

Gemini CLI GitHub Action으로 GitHub 워크플로에 직접 통합할 수 있어요.

Pull Request 리뷰: 컨텍스트 있는 피드백과 제안으로 자동 코드 리뷰
Issue 트리아지: 내용 분석 기반으로 GitHub 이슈에 자동 라벨링과 우선순위 지정
온디맨드 도움: 이슈와 PR에서 @gemini-cli를 멘션하면 디버깅·설명·작업 위임을 도와줘요
커스텀 워크플로: 팀 니즈에 맞는 자동·예약·온디맨드 워크플로를 만들 수 있어요

인증 옵션

상황에 맞는 인증 방식을 골라 쓰면 돼요.

옵션 1: Google로 로그인 (OAuth)

개인 개발자나 Gemini Code Assist 라이선스가 있는 사람에게 좋아요. 특정 모델을 고를 필요 없다면 간편한 선택이에요. 세부 내용은 quota limits and terms of service를 확인해요.

무료 티어: 분당 60회, 하루 1,000회 요청
Gemini 3 모델: 1M 토큰 컨텍스트 윈도우
API 키 관리 불필요: Google 계정으로 로그인만 하면 돼요
최신 모델 자동 업데이트

gemini

조직에서 유료 Code Assist 라이선스를 쓴다면 Google Cloud 프로젝트를 함께 설정해요.

# Set your Google Cloud Project
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
gemini

옵션 2: Gemini API 키

특정 모델을 직접 골라야 하거나 유료 티어가 필요하다면 이 방식을 써요.

무료 티어: Gemini 3 기준 하루 1,000회 요청 (flash와 pro 혼합)
모델 선택: 원하는 Gemini 모델을 직접 지정
사용량 기반 과금: 필요할 때 한도 업그레이드 가능

# Get your key from https://aistudio.google.com/apikey
export GEMINI_API_KEY="YOUR_API_KEY"
gemini

옵션 3: Vertex AI

엔터프라이즈 팀이나 프로덕션 워크로드에 적합해요.

엔터프라이즈 기능: 고급 보안과 컴플라이언스
확장성: 결제 계정 기반의 높은 요청 한도
통합: 기존 Google Cloud 인프라와 연동

# Get your key from Google Cloud Console
export GOOGLE_API_KEY="YOUR_API_KEY"
export GOOGLE_GENAI_USE_VERTEXAI=true
gemini

Google Workspace 계정이나 다른 인증 방식은 authentication guide를 참고해요.

시작하기

기본 사용법

현재 디렉터리에서 시작하려면 그냥 실행하면 돼요.

gemini

여러 디렉터리를 포함하고 싶다면 아래처럼 써요.

gemini --include-directories ../lib,../docs

특정 모델을 지정할 수도 있어요.

gemini -m gemini-2.5-flash

스크립트용 비대화형 모드

단순 텍스트 응답을 받으려면 -p 플래그를 써요.

gemini -p "Explain the architecture of this codebase"

JSON을 파싱하거나 에러를 처리하는 등 고급 스크립팅이 필요하면 --output-format json으로 구조화된 출력을 받을 수 있어요.

gemini -p "Explain the architecture of this codebase" --output-format json

오래 걸리는 작업을 모니터링하면서 실시간 이벤트 스트리밍이 필요할 때는 --output-format stream-json으로 newline-delimited JSON 이벤트를 받아요.

gemini -p "Run tests and deploy" --output-format stream-json

빠른 예시

새 프로젝트를 시작하는 경우예요.

cd new-project/
gemini
> Write me a Discord bot that answers questions using a FAQ.md file I will provide

기존 코드를 분석할 때는 이렇게 활용할 수 있어요.

git clone https://github.com/google-gemini/gemini-cli
cd gemini-cli
gemini
> Give me a summary of all of the changes that went in yesterday

MCP 서버 사용

~/.gemini/settings.json에 MCP 서버를 설정하면 커스텀 도구로 확장할 수 있어요.

> @github List my open pull requests
> @slack Send a summary of today's commits to #dev channel
> @database Run a query to find inactive users

설정 방법은 MCP Server Integration guide에서 확인할 수 있어요.

문서 리소스

공식 문서는 여러 주제로 잘 나뉘어 있어요.

시작하기 — Quickstart Guide, Authentication Setup, Configuration Guide, Keyboard Shortcuts

핵심 기능 — Commands Reference(/help, /chat 등 슬래시 커맨드), Custom Commands, Context Files (GEMINI.md), Checkpointing, Token Caching

도구 및 확장 — File System Operations, Shell Commands, Web Fetch & Search, MCP Server Integration, Custom Extensions

고급 주제 — Headless Mode (Scripting), IDE Integration(VS Code companion), Sandboxing & Security, Trusted Folders, Enterprise Guide, Telemetry & Monitoring, Local development

트러블슈팅 및 지원 — Troubleshooting Guide, FAQ. CLI 안에서 /bug 명령어로 바로 이슈를 리포트할 수도 있어요.

오픈소스와 컨트리뷰션

Gemini CLI는 완전한 오픈소스(Apache 2.0)라서 버그 리포트, 기능 제안, 문서 개선, 코드 기여, MCP 서버·확장 공유를 환영해요. 참여 방법은 Contributing Guide에서 확인할 수 있고, 예정된 기능은 Official Roadmap에서 볼 수 있어요.

무료 강좌로는 deeplearning.ai의 무료 코스가 기본기를 배우기 좋고, 변경 내역은 Changelog에서 확인할 수 있어요.

Gemini CLI

Gemini CLI

본문

왜 Gemini CLI인가요?

설치

npx로 바로 실행 (설치 불필요)

npm으로 전역 설치

Homebrew (macOS/Linux)

MacPorts (macOS)

Anaconda (제한된 환경에서)

릴리스 채널

주요 기능

GitHub 통합

인증 옵션

옵션 1: Google로 로그인 (OAuth)

옵션 2: Gemini API 키

옵션 3: Vertex AI

시작하기

기본 사용법

스크립트용 비대화형 모드

빠른 예시

MCP 서버 사용

문서 리소스

오픈소스와 컨트리뷰션

더 알아보기 (Learn more)