설치

Gemini CLI를 다양한 방법으로 설치할 수 있습니다. 시스템 요구사항을 확인한 후 원하는 방법을 선택하세요.

시스템 요구사항

Node.js 사전 준비

Node.js 설치 여부 확인

터미널에서 아래 명령어로 Node.js가 설치되어 있는지, 버전은 충분한지 확인하세요.

node --version
# 예: v22.11.0 (20.0.0 이상이면 OK)

npm --version
# 예: 10.9.0

명령어가 인식되지 않거나(command not found) 버전이 20.0.0 미만이면 아래 방법으로 설치하세요.

Node.js 설치 방법

방법 1: 공식 사이트에서 설치 (가장 간단)

https://nodejs.org에서 LTS(장기 지원) 버전을 다운로드하여 설치합니다. 설치 프로그램이 Node.js와 npm을 함께 설치해 줍니다.

방법 2: nvm으로 설치 (권장 — 버전 관리 가능)

nvm(Node Version Manager)을 사용하면 여러 Node.js 버전을 설치하고 전환할 수 있어 편리합니다.

# nvm 설치
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

# 터미널 재시작 후
nvm install --lts
nvm use --lts

# nvm-windows 설치 후 (https://github.com/coreybutler/nvm-windows)
nvm install lts
nvm use lts

방법 3: 패키지 매니저로 설치

brew install node

# NodeSource 저장소 추가 (Node.js 22.x LTS)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

choco install nodejs-lts

설치 확인

설치가 완료되면 아래 명령어로 정상 설치 여부를 확인하세요.

node --version   # v20.0.0 이상 출력되면 성공
npm --version    # npm도 함께 설치됨

Gemini CLI 설치 방법

npm (권장)

npm install -g @google/gemini-cli

Homebrew (macOS / Linux)

brew install gemini-cli

MacPorts (macOS)

sudo port install gemini-cli

Anaconda (제한된 환경)

Node.js를 직접 설치할 수 없는 환경에서 유용합니다.

conda create -y -n gemini_env -c conda-forge nodejs
conda activate gemini_env
npm install -g @google/gemini-cli

설치 없이 실행 (npx)

npx @google/gemini-cli

Docker

docker run --rm -it us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.1.1
gemini --sandbox -y -p "your prompt here"

릴리스 채널

업데이트

gemini update

빠른 시작

설치부터 첫 번째 대화까지 5분 안에 시작해보세요.

단계별 가이드

npm install -g @google/gemini-cli

cd my-project
gemini

> 이 프로젝트의 구조를 설명해줘
> README.md를 요약해줘
> src/ 폴더에서 TODO 주석을 찾아줘

기본 사용 패턴

대화형 모드 (기본)

# 대화형 REPL 시작
gemini

# 초기 프롬프트와 함께 시작
gemini "이 프로젝트에 대해 설명해줘"

비대화형 모드 (일회성 질문)

# 질문 후 바로 종료
gemini -p "README.md를 요약해줘"

# 파이프와 함께 사용
cat error.log | gemini -p "이 에러 로그를 분석해줘"

대화형 + 프롬프트

# 프롬프트 실행 후 REPL 유지
gemini -i "프로젝트 구조를 분석해줘"

인증 설정

Gemini CLI에서 사용할 수 있는 인증 방법과 설정 방법을 알아봅니다.

인증 방법

1. Google 계정으로 로그인 (권장)

가장 간단한 방법입니다. gemini를 실행하고 "Sign in with Google"을 선택하면 브라우저를 통해 로그인이 진행됩니다. 인증 정보는 로컬에 캐시되어 이후 세션에서 자동으로 사용됩니다.

2. Gemini API 키

Google AI Studio에서 API 키를 발급받아 환경 변수로 설정합니다.

export GEMINI_API_KEY="your-api-key-here"

3. Vertex AI

Google Cloud 프로젝트를 통한 인증으로, 세 가지 방법을 지원합니다:

• ADC (Application Default Credentials): gcloud 명령으로 설정
• 서비스 계정 키: JSON 키 파일 사용
• Google Cloud API 키: 일부 조직에서 제한될 수 있음

Google Cloud 프로젝트 설정

다음에 해당하는 경우 Google Cloud 프로젝트 설정이 필요합니다:

• 회사, 학교, Google Workspace 계정 사용자
• Gemini Code Assist 라이선스 보유자
• 엔터프라이즈 구독자

# 환경 변수로 프로젝트 설정
export GOOGLE_CLOUD_PROJECT="my-project-id"
# 또는
export GOOGLE_CLOUD_PROJECT_ID="my-project-id"

환경 변수 영구 저장

두 가지 방법으로 환경 변수를 영구적으로 저장할 수 있습니다.

방법 1: 셸 설정 파일

export GEMINI_API_KEY="your-api-key-here"
export GOOGLE_CLOUD_PROJECT="my-project-id"

방법 2: .gemini/.env 파일

프로젝트 루트 또는 홈 디렉토리의 .gemini/.env 파일에 저장합니다.

GEMINI_API_KEY=your-api-key-here
GOOGLE_CLOUD_PROJECT=my-project-id

CLI 치트시트

자주 사용하는 명령어와 옵션을 한눈에 확인하세요.

기본 명령어

주요 옵션

REPL 내부 명령어

GEMINI.md (프로젝트 컨텍스트)

프로젝트별 지시사항과 규칙을 정의하여 AI의 응답을 맞춤화하세요.

GEMINI.md란?

GEMINI.md는 Gemini 모델에게 프로젝트에 대한 컨텍스트와 지시사항을 전달하는 파일입니다. 매번 프롬프트에 반복적인 설명을 입력하는 대신, 한 번 정의하면 모든 세션에서 자동으로 적용됩니다.

계층 구조

Gemini CLI는 다음 순서로 컨텍스트 파일을 로드합니다:

GEMINI.md 작성 예시

# 프로젝트: My TypeScript Library

## 일반 지침
- 기존 코딩 스타일을 따를 것
- 함수와 클래스에 JSDoc 주석 추가
- 한국어로 주석 작성

## 코딩 스타일
- 들여쓰기: 2칸 스페이스
- 인터페이스 이름: 'I' 접두사 사용
- 엄격한 동등 비교 (=== 및 !==)
- 세미콜론 필수

## 테스트
- Jest 프레임워크 사용
- 테스트 파일은 __tests__ 디렉토리에 배치
- 커버리지 80% 이상 유지

모듈화

@ 구문으로 다른 마크다운 파일을 임포트할 수 있습니다.

@./components/instructions.md
@../shared/style-guide.md

파일명 커스터마이징

settings.json에서 컨텍스트 파일명을 변경할 수 있습니다.

{
  "context": {
    "fileName": ["AGENTS.md", "CONTEXT.md", "GEMINI.md"]
  }
}

관련 명령어

모델 선택

작업 특성에 맞는 최적의 모델을 선택하는 방법을 알아봅니다.

사용 가능한 모델

모델 선택 방법

CLI 시작 시 지정

# Pro 모델로 시작
gemini -m pro

# Flash 모델로 시작
gemini -m flash

세션 중 변경

/model

대화형 다이얼로그가 열리며 모델을 선택할 수 있습니다. 변경은 즉시 적용됩니다.

모델 선택 가이드

에이전트 스킬

전문 지식과 워크플로우를 패키징하여 AI의 능력을 확장하세요.

에이전트 스킬이란?

에이전트 스킬은 특화된 전문 지식과 절차적 워크플로우를 패키징한 확장 기능입니다. GEMINI.md와 달리 스킬은 온디맨드로 작동하며, 모델이 작업의 관련성과 스킬의 설명을 기반으로 자율적으로 활성화를 결정합니다.

주요 장점

스킬 검색 경로

스킬은 우선순위에 따라 세 단계에서 검색됩니다:

1. 워크스페이스 스킬: .gemini/skills/ 또는 .agents/skills/
2. 사용자 스킬: ~/.gemini/skills/ 또는 ~/.agents/skills/
3. 확장 프로그램 스킬: 설치된 확장 프로그램에 번들된 스킬

스킬 관리 명령어

활성화 과정

MCP 서버

Model Context Protocol을 통해 외부 도구와 API를 Gemini CLI에 연동하세요.

MCP 서버란?

MCP(Model Context Protocol) 서버는 Gemini CLI에 외부 도구와 리소스를 제공하는 애플리케이션입니다. 외부 시스템, API, 데이터베이스, 커스텀 워크플로우에 대한 접근을 가능하게 합니다.

전송 방식

MCP 서버 추가

CLI로 추가

# Stdio 기반 서버 추가
gemini mcp add github npx -y @modelcontextprotocol/server-github

# HTTP 기반 서버 추가
gemini mcp add api-server http://localhost:3000 --transport http

# 환경 변수와 함께 추가
gemini mcp add slack node server.js --env SLACK_TOKEN=xoxb-xxx

# 특정 도구만 포함
gemini mcp add github npx -y @modelcontextprotocol/server-github \
  --include-tools list_repos,get_pr

settings.json으로 설정

Python 서버 (Stdio)

{
  "mcpServers": {
    "pythonTools": {
      "command": "python",
      "args": ["-m", "my_mcp_server"],
      "env": { "API_KEY": "$DB_TOKEN" },
      "timeout": 15000
    }
  }
}

HTTP 서버

{
  "mcpServers": {
    "httpServer": {
      "httpUrl": "http://localhost:3000/mcp",
      "headers": { "Authorization": "Bearer token" }
    }
  }
}

Docker 기반 서버

{
  "mcpServers": {
    "dockerized": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "my-mcp-server:latest"]
    }
  }
}

서버 관리

보안

• 환경 변수 필터링: *TOKEN*, *SECRET*, *PASSWORD*, *KEY* 등 민감한 변수는 자동으로 제거됩니다.
• 명시적 전달: 필요한 변수는 env 블록에서 명시적으로 설정해야 합니다.
• OAuth 지원: 동적 검색, 자동 토큰 갱신, ~/.gemini/mcp-oauth-tokens.json에 안전한 저장.

샌드박싱

AI 작업을 격리된 환경에서 안전하게 실행하세요.

샌드박싱이란?

샌드박싱은 잠재적으로 위험한 작업을 호스트 시스템으로부터 격리하는 보안 기능입니다. AI 작업과 실행 환경 사이에 보안 장벽을 제공하여 우발적인 시스템 손상을 방지합니다.

플랫폼별 격리 방식

활성화 방법

우선순위 순서로 세 가지 방법이 있습니다:

1. 명령줄 플래그

gemini -s
# 또는
gemini --sandbox

2. 환경 변수

export GEMINI_SANDBOX=true
# 특정 방식 지정
export GEMINI_SANDBOX=docker

3. settings.json

{
  "tools": {
    "sandbox": true
  }
}

도구 수준 vs 프로세스 수준

도구 수준 샌드박싱은 개별 작업(셸 명령, 파일 쓰기)만 격리하며, 비도구 작업은 로컬 환경과 통합을 유지합니다. security.toolSandboxing: false로 비활성화할 수 있습니다.

훅 (Hooks)

에이전트 루프의 특정 시점에서 커스텀 스크립트를 실행하여 동작을 제어하세요.

훅이란?

훅은 Gemini CLI의 에이전트 루프에서 특정 시점에 실행되는 스크립트입니다. 소스 코드를 수정하지 않고도 동작을 커스터마이징할 수 있습니다. 훅은 동기적으로 실행되며, 모든 훅이 완료될 때까지 Gemini CLI가 대기합니다.

훅 이벤트

설정 예시

{
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "write_file|replace",
        "hooks": [
          {
            "name": "security-check",
            "type": "command",
            "command": "$GEMINI_PROJECT_DIR/.gemini/hooks/security.sh",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

종료 코드

환경 변수

훅 실행 시 다음 환경 변수에 접근할 수 있습니다:

• GEMINI_PROJECT_DIR: 프로젝트 루트 절대 경로
• GEMINI_SESSION_ID: 현재 세션 고유 식별자
• GEMINI_CWD: 현재 작업 디렉토리

관리 명령어

/hooks panel            # 설정된 훅 목록 표시
/hooks enable-all       # 모든 훅 활성화
/hooks disable-all      # 모든 훅 비활성화
/hooks enable <이름>     # 특정 훅 활성화
/hooks disable <이름>    # 특정 훅 비활성화

파일 관리

Gemini CLI를 사용하여 파일을 읽고, 생성하고, 수정하는 방법을 알아봅니다.

파일 작업 예시

# 파일 읽기 및 분석
> src/index.ts 파일을 분석해줘

# 파일 생성
> utils/helpers.ts에 문자열 유틸리티 함수를 만들어줘

# 파일 수정
> config.json에서 포트를 3000에서 8080으로 변경해줘

# 여러 파일 작업
> src/ 폴더의 모든 .ts 파일에서 console.log를 제거해줘

# 파일 검색
> TODO 주석이 포함된 파일을 모두 찾아줘

승인 모드

Gemini CLI는 파일을 수정하기 전에 사용자의 승인을 요청합니다.

# 승인 모드 지정
gemini --approval-mode auto_edit

# 자동 승인 모드 (약칭)
gemini -y

셸 명령어

Gemini CLI 내에서 직접 셸 명령을 실행하고 결과를 활용하세요.

셸 명령 실행

Gemini CLI는 AI가 필요할 때 자동으로 셸 명령을 실행합니다. 또한 사용자가 직접 실행을 요청할 수도 있습니다.

# AI에게 명령 실행 요청
> git log --oneline -10 실행해서 최근 커밋 보여줘
> npm test 실행하고 실패한 테스트 수정해줘
> docker ps로 실행 중인 컨테이너 확인해줘

# 파이프로 결과 전달
cat build.log | gemini -p "빌드 에러를 분석하고 해결 방법을 알려줘"

비대화형 자동화

# CI/CD 파이프라인에서 사용
gemini -p "src/ 폴더의 코드를 린트하고 문제를 수정해줘" -y

# 스크립트에서 사용
result=$(gemini -p "package.json의 버전을 파싱해줘" -o json)
echo $result

세션 관리

대화 세션을 저장하고 이어서 작업하는 방법을 알아봅니다.

세션 이어하기

# 가장 최근 세션 재개
gemini -r "latest"

# 특정 세션 ID로 재개
gemini -r "abc123"

# 세션 재개 + 추가 프롬프트
gemini -r "abc123" "이 PR을 마무리해줘"

세션 목록 및 관리

# 현재 프로젝트의 세션 목록
gemini --list-sessions

# 특정 세션 삭제
gemini --delete-session 0

확장 프로그램

Gemini CLI의 기능을 확장하는 확장 프로그램을 설치하고 관리하세요.

확장 프로그램 관리

개발용 명령어

# 새 확장 프로그램 템플릿 생성
gemini extensions new ./my-extension

# 로컬 확장 프로그램 링크 (개발용)
gemini extensions link /path/to/extension

# 확장 프로그램 구조 검증
gemini extensions validate ./my-extension

작업 자동화

Gemini CLI를 스크립트와 CI/CD 파이프라인에 통합하여 작업을 자동화하세요.

Headless 모드

Gemini CLI를 프로그래밍 방식으로 사용할 수 있습니다. 대화형 인터페이스 없이 프롬프트를 처리합니다.

# 비대화형 실행
gemini -p "모든 테스트 파일에 JSDoc 주석을 추가해줘" -y

# JSON 출력
gemini -p "package.json의 의존성 목록" -o json

# 파이프라인에서 사용
git diff HEAD~1 | gemini -p "이 변경사항을 리뷰해줘" -o text

CI/CD 활용 예시

name: AI Code Review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g @google/gemini-cli
      - run: |
          git diff origin/main...HEAD | \
          gemini -p "PR 변경사항을 리뷰하고 문제를 보고해줘" -y
        env:
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}

스크립트 통합

#!/bin/bash
# 자동 코드 리뷰 스크립트

# 변경된 파일 목록 가져오기
changed_files=$(git diff --name-only HEAD~1)

# 각 파일에 대해 리뷰 수행
for file in $changed_files; do
  echo "리뷰 중: $file"
  gemini -p "다음 파일의 코드를 리뷰해줘: $file" -y -o text
done

설정 파일

settings.json으로 Gemini CLI의 동작을 세밀하게 제어하세요.

설정 파일 위치

설정은 다음 순서의 우선순위로 병합됩니다:

1. 프로젝트: .gemini/settings.json
2. 사용자: ~/.gemini/settings.json
3. 시스템: /etc/gemini-cli/settings.json

설정 예시

{
  "theme": "dark",
  "model": "auto",
  "context": {
    "fileName": ["GEMINI.md"]
  },
  "tools": {
    "sandbox": false
  },
  "security": {
    "toolSandboxing": true
  },
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "$GITHUB_TOKEN"
      }
    }
  },
  "hooks": {}
}

테마

Gemini CLI의 터미널 UI를 취향에 맞게 커스터마이징하세요.

테마 설정

settings.json에서 테마를 설정할 수 있습니다.

{
  "theme": "dark"
}

사용 가능한 테마 옵션: dark, light, auto (시스템 설정 따름)

커스텀 명령어

자주 사용하는 프롬프트를 슬래시 명령어로 등록하세요.

커스텀 명령어란?

자주 사용하는 프롬프트 패턴을 슬래시 명령어로 만들어 빠르게 재사용할 수 있습니다.

관리 명령어

/commands reload    # 커스텀 명령어 새로고침

무시 파일 (.geminiignore)

AI가 접근하지 않아야 할 파일과 디렉토리를 지정하세요.

.geminiignore란?

.gitignore와 유사한 형식으로, Gemini CLI가 무시할 파일과 디렉토리 패턴을 지정합니다. 민감한 파일, 대용량 바이너리, 불필요한 종속성 폴더 등을 제외할 수 있습니다.

예시

# 종속성
node_modules/
vendor/

# 빌드 산출물
dist/
build/
*.min.js

# 민감한 파일
.env
.env.local
credentials.json
*.pem

# 대용량 파일
*.zip
*.tar.gz
data/

요금 및 할당량

Gemini CLI의 무료 사용 한도와 유료 플랜을 확인하세요.

무료 사용

개인 유료 플랜

조직/기업 플랜

종량제

• Vertex AI (일반 모드): 모델과 토큰 사용량에 따라 과금. 동적 공유 쿼터 또는 사전 구매 처리량 옵션.
• Gemini API 키 (유료): 가격 등급별 가변 쿼터. 토큰/호출 단위 과금.

사용량 확인

/stats model

실시간 토큰 사용량과 적용된 한도를 확인할 수 있습니다.

키보드 단축키

Gemini CLI를 더 빠르게 사용하기 위한 단축키 모음입니다.

기본 단축키

문제 해결

자주 발생하는 문제와 해결 방법을 안내합니다.

설치 관련

Node.js 버전 오류

Node.js 20.0.0 이상이 필요합니다.

# 현재 버전 확인
node --version

# nvm으로 업그레이드
nvm install 20
nvm use 20

권한 오류 (npm)

# npm 글로벌 디렉토리 변경
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

# 재설치
npm install -g @google/gemini-cli

인증 관련

로그인이 안 될 때

• 인터넷 연결을 확인하세요.
• 방화벽이나 프록시 설정을 확인하세요.
• Gemini Code Assist 지원 지역인지 확인하세요.

API 키 오류

• 환경 변수가 올바르게 설정되었는지 확인: echo $GEMINI_API_KEY
• API 키가 유효한지 Google AI Studio에서 확인하세요.

MCP 서버 관련

서버가 연결되지 않을 때

• 명령어와 인수가 올바른지 확인하세요.
• 서버를 독립적으로 테스트하세요.
• 실행 권한을 확인하세요.

도구가 발견되지 않을 때

• MCP 프로토콜이 올바르게 구현되었는지 확인하세요.
• 서버 로그를 검토하세요.

디버그 모드

# 디버그 모드로 실행
gemini -d

# 또는 환경 변수로 설정
DEBUG=1 gemini -s -p "test command"

FAQ

자주 묻는 질문과 답변을 모았습니다.

일반

Q. Gemini CLI는 무료인가요?

네, Google 계정으로 로그인하면 하루 1,000건의 요청을 무료로 사용할 수 있습니다. Gemini API 키(무료)의 경우 하루 250건, Flash 모델만 사용 가능합니다.

Q. 어떤 운영체제를 지원하나요?

macOS 15+, Windows 11 24H2+, Ubuntu 20.04+를 공식 지원합니다.

Q. 오프라인에서 사용할 수 있나요?

아니요, Gemini CLI는 Google의 AI 모델에 접근하기 위해 인터넷 연결이 필요합니다.

모델

Q. Gemini 3은 무엇인가요?

Gemini 3은 Google의 최신 AI 모델 시리즈입니다. Gemini CLI에서 프리뷰로 사용할 수 있으며, auto 모드에서 자동으로 선택될 수 있습니다.

Q. 서브 에이전트의 모델을 변경할 수 있나요?

현재 /model 명령어와 --model 플래그는 서브 에이전트에 영향을 주지 않습니다.

보안

Q. 내 코드가 학습에 사용되나요?

인증 방법과 서비스 약관에 따라 다릅니다. 자세한 내용은 공식 문서의 약관 및 개인정보 보호 페이지를 확인하세요.

Q. 샌드박스 모드는 어떻게 작동하나요?

플랫폼별 격리 기술을 사용합니다. macOS는 Seatbelt, Linux는 Docker/gVisor, Windows는 icacls를 활용합니다. gemini -s로 활성화할 수 있습니다.

Gemini 3 모델 NEW

Google의 최신 AI 모델 라인업인 Gemini 3을 Gemini CLI에서 사용하는 방법을 알아봅니다.

Gemini 3란?

Gemini 3은 Google의 차세대 AI 모델 시리즈입니다. 현재 다음 모델이 제공됩니다:

• Gemini 3 Pro: 복잡한 작업을 위한 최고 성능 모델
• Gemini 3 Flash: 단순 작업을 위한 빠른 모델
• Gemini 3.1 Pro Preview: 차세대 모델의 롤링 프리뷰

활성화 방법

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

Gemini Code Assist 사용자

조직 관리자의 추가 설정이 필요합니다:

1. Google Cloud 설정에서 릴리스 채널을 "Preview"로 변경
2. 사용자가 /settings에서 "Preview Features" 활성화

모델 라우팅

일일 사용량 관리

Gemini 3 Pro의 일일 사용량 한도에 도달하면 자동으로 Gemini 2.5 Pro로 전환됩니다. 높은 수요 기간에는 즉시 실패 대신 지수 백오프 재시도 로직이 적용됩니다.

모델 라우팅

모델 실패 시 자동 폴백과 로컬 라우팅을 통한 안정적인 운영 방법을 알아봅니다.

자동 폴백

Gemini CLI는 기본적으로 모델 라우팅이 활성화되어 있습니다. ModelAvailabilityService가 3단계로 관리합니다:

모델 선택 우선순위

1. --model 명령줄 플래그
2. GEMINI_MODEL 환경 변수
3. model.name (settings.json)
4. 로컬 Gemma 모델 (활성화된 경우)
5. 기본값 (auto)

로컬 모델 라우팅 (실험적)

로컬에서 실행되는 Gemma 모델로 라우팅 결정을 내릴 수 있습니다. 호스팅된 모델에 결정을 보내는 대신 로컬 모델이 판단하여 비용을 절감합니다. Gemini API 호환 HTTP 엔드포인트로 서빙되어야 합니다.

모델 스티어링 실험적

작업 실행 중 실시간으로 AI에게 힌트를 전달하여 방향을 조정하세요.

모델 스티어링이란?

모델 스티어링은 작업 실행 중 에이전트를 재시작하지 않고 실시간으로 피드백과 방향 수정을 제공하는 실험적 기능입니다. 특히 복잡한 플랜 모드 워크플로우에서 유용합니다.

활성화

{
  "experimental": {
    "modelSteering": true
  }
}

작동 방식

1. 확인: 빠른 모델이 힌트 수신을 1문장으로 확인
2. 컨텍스트 주입: 내부 지시와 함께 힌트가 전달
3. 실시간 반영: 다음 턴에서 즉시 반영

활용 예시

# 파일 경로 수정
"유틸리티는 src/common/utils에 있어"

# 단계 건너뛰기
"단위 테스트는 건너뛰고 구현에 집중해"

# 도구 방향 지정
"Logger 클래스 대신 winston 라이브러리 사용해"

# 모호성 해소
"UserService는 auth 모듈에 있는 걸 말하는 거야"

서브 에이전트

전문화된 AI 어시스턴트에게 특정 작업을 위임하세요.

서브 에이전트란?

서브 에이전트는 메인 Gemini CLI 세션 내의 전문 AI 어시스턴트입니다. 각각 독자적인 시스템 프롬프트, 페르소나, 특화된 도구 세트를 가지며 별도의 컨텍스트 윈도우에서 작동합니다.

내장 서브 에이전트

사용 방법

자동 위임

메인 에이전트가 작업을 분석하여 적합한 서브 에이전트에 자동으로 위임합니다.

명시적 호출

# @ 구문으로 특정 에이전트 호출
@codebase_investigator 서비스 간의 의존성 관계를 분석해줘
@cli_help 커스텀 명령어 만드는 방법 알려줘

커스텀 서브 에이전트 생성

YAML 프론트매터가 포함된 마크다운 파일로 정의합니다.

파일 위치

• 프로젝트: .gemini/agents/*.md
• 사용자: ~/.gemini/agents/*.md

설정 필드

관리

# REPL 내부
/agents                    # 에이전트 관리
/agents reload             # 레지스트리 새로고침

# 비활성화 (settings.json)
{ "experimental": { "enableAgents": false } }

원격 에이전트

Agent-to-Agent(A2A) 프로토콜로 외부 에이전트에 작업을 위임하세요.

원격 에이전트란?

원격 서브 에이전트는 A2A(Agent-to-Agent) 프로토콜을 사용하여 외부 에이전트 서비스와 통신합니다. 로컬 작업 범위를 넘어 원격 서비스에 작업을 위임할 수 있습니다.

설정

프로젝트 또는 사용자 수준의 마크다운 파일로 정의합니다:

• 프로젝트: .gemini/agents/*.md (팀 공유)
• 사용자: ~/.gemini/agents/*.md (개인용)

각 정의에는 고유 이름 슬러그와 agent_card_url 또는 인라인 agent_card_json이 필요합니다.

인증 방법

관리 명령어

/agents list              # 사용 가능 에이전트 목록
/agents reload            # 파일 변경 후 레지스트리 새로고침
/agents enable <이름>      # 특정 에이전트 활성화
/agents disable <이름>     # 특정 에이전트 비활성화

플랜 모드

읽기 전용 환경에서 아키텍처를 설계하고 실행 계획을 수립하세요.

플랜 모드란?

플랜 모드는 구현 전 아키텍처 계획을 위한 읽기 전용 환경입니다. 프로젝트를 탐색하고, 문제를 이해하고, 트레이드오프를 평가한 후 코드를 수정하기 전에 실행 전략을 정렬할 수 있습니다.

진입 방법

워크플로우

도구 제한

플랜 모드에서는 안전을 위해 도구가 엄격히 제한됩니다:

• 허용: read_file, list_directory, glob, grep_search, google_web_search, web_fetch, ask_user
• 제한적 쓰기: 지정된 계획 디렉토리의 .md 파일만 write_file/replace 가능
• 금지: 프로젝트 코드에 대한 모든 쓰기 작업

계획 디렉토리 커스터마이징

{
  "general": {
    "plan": {
      "directory": ".gemini/plans"
    }
  }
}

모델 라우팅 연동

auto 모델 사용 시, 계획 단계에서는 Pro 모델로 강력한 추론을 수행하고, 구현 단계에서는 Flash 모델로 전환하여 속도를 높입니다.

종료 방법

• 완성된 계획을 승인 (자동 종료 후 구현 시작)
• Shift+Tab으로 모드 전환
• "플랜 모드 종료해줘"라고 자연어로 요청

체크포인팅

AI가 파일을 수정하기 전 자동으로 프로젝트 상태를 스냅샷으로 저장합니다.

체크포인팅이란?

체크포인팅은 AI 도구가 파일을 수정하기 전에 프로젝트 상태의 스냅샷을 자동 저장하는 안전 기능입니다. 파일 수정 도구를 승인할 때 세 가지 구성 요소가 생성됩니다:

• Git 스냅샷: ~/.gemini/history/<project_hash>의 쉐도우 저장소에 커밋 (사용자의 Git 저장소에 영향 없음)
• 대화 이력: 해당 시점까지의 전체 채팅 내용 보존
• 도구 호출 데이터: 체크포인트를 트리거한 도구 실행 정보 저장

활성화

{
  "general": {
    "checkpointing": {
      "enabled": true
    }
  }
}

/restore 명령어

되감기 (Rewind)

이전 대화 상태로 돌아가고, AI가 수정한 파일을 선택적으로 복원하세요.

사용 방법

• 명령어: /rewind 입력 후 Enter
• 단축키: Esc 두 번 누르기

복원 옵션

되돌릴 대화 지점을 선택한 후 다음 옵션이 표시됩니다:

토큰 캐싱

API 비용을 자동으로 최적화하는 토큰 캐싱 기능을 알아봅니다.

작동 방식

Gemini CLI는 API 키 인증 사용 시 자동으로 토큰 캐싱을 수행합니다. 이전에 제출한 시스템 지침과 컨텍스트를 후속 요청에서 재사용하여 처리할 토큰 수를 줄입니다.

지원 대상

사용량 모니터링

/stats

일반 토큰 사용량과 캐시 절약량을 확인할 수 있습니다.

알림 실험적

백그라운드 작업 완료나 사용자 입력 필요 시 데스크톱 알림을 받으세요.

활성화

{
  "general": {
    "enableNotifications": true
  }
}

또는 /settings → General → Enable Notifications → On

알림 유형

지원 터미널

OSC 9 이스케이프 시퀀스를 사용합니다. iTerm2, WezTerm, Ghostty, Kitty를 지원합니다. 미지원 터미널에서는 터미널 벨(BEL)로 대체되어 작업 표시줄 깜박임이나 시스템 알림음이 울립니다.

메모리 관리

GEMINI.md와 메모리 시스템을 활용한 지속적 컨텍스트 관리 방법을 알아봅니다.

두 가지 메커니즘

GEMINI.md 계층 구조

1. 글로벌: ~/.gemini/GEMINI.md (모든 프로젝트)
2. 프로젝트 루트: ./GEMINI.md (현재 저장소)
3. 하위 디렉토리: ./src/GEMINI.md (폴더별 규칙)

Memory 저장

자연어로 기억할 내용을 말하면 에이전트가 save_memory 도구로 자동 저장합니다.

> 나는 'const'를 'let'보다 항상 선호해. 기억해줘.
> 이 프로젝트는 탭 대신 2칸 스페이스를 사용해. 기억해.

관리 명령어

작업 계획 (Todo)

구조화된 할 일 목록으로 복잡한 프로젝트를 체계적으로 관리하세요.

왜 필요한가?

표준 LLM은 10턴 이상의 코드 생성 후 원래 목표를 "잊을" 수 있습니다. 작업 계획은 세 가지 장점을 제공합니다:

사용 방법

# 계획 수립 요청
> 이 프로젝트를 JavaScript에서 TypeScript로 마이그레이션하려고 해. 먼저 계획을 세워줘.

# 진행 상황 확인
Ctrl+T    # 전체 할 일 목록 표시 (대기, 진행 중, 완료)

# 계획 수정 요청
> @types/node 설치 단계가 빠져있어. 추가해줘.
> 3번 단계를 취소하고 4번부터 진행해줘.

웹 도구

실시간 웹 검색과 URL 내용 가져오기로 최신 정보에 접근하세요.

주요 도구

Google 웹 검색 (google_web_search)

인터넷에서 관련 페이지를 검색합니다. 모델의 학습 데이터 이후에 출시된 문서를 찾거나, 정보를 검증하여 할루시네이션을 방지하는 데 유용합니다.

웹 가져오기 (web_fetch)

특정 URL에서 원본 콘텐츠를 가져옵니다. 광고와 탐색 요소를 제거하여 핵심 내용만 추출합니다.

활용 예시

# 기술 조사
> Bun 1.0 릴리스 노트를 검색해서 주요 변경사항 요약해줘

# 상세 정보 가져오기
> https://docs.example.com/api 를 읽고 내 코드에 적용하는 방법 설명해줘

# 소스 비교
> React와 Vue의 최신 상태 관리 방법을 비교해줘

# 에러 트러블슈팅
> "TypeError: Cannot read property of undefined" 에러가 나와. 해결 방법 검색해줘

헤드리스 모드

대화형 인터페이스 없이 프로그래밍 방식으로 Gemini CLI를 사용하세요.

활성화

두 가지 경우에 자동 활성화됩니다:

• 비TTY (비터미널) 환경에서 실행
• -p 또는 --prompt 플래그와 함께 실행

출력 형식

JSON (-o json)

단일 JSON 객체를 반환합니다:

• response: 모델의 최종 답변 (문자열)
• stats: 토큰 사용량 및 API 지연 메트릭 (객체)
• error: 요청 실패 시 에러 상세 (선택)

스트리밍 JSON (-o stream-json)

줄 구분 JSON(JSONL) 이벤트를 생성합니다:

종료 코드

Git Worktrees 실험적

별도의 작업 디렉토리에서 여러 작업을 동시에 수행하세요.

Git Worktrees란?

Git worktree는 같은 저장소 이력을 공유하면서 각각 고유한 파일과 브랜치를 가진 별도의 작업 디렉토리를 생성합니다. 동시 작업 세션 간 코드 변경 충돌을 방지합니다.

활성화

{
  "experimental": {
    "worktrees": true
  }
}

사용법

# 이름 지정하여 생성
gemini --worktree feature-search

# 자동 이름으로 생성
gemini --worktree

이름은 디렉토리명 (.gemini/worktrees/에 저장)과 연관된 브랜치명이 됩니다.

작업 재개

cd .gemini/worktrees/feature-search
gemini --resume <session_id>

확장 프로그램 개발

커스텀 도구, 명령어, 컨텍스트를 제공하는 확장 프로그램을 직접 만드세요.

확장 기능 유형

프로젝트 구조

my-extension/
  gemini-extension.json    # 매니페스트 (필수)
  example.js               # MCP 서버 구현
  package.json             # Node.js 의존성
  GEMINI.md                # 컨텍스트 파일 (선택)
  commands/                # 커스텀 명령어 (선택)
  skills/                  # 에이전트 스킬 (선택)

매니페스트 예시

{
  "name": "mcp-server-example",
  "version": "1.0.0",
  "settings": [{
    "name": "API Key",
    "envVar": "MY_SERVICE_API_KEY",
    "sensitive": true
  }],
  "mcpServers": {
    "nodeServer": {
      "command": "node",
      "args": ["${extensionPath}${/}example.js"],
      "cwd": "${extensionPath}"
    }
  }
}

MCP 서버 구현

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';

const server = new McpServer({
  name: 'my-server',
  version: '1.0.0',
});

server.registerTool(
  'fetch_posts',
  {
    description: 'Fetches posts from API.',
    inputSchema: z.object({}).shape,
  },
  async () => {
    const data = await fetch('https://api.example.com/posts');
    const json = await data.json();
    return { content: [{ type: 'text', text: JSON.stringify(json) }] };
  },
);

const transport = new StdioServerTransport();
await server.connect(transport);

개발 워크플로우

# 1. 템플릿 생성
gemini extensions new my-extension mcp-server

# 2. 의존성 설치
cd my-extension && npm install

# 3. 개발용 링크
gemini extensions link .

# 4. 테스트 (CLI 재시작 후 도구/명령어 확인)
gemini

# 5. 구조 검증
gemini extensions validate .

IDE 연동

VS Code, JetBrains 등의 IDE와 Gemini CLI를 연동하여 개발 경험을 향상시키세요.

지원 IDE

VS Code 호환 에디터

• Visual Studio Code
• Antigravity
• 기타 VS Code 포크

ACP 호환 IDE

• JetBrains IDE (IntelliJ IDEA, PyCharm, GoLand)
• Zed
• Agent Client Protocol(ACP) 에이전트 레지스트리를 지원하는 모든 IDE

VS Code Companion 확장

"Gemini CLI Companion" 확장은 직접 IDE 접근과 실시간 워크스페이스 인식을 제공합니다.

• 최근 접근 파일 10개, 커서 위치, 선택 텍스트 (최대 16KB)의 워크스페이스 컨텍스트
• 코드 변경 검토 및 적용을 위한 네이티브 diff 뷰어
• Command Palette를 통한 CLI 기능 접근

설치

• 지원 에디터에서 CLI 실행 시 자동 설치
• CLI 명령: /ide install
• VS Code Marketplace 또는 Open VSX Registry에서 수동 설치

연결 관리

/ide enable       # IDE 연동 활성화
/ide disable      # IDE 연동 비활성화
/ide status       # 연결 상태 및 워크스페이스 파일 표시

Diff 작업

변경사항 수락: 체크 아이콘, 파일 저장, Command Palette, CLI 확인 중 하나로 수락합니다. 거부: 'x' 아이콘 클릭 또는 탭 닫기.

시스템 프롬프트

Gemini CLI의 핵심 동작 지침을 완전히 커스터마이징하세요.

시스템 프롬프트란?

시스템 프롬프트는 Gemini CLI의 동작을 안내하는 핵심 지시사항입니다. 커스텀 마크다운 파일로 완전히 대체할 수 있습니다.

GEMINI_SYSTEM_MD 환경 변수

변수 치환

커스텀 프롬프트에서 내장 콘텐츠를 동적으로 주입할 수 있습니다:

• ${AgentSkills}: 에이전트 스킬 목록
• ${SubAgents}: 서브 에이전트 목록
• ${AvailableTools}: 사용 가능 도구 목록

기본 프롬프트 내보내기

GEMINI_WRITE_SYSTEM_MD=1 gemini

UI 표시

커스텀 시스템 프롬프트가 활성화되면 CLI에 |⌐■_■| 표시가 나타납니다.

생성 설정

Temperature, Top-P 등 모델 생성 매개변수를 세밀하게 조정하세요.

주요 매개변수

설정 방법

GenerateContentConfig 객체를 통해 @google/genai SDK에 전달됩니다. 두 가지 설정 원시값을 지원합니다:

• 별칭 (Aliases): 이름 있는 재사용 가능 프리셋. 다른 별칭을 상속 가능
• 오버라이드 (Overrides): 런타임 컨텍스트(모델명, 에이전트 범위)에 따라 조건부 적용

신뢰 폴더

프로젝트별 보안 수준을 제어하여 악성 코드 실행을 방지하세요.

신뢰 폴더란?

Gemini CLI의 전체 기능에 접근할 수 있는 프로젝트를 제어하는 보안 기능입니다. 프로젝트별 설정을 로드하기 전에 사용자의 승인을 요구합니다. 기본적으로 비활성화되어 있습니다.

활성화

{
  "security": {
    "folderTrust": {
      "enabled": true
    }
  }
}

신뢰 대화 옵션

폴더에서 처음 CLI를 실행하면 세 가지 옵션이 제공됩니다:

1. 현재 폴더만 신뢰
2. 상위 디렉토리 신뢰 (모든 하위 디렉토리 자동 신뢰)
3. 비신뢰로 표시 (제한된 "안전 모드"로 작동)

비신뢰 폴더 제한사항

• 워크스페이스 설정 파일 무시
• .env 파일 환경 변수 미로드
• 확장 프로그램 관리 차단
• 도구 자동 수락 비활성화
• 자동 메모리 로드 중지
• MCP 서버 연결 차단
• 커스텀 명령어 미로드

관리

• /permissions 명령어로 현재 폴더의 신뢰 수준 변경
• ~/.gemini/trustedFolders.json에서 모든 신뢰 규칙 확인

엔터프라이즈 설정

조직 전체에 Gemini CLI 정책과 보안 제어를 적용하세요.

시스템 설정 파일

설정 병합 우선순위

시스템 기본값 → 사용자 설정 → 워크스페이스 설정 → 시스템 오버라이드 (최종 권한)

주요 보안 제어

도구 접근 제한

허용 목록 방식(tools.core)이 가장 안전합니다. 위험한 명령을 차단하는 대신 허용할 도구를 명시적으로 지정합니다.

YOLO 모드 비활성화

{
  "security": {
    "disableYoloMode": true
  }
}

MCP 서버 허용 목록

{
  "mcp": { "allowed": ["corp-data-api"] },
  "mcpServers": {
    "corp-data-api": {
      "command": "/usr/local/bin/start-corp-api.sh"
    }
  }
}

인증 강제

{
  "enforcedAuthType": "oauth-personal"
}

사용자 격리

공유 환경에서 GEMINI_CLI_HOME 환경 변수로 각 사용자/작업을 고유한 상태 디렉토리로 분리합니다.

감사 (Telemetry)

"logPrompts": false로 민감한 프롬프트 내용 없이 도구 사용만 감사할 수 있습니다. otlpEndpoint로 내부 OTLP 수집기에 전송합니다.

텔레메트리

Gemini CLI의 관찰 가능성 데이터 수집과 설정 방법을 알아봅니다.

수집 데이터

OpenTelemetry를 통해 세 가지 유형의 데이터를 수집합니다:

로그

세션 설정, 프롬프트 제출, 도구 실행 (함수명, 인수, 소요시간), API 요청/응답 (토큰 수), 파일 작업, 모델 라우팅 결정, 확장 프로그램 생명주기 이벤트.

메트릭

도구 호출 횟수/지연, API 요청 횟수/지연, 유형별 토큰 사용량 (입력, 출력, 사고, 캐시, 도구), 파일 작업 및 변경 라인 수.

추적 (Traces)

작업명, 모델, 도구 상세, 토큰 수 등 속성이 포함된 스팬 기반 상세 가시성.

설정

도구 레퍼런스

Gemini CLI에서 사용 가능한 모든 내장 도구의 카테고리별 목록입니다.

실행

파일 시스템

상호작용

메모리 & 계획

웹

정책 엔진

도구 실행을 세밀하게 제어하는 TOML 기반 규칙 시스템입니다.

정책 엔진이란?

도구 호출을 허용(allow), 거부(deny), 또는 사용자 확인 요청(ask_user)으로 결정하는 규칙을 정의합니다.

규칙 조건

• 도구 이름: 정확한 이름 또는 와일드카드 (*, mcp_server_*)
• 인수 패턴: JSON 형식 인수에 대한 정규식
• 실행 환경: 대화형 vs 비대화형
• 승인 모드: default, autoEdit, plan, yolo

우선순위 계층

공식: 최종 우선순위 = 계층 기본값 + (toml_priority / 1000)

TOML 규칙 예시

# 위험한 명령 차단
[[rule]]
toolName = "run_shell_command"
commandPrefix = "rm -rf"
decision = "deny"
priority = 100

# MCP 도구 허용
[[rule]]
mcpName = "my-jira-server"
toolName = "search"
decision = "allow"
priority = 200

# 파일 수정 확인 요청
[[rule]]
toolName = ["write_file", "replace"]
decision = "ask_user"
priority = 10

정책 파일 위치

• 사용자: ~/.gemini/policies/*.toml
• 워크스페이스: $WORKSPACE_ROOT/.gemini/policies/*.toml
• 시스템 관리자: OS별 시스템 경로

메모리 임포트 프로세서

GEMINI.md 파일을 모듈화하여 재사용 가능한 컴포넌트로 관리하세요.

임포트 구문

@ 뒤에 파일 경로를 지정하여 다른 파일의 내용을 가져옵니다:

@./file.md                      # 상대 경로
@../shared/style-guide.md       # 상위 디렉토리
@./components/instructions.md   # 하위 디렉토리
@/absolute/path/to/file.md      # 절대 경로

안전 메커니즘

• 순환 임포트 감지: A가 B를 임포트하고 B가 A를 임포트하는 것을 자동 방지
• 파일 접근 보안: validateImportPath 함수로 지정된 디렉토리로만 임포트 제한
• 최대 깊이 제한: 기본 5단계로 무한 재귀 방지

특수 처리

• 오류 처리: 누락된 파일이나 권한 문제 시 에러 주석을 삽입 (무음 실패 방지)
• 코드 블록 인식: marked 라이브러리로 코드 블록 내의 @ 구문은 실제 임포트로 처리하지 않음
• 계층 시각화: 임포트 트리 구조로 파일 관계를 명시적으로 표시

ACP 모드 실험적

Agent Client Protocol을 통해 IDE와 개발 도구에서 Gemini CLI를 프로그래밍 방식으로 제어하세요.

ACP 모드란?

ACP(Agent Client Protocol)는 AI 코딩 에이전트와 코드 에디터/IDE 간 통신을 표준화하는 개방형 프로토콜입니다. JSON-RPC 프로토콜을 stdio로 통신합니다.

시작

gemini --acp

지원 메서드

MCP 연동

IDE 클라이언트가 MCP 서버를 구현하면 Gemini 모델이 해당 도구를 사용할 수 있습니다:

1. 클라이언트가 도구를 노출하는 MCP 서버 구현
2. ACP 초기화 시 MCP 서버 연결 정보 제공
3. Gemini CLI가 연결하여 사용 가능 도구 검색
4. 모델이 작업 실행을 위해 도구 호출

디버깅

gemini --acp --debug

제거 (Uninstall)

Gemini CLI를 시스템에서 완전히 제거하는 방법입니다.

설치 방법별 제거

npm 글로벌 설치

npm uninstall -g @google/gemini-cli

npx (임시 캐시)

npx는 임시 캐시에서 실행되므로 영구 설치가 아닙니다. 캐시를 정리하려면:

rm -rf "$(npm config get cache)/_npx"

Remove-Item -Path (Join-Path $env:LocalAppData "npm-cache\_npx") -Recurse -Force

Homebrew

brew uninstall gemini-cli

MacPorts

sudo port uninstall gemini-cli