챕터 10 · L1
Gemini CLI 설치 및 시작
Google Gemini CLI 설치, 인증, 100만 토큰 컨텍스트 활용법
Gemini CLI를 설치하고 100만 토큰 컨텍스트로 대화를 시작할 수 있어요.
참고 문서
공개 문서
10. Gemini CLI 설치 및 시작
아래는 content/courses/10-gemini-install.mdx 와 동일한 원문입니다. Markdown과 HTML 변환 결과를 각각 복사할 수 있습니다.
공개 문서 원문 (Markdown)
# Gemini CLI 설치 및 시작
> **이 챕터를 마치면** Gemini CLI를 설치하고 100만 토큰 컨텍스트로 대화를 시작할 수 있어요.
Gemini CLI는 Google이 만든 오픈소스 AI 터미널 도구예요.
**100만 토큰 컨텍스트**가 가장 큰 강점이에요.
대규모 코드베이스 전체를 한 번에 분석하거나, 긴 문서를 처리하는 데 탁월해요.
> **전제 조건:** Node.js 18+ 설치 완료 ([설치 챕터](./02-installation) 참고)
---
## 설치
<div className="float-right w-full md:w-[40%] md:ml-6 mb-4 flex-shrink-0 not-prose">
<a href="https://www.npmjs.com/package/@google/gemini-cli" target="_blank" rel="noopener noreferrer" className="block rounded-lg overflow-hidden border border-slate-200 shadow-sm hover:shadow-md transition-shadow">
<img src="/images/gemini-install.png" alt="Gemini CLI npm 패키지 — @google/gemini-cli" className="w-full h-auto" />
</a>
</div>
```bash
npm install -g @google/gemini-cli
```
설치 확인:
```bash
gemini --version
# Gemini CLI 0.x.x
```
---
## 인증
### 방법 1: Google 계정 로그인 (무료 — 추천)
```bash
gemini
```
첫 실행 시 브라우저가 열리며 Google 계정으로 로그인합니다.
**무료 사용 한도 (2026 기준):**
- 분당 60 요청
- 일 1,500 요청
- 개인 사용에는 충분한 수준
### 방법 2: API Key 사용
[Google AI Studio](https://aistudio.google.com/)에서 API Key를 발급합니다.
```bash
export GEMINI_API_KEY="AIza..."
gemini
```
또는 `.env` 파일에 저장:
```bash
GEMINI_API_KEY=AIza...
```
---
## 첫 실행
프로젝트 폴더에서 실행합니다.
```bash
cd my-project
gemini
```
대화형 모드:
```
╔════════════════════════════════╗
║ Gemini CLI v0.x.x ║
╚════════════════════════════════╝
>
```
---
## 실행 모드
### 1. 대화형 모드 (기본)
```bash
gemini
```
### 2. 단일 명령 모드
```bash
gemini "이 프로젝트의 폴더 구조를 설명해줘"
```
### 3. 파이프 모드 — Gemini CLI의 진짜 강점
```bash
# 여러 파일을 한 번에 전달
find . -name "*.ts" | xargs cat | gemini "TypeScript 파일 전체를 분석해줘"
# 에러 로그 분석
cat error.log | gemini "이 에러의 원인을 한국어로 설명해줘"
# 특정 폴더 전체 분석
cat src/**/*.ts | gemini "코드 품질 이슈를 찾아줘"
```
---
## 100만 토큰 컨텍스트란?
토큰은 텍스트 처리 단위입니다. 대략적인 비교:
| 컨텍스트 창 | 도구 | 처리 가능 분량 |
|------------|------|----------------|
| 200K 토큰 | Claude Sonnet | 코드 약 15만 줄 |
| **1M 토큰** | **Gemini 2.5 Pro** | **코드 약 75만 줄** |
실제로는 이런 상황에서 차이가 납니다:
```bash
# 대형 오픈소스 라이브러리 전체 분석
find node_modules/next -name "*.ts" | head -100 | xargs cat | gemini "Next.js 소스에서 App Router 동작 원리를 설명해줘"
# 팀 프로젝트 전체 코드 리뷰
find src -name "*.tsx" | xargs cat | gemini "전체 컴포넌트에서 접근성(a11y) 문제를 찾아줘"
```
---
## Gemini CLI가 잘하는 것
**분석·리뷰 작업:**
```bash
# 보안 취약점 전수 조사
find . -name "*.ts" | xargs cat | gemini "OWASP Top 10 기준으로 보안 취약점을 찾아줘"
# 성능 최적화 포인트 발견
find src -name "*.tsx" | xargs cat | gemini "렌더링 성능 개선이 필요한 컴포넌트를 찾아줘"
# 문서화
find src -name "*.ts" | xargs cat | gemini "각 함수에 JSDoc 주석을 추가해줘"
```
**Gemini CLI가 상대적으로 약한 것:**
- 실시간 파일 수정 (→ Claude Code 활용)
- UI 작업과 시각적 확인 (→ Cursor 활용)
- 복잡한 멀티파일 리팩토링 (→ Claude Code 활용)
---
## 핵심 슬래시 커맨드
| 커맨드 | 설명 |
|--------|------|
| `/help` | 사용 가능한 커맨드 목록 |
| `/clear` | 대화 초기화 |
| `/quit` | Gemini CLI 종료 |
| `@파일명` | 특정 파일을 컨텍스트에 추가 |
---
## @파일 참조 기능
```bash
gemini
> @package.json 이 프로젝트의 의존성 중 보안 업데이트가 필요한 게 있어?
```
```bash
gemini
> @src/lib/auth.ts @src/app/api/login/route.ts 이 두 파일의 인증 로직에 취약점이 있어?
```
여러 파일을 한 번에 컨텍스트로 넣을 수 있습니다.
---
## 다음 단계
설치가 완료되었으면 Gemini CLI의 핵심 활용 사례인 **전체 코드베이스 리뷰**를 배워봅시다.
---
## 9장 보강 프로세스 적용: Gemini 설치 운영 표준
8장까지 적용한 동일 프로세스(대본 패턴 분석 → 실패 패턴 제거 → 실행형 체크리스트)를 10챕터에 적용합니다.
### 설치 성공 루틴 (권장)
1. 설치
2. 버전 확인
3. 인증
4. 첫 질의 실행
5. 파이프 모드 1회 검증
### 10챕터 실패 패턴 TOP 5
1. **`find|xargs cat`에 바이너리/불필요 파일 포함**
- 대응: `node_modules`, `.next`, `dist` 제외 패턴 고정
2. **너무 큰 입력을 무작정 전달**
- 대응: 목적별로 파일 범위를 나눠 단계 분석
3. **인증 방식 혼동**
- 대응: Google 로그인/키 방식 중 하나를 먼저 표준으로 선택
4. **무료 한도 관리 실패**
- 대응: 질문을 좁게 쓰고 핵심 파일만 전달
5. **검토 결과를 코드 수정으로 연결하지 못함**
- 대응: Gemini 결과를 Claude Code 작업 지시로 바로 변환
### 10챕터 체크리스트 (DoD)
- [ ] `gemini --version` 확인 완료
- [ ] 인증 완료 및 첫 대화 실행
- [ ] 파이프 입력 1회 이상 검증 완료
- [ ] 분석 범위 제외 규칙(`node_modules` 등) 적용 완료
- [ ] 발견 이슈를 다음 작업 지시문으로 변환 완료
> **다음 챕터 입력값:** 리뷰 질문 템플릿(보안/성능/타입), 제외 경로 규칙, 결과 정리 포맷공개 문서 변환 코드 (HTML)
<h1>Gemini CLI 설치 및 시작</h1>
<blockquote>
<p><strong>이 챕터를 마치면</strong> Gemini CLI를 설치하고 100만 토큰 컨텍스트로 대화를 시작할 수 있어요.</p>
</blockquote>
<p>Gemini CLI는 Google이 만든 오픈소스 AI 터미널 도구예요.
<strong>100만 토큰 컨텍스트</strong>가 가장 큰 강점이에요.
대규모 코드베이스 전체를 한 번에 분석하거나, 긴 문서를 처리하는 데 탁월해요.</p>
<blockquote>
<p><strong>전제 조건:</strong> Node.js 18+ 설치 완료 (<a href="./02-installation">설치 챕터</a> 참고)</p>
</blockquote>
<hr>
<h2>설치</h2>
<div className="float-right w-full md:w-[40%] md:ml-6 mb-4 flex-shrink-0 not-prose">
<a href="https://www.npmjs.com/package/@google/gemini-cli" target="_blank" rel="noopener noreferrer" className="block rounded-lg overflow-hidden border border-slate-200 shadow-sm hover:shadow-md transition-shadow">
<img src="/images/gemini-install.png" alt="Gemini CLI npm 패키지 — @google/gemini-cli" className="w-full h-auto" />
</a>
</div><pre><code class="language-bash">npm install -g @google/gemini-cli
</code></pre>
<p>설치 확인:</p>
<pre><code class="language-bash">gemini --version
# Gemini CLI 0.x.x
</code></pre>
<hr>
<h2>인증</h2>
<h3>방법 1: Google 계정 로그인 (무료 — 추천)</h3>
<pre><code class="language-bash">gemini
</code></pre>
<p>첫 실행 시 브라우저가 열리며 Google 계정으로 로그인합니다.</p>
<p><strong>무료 사용 한도 (2026 기준):</strong></p>
<ul>
<li>분당 60 요청</li>
<li>일 1,500 요청</li>
<li>개인 사용에는 충분한 수준</li>
</ul>
<h3>방법 2: API Key 사용</h3>
<p><a href="https://aistudio.google.com/">Google AI Studio</a>에서 API Key를 발급합니다.</p>
<pre><code class="language-bash">export GEMINI_API_KEY="AIza..."
gemini
</code></pre>
<p>또는 <code>.env</code> 파일에 저장:</p>
<pre><code class="language-bash">GEMINI_API_KEY=AIza...
</code></pre>
<hr>
<h2>첫 실행</h2>
<p>프로젝트 폴더에서 실행합니다.</p>
<pre><code class="language-bash">cd my-project
gemini
</code></pre>
<p>대화형 모드:</p>
<pre><code>╔════════════════════════════════╗
║ Gemini CLI v0.x.x ║
╚════════════════════════════════╝
>
</code></pre>
<hr>
<h2>실행 모드</h2>
<h3>1. 대화형 모드 (기본)</h3>
<pre><code class="language-bash">gemini
</code></pre>
<h3>2. 단일 명령 모드</h3>
<pre><code class="language-bash">gemini "이 프로젝트의 폴더 구조를 설명해줘"
</code></pre>
<h3>3. 파이프 모드 — Gemini CLI의 진짜 강점</h3>
<pre><code class="language-bash"># 여러 파일을 한 번에 전달
find . -name "*.ts" | xargs cat | gemini "TypeScript 파일 전체를 분석해줘"
# 에러 로그 분석
cat error.log | gemini "이 에러의 원인을 한국어로 설명해줘"
# 특정 폴더 전체 분석
cat src/**/*.ts | gemini "코드 품질 이슈를 찾아줘"
</code></pre>
<hr>
<h2>100만 토큰 컨텍스트란?</h2>
<p>토큰은 텍스트 처리 단위입니다. 대략적인 비교:</p>
<table>
<thead>
<tr>
<th>컨텍스트 창</th>
<th>도구</th>
<th>처리 가능 분량</th>
</tr>
</thead>
<tbody><tr>
<td>200K 토큰</td>
<td>Claude Sonnet</td>
<td>코드 약 15만 줄</td>
</tr>
<tr>
<td><strong>1M 토큰</strong></td>
<td><strong>Gemini 2.5 Pro</strong></td>
<td><strong>코드 약 75만 줄</strong></td>
</tr>
</tbody></table>
<p>실제로는 이런 상황에서 차이가 납니다:</p>
<pre><code class="language-bash"># 대형 오픈소스 라이브러리 전체 분석
find node_modules/next -name "*.ts" | head -100 | xargs cat | gemini "Next.js 소스에서 App Router 동작 원리를 설명해줘"
# 팀 프로젝트 전체 코드 리뷰
find src -name "*.tsx" | xargs cat | gemini "전체 컴포넌트에서 접근성(a11y) 문제를 찾아줘"
</code></pre>
<hr>
<h2>Gemini CLI가 잘하는 것</h2>
<p><strong>분석·리뷰 작업:</strong></p>
<pre><code class="language-bash"># 보안 취약점 전수 조사
find . -name "*.ts" | xargs cat | gemini "OWASP Top 10 기준으로 보안 취약점을 찾아줘"
# 성능 최적화 포인트 발견
find src -name "*.tsx" | xargs cat | gemini "렌더링 성능 개선이 필요한 컴포넌트를 찾아줘"
# 문서화
find src -name "*.ts" | xargs cat | gemini "각 함수에 JSDoc 주석을 추가해줘"
</code></pre>
<p><strong>Gemini CLI가 상대적으로 약한 것:</strong></p>
<ul>
<li>실시간 파일 수정 (→ Claude Code 활용)</li>
<li>UI 작업과 시각적 확인 (→ Cursor 활용)</li>
<li>복잡한 멀티파일 리팩토링 (→ Claude Code 활용)</li>
</ul>
<hr>
<h2>핵심 슬래시 커맨드</h2>
<table>
<thead>
<tr>
<th>커맨드</th>
<th>설명</th>
</tr>
</thead>
<tbody><tr>
<td><code>/help</code></td>
<td>사용 가능한 커맨드 목록</td>
</tr>
<tr>
<td><code>/clear</code></td>
<td>대화 초기화</td>
</tr>
<tr>
<td><code>/quit</code></td>
<td>Gemini CLI 종료</td>
</tr>
<tr>
<td><code>@파일명</code></td>
<td>특정 파일을 컨텍스트에 추가</td>
</tr>
</tbody></table>
<hr>
<h2>@파일 참조 기능</h2>
<pre><code class="language-bash">gemini
> @package.json 이 프로젝트의 의존성 중 보안 업데이트가 필요한 게 있어?
</code></pre>
<pre><code class="language-bash">gemini
> @src/lib/auth.ts @src/app/api/login/route.ts 이 두 파일의 인증 로직에 취약점이 있어?
</code></pre>
<p>여러 파일을 한 번에 컨텍스트로 넣을 수 있습니다.</p>
<hr>
<h2>다음 단계</h2>
<p>설치가 완료되었으면 Gemini CLI의 핵심 활용 사례인 <strong>전체 코드베이스 리뷰</strong>를 배워봅시다.</p>
<hr>
<h2>9장 보강 프로세스 적용: Gemini 설치 운영 표준</h2>
<p>8장까지 적용한 동일 프로세스(대본 패턴 분석 → 실패 패턴 제거 → 실행형 체크리스트)를 10챕터에 적용합니다.</p>
<h3>설치 성공 루틴 (권장)</h3>
<ol>
<li>설치</li>
<li>버전 확인</li>
<li>인증</li>
<li>첫 질의 실행</li>
<li>파이프 모드 1회 검증</li>
</ol>
<h3>10챕터 실패 패턴 TOP 5</h3>
<ol>
<li><p><strong><code>find|xargs cat</code>에 바이너리/불필요 파일 포함</strong></p>
<ul>
<li>대응: <code>node_modules</code>, <code>.next</code>, <code>dist</code> 제외 패턴 고정</li>
</ul>
</li>
<li><p><strong>너무 큰 입력을 무작정 전달</strong></p>
<ul>
<li>대응: 목적별로 파일 범위를 나눠 단계 분석</li>
</ul>
</li>
<li><p><strong>인증 방식 혼동</strong></p>
<ul>
<li>대응: Google 로그인/키 방식 중 하나를 먼저 표준으로 선택</li>
</ul>
</li>
<li><p><strong>무료 한도 관리 실패</strong></p>
<ul>
<li>대응: 질문을 좁게 쓰고 핵심 파일만 전달</li>
</ul>
</li>
<li><p><strong>검토 결과를 코드 수정으로 연결하지 못함</strong></p>
<ul>
<li>대응: Gemini 결과를 Claude Code 작업 지시로 바로 변환</li>
</ul>
</li>
</ol>
<h3>10챕터 체크리스트 (DoD)</h3>
<ul>
<li><input disabled="" type="checkbox"> <code>gemini --version</code> 확인 완료</li>
<li><input disabled="" type="checkbox"> 인증 완료 및 첫 대화 실행</li>
<li><input disabled="" type="checkbox"> 파이프 입력 1회 이상 검증 완료</li>
<li><input disabled="" type="checkbox"> 분석 범위 제외 규칙(<code>node_modules</code> 등) 적용 완료</li>
<li><input disabled="" type="checkbox"> 발견 이슈를 다음 작업 지시문으로 변환 완료</li>
</ul>
<blockquote>
<p><strong>다음 챕터 입력값:</strong> 리뷰 질문 템플릿(보안/성능/타입), 제외 경로 규칙, 결과 정리 포맷</p>
</blockquote>