Gemini CLI 시작하기

공식 레퍼런스: 개요 · 설치 · 인증 · GEMINI.md

왜 Gemini CLI를 따로 봐야 할까?

Gemini CLI는 Google의 오픈소스 터미널 에이전트입니다. 지금 기준으로 보면 강점은 명확합니다. Gemini 모델, 로컬 도구, 웹 접근, 프로젝트 메모리를 한 CLI 안에 묶어 둔 형태입니다.

이 프로젝트 같은 문서/콘텐츠 저장소에서는 특히 아래 상황에서 강합니다.

큰 저장소 빠르게 이해하기 — 100만 토큰 컨텍스트로 구조를 넓게 볼 수 있습니다.
로컬 파일 + 웹 정보 같이 다루기 — 파일 읽기, 셸 실행, 웹 검색을 한 흐름에서 이어갈 수 있습니다.
지시문 재사용 — GEMINI.md에 프로젝트 규칙을 적어 두면 매번 프롬프트를 길게 쓰지 않아도 됩니다.

설치는 이렇게 가면 됩니다

공식 문서 기준 Gemini CLI는 **Node.js 20+**를 권장합니다.

# npm 전역 설치
npm install -g @google/gemini-cli
 
# macOS / Linux
brew install gemini-cli
 
# 설치 없이 체험
npx @google/gemini-cli

최신 GitHub 버전을 바로 시험해 보고 싶다면 공식 저장소 실행도 가능합니다.

npx https://github.com/google-gemini/gemini-cli

인증은 사용 방식에 맞춰 고르기

공식 문서는 인증 경로를 꽤 분명하게 나눕니다.

상황	추천 방식	메모
개인 로컬 사용	Google 계정 로그인	가장 쉬운 기본값
스크립트 / CI / 헤드리스	Gemini API 키	환경변수 기반으로 단순
GCP 중심 조직 환경	Vertex AI	기존 Google Cloud 운영 방식과 잘 맞음
회사 / 학교 / Workspace 계정	Google 로그인 + 프로젝트 설정	Cloud 프로젝트가 필요한 경우가 많음

2) Gemini API 키 사용

헤드리스 실행이나 자동화에는 이 경로가 가장 실용적입니다.

export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
gemini

3) Vertex AI 사용

팀이 이미 Google Cloud에서 모델 접근을 관리하고 있다면 이쪽이 자연스럽습니다.

export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"
gemini

먼저 익혀 둘 명령 패턴과 워크플로

Gemini CLI는 긴 자연어만 던질 때보다, 도구 문법과 워크플로를 같이 쓸 때 훨씬 좋습니다.

기본 대화 및 도구 사용

# 대화형 모드 시작
gemini
 
# @로 파일/디렉터리 포함
gemini "@package.json @src 앱 아키텍처를 설명해줘"
 
# !로 셸 명령 실행 (결과를 에이전트가 읽고 판단)
!npm test

핵심 워크플로: 조사 -> 전략 -> 실행

단순한 채팅을 넘어, 에이전트에게 명확한 단계별 지시를 내리는 것이 실무 베스트 프랙티스입니다.

조사 (Research): 파일과 디렉터리를 탐색(grep_search, glob)하여 현황을 파악하게 합니다.
전략 (Strategy): 코드를 수정하기 전, 어떻게 접근할지 설계하고 사용자에게 계획을 공유하게 합니다.
실행 (Execution): 확정된 계획을 바탕으로 파일을 수정(replace, write_file)하고 검증(run_shell_command)합니다.

대규모 리팩터링이나 구조를 잡을 때는 섣불리 코드를 수정하지 않는 것이 좋습니다. 이때 /plan 명령어를 입력해 Plan Mode로 진입하세요. 이 모드에서는 에이전트가 파일을 수정할 수 없으며, 오직 "읽기 전용 도구"를 사용해 아키텍처를 조사하고 완벽한 설계 문서를 작성하는 데 집중합니다. 계획이 확정되면 수동으로 기본 모드로 돌아와 안전하게 실행할 수 있습니다.

진짜 핵심은 `GEMINI.md`

많은 팀이 설치만 해 보고 끝나는데, 실전 생산성 차이는 여기서 납니다. Gemini CLI는 GEMINI.md를 계층적으로 읽습니다.

~/.gemini/GEMINI.md
워크스페이스 및 상위 경로의 컨텍스트 파일
특정 디렉터리를 건드릴 때 즉시 발견되는 JIT 컨텍스트 파일

예시 `GEMINI.md`

# Project: AI Native Notes
 
## Stack
- Next.js 16
- TypeScript
- next-intl
- /content 기반 MDX 구조
 
## Content rules
- 로케일별 frontmatter 구조를 동일하게 유지
- 마케팅 문구보다 실전 예시 우선
- ko / en / es slug를 맞춘다
 
## Safety
- 문서 확인 없이 CLI 플래그를 지어내지 말 것
- 추정보다 공식 Gemini CLI 동작을 우선할 것

같이 알아두면 좋은 메모리 명령

/memory show
/memory reload
/memory add Always preserve locale parity when editing content.

Claude Code / GPT Codex / Gemini CLI 비교

항목	Claude Code	GPT Codex	Gemini CLI
핵심 지시 파일	CLAUDE.md	AGENTS.md	GEMINI.md
컨텍스트 성격	대화형 메모리 강점	태스크 단위 실행	계층형 메모리 + 대형 컨텍스트
로컬 도구 접근	로컬 + MCP	샌드박스 중심	로컬 도구 + 웹 + MCP + 서브 에이전트
첫 사용 추천	함께 고치며 탐색	경계가 분명한 구현 작업	저장소 이해 + 자동화 + 대형 리팩터링

다음에 읽으면 좋은 글

저장소 단위 분석 패턴은 100만 토큰 컨텍스트 활용법
실전적인 도구 연결은 Gemini CLI MCP 연동
복잡한 구현을 위한 Gemini Task Decomposition
복잡한 작업 위임은 서브 에이전트와 스킬
스크립트/CI는 Headless Automation