Romin Irani의 Gemini CLI 튜토리얼 시리즈 요약

이 문서는 Romin Irani가 Medium에 연재한 Gemini CLI 튜토리얼 시리즈를 번역하고 요약한 내용입니다. 개발자가 터미널에서 Gemini의 강력한 기능을 활용하는 방법을 단계별로 배울 수 있도록 돕기 위해 작성되었습니다.

출처:

Part 1: Gemini CLI Tutorial Series (opens in a new tab)

Part 2: Gemini CLI Tutorial Series — Part 2 : Gemini CLI Command line parameters (opens in a new tab)

Part 3: Gemini CLI Tutorial Series — Part 3 : Configuration settings via settings.json and .env files (opens in a new tab)

Part 1: 설치 및 시작하기

첫 번째 파트에서는 Gemini CLI를 설치하고 기본적인 사용법을 익힙니다.

Gemini CLI란?

Gemini CLI는 터미널에 Gemini의 강력한 기능을 직접 통합한 오픈소스 AI 에이전트입니다. 코딩 관련 작업뿐만 아니라 다양한 작업을 수행할 수 있으며, 여러 도구와 통합되어 있습니다. 또한 MCP 서버를 지원하며, 넉넉한 무료 등급을 제공합니다.

설치 및 설정

Node.js 설치: 먼저 머신에 Node.js 버전 18 이상이 설치되어 있어야 합니다.
Gemini CLI 설치: 다음 명령어를 사용하여 Gemini CLI를 설치합니다.
```
npm install -g @google/gemini-cli
```
버전 확인: 설치 후 다음 명령어로 버전을 확인할 수 있습니다.
```
gemini -v
```
최초 실행 및 인증:
- gemini 명령어로 CLI를 시작합니다.
- 원하는 테마를 선택합니다.
- 인증 방법을 선택합니다.
  - Google 로그인: 무료 등급(분당 60개 요청, 하루 1000개 모델 요청)을 이용할 수 있습니다.
  - Gemini API 키 또는 Vertex AI: 더 높은 할당량이 필요한 경우 사용합니다.

터미널 인터페이스 및 기본 명령어

상태 표시줄: 현재 폴더, 사용 중인 모델 (gemini-2.5-pro), 남은 컨텍스트, 샌드박스 실행 여부 등을 보여줍니다.
/help: 사용 가능한 명령어, 단축키, @를 사용해 파일/폴더를 컨텍스트에 추가하는 방법을 보여줍니다.
/session: 현재 세션의 총 토큰, 지속 시간 등의 통계를 보여줍니다.
/tools: 사용 가능한 도구 목록을 보여줍니다. (GoogleSearch, WriteFile 등)
!: 셸 모드로 전환하여 pwd 같은 시스템 셸 명령어를 직접 실행할 수 있습니다. ESC 키로 빠져나옵니다.

첫 코딩 작업 예시: Python Flask 앱 만들기

이 튜토리얼에서는 크리켓 실시간 점수 RSS 피드를 보여주는 Python Flask 웹 애플리케이션을 만드는 과정을 예시로 보여줍니다.

프롬프트 입력: "라이브 크리켓 점수를 보여주는 Python Flask 앱을 만들어줘. RSS 피드 주소는 ... 이야." 와 같이 자연어로 요청합니다.
계획 수립 및 확인: Gemini CLI는 cricket-scores-app이라는 새 디렉토리를 만들고, 기본 Flask 애플리케이션 구조를 설정하는 등 작업 계획을 제시합니다.
도구 사용 승인: mkdir로 디렉토리를 만들거나 WriteFile로 코드를 작성하는 등 파일 시스템에 접근하는 작업을 수행하기 전에 사용자에게 실행 허가를 요청합니다. 한 번만 허용하거나, 항상 허용하도록 선택할 수 있습니다.
코드 생성 및 패키지 관리: app.py, templates/index.html 같은 파일을 생성하고, requirements.txt에 필요한 Python 패키지(Flask, feedparser)를 식별합니다.
실행 및 디버깅: 가상 환경 설정, pip을 통한 패키지 설치, Flask 애플리케이션 실행까지의 과정을 안내합니다. 기본 포트(5000)가 사용 중일 경우, 다른 포트(8080)를 사용하도록 제안하고 문제를 해결하는 상호작용도 가능합니다.

Part 2: Gemini CLI 명령줄 매개변수

두 번째 파트에서는 Gemini CLI를 시작할 때 사용할 수 있는 다양한 명령줄 옵션을 자세히 다룹니다. 이를 통해 체크포인팅, 디버깅, 컨텍스트 설정, 원격 측정 등 고급 기능을 활용하는 방법을 배울 수 있습니다.

Gemini CLI 업그레이드

Gemini CLI는 매우 빠르게 업데이트되므로, 항상 최신 버전을 사용하는 것이 좋습니다. 다음 명령어로 업그레이드할 수 있습니다.

npm upgrade -g @google/gemini-cli

주요 명령줄 옵션

gemini --help 명령어를 통해 사용 가능한 모든 옵션을 확인할 수 있습니다. 주요 옵션은 다음과 같습니다.

-v, --version: 현재 설치된 Gemini CLI의 버전을 표시합니다.
-m, --model <모델명>: 사용할 Gemini 모델을 지정합니다. 현재 gemini-2.5-pro(기본값)와 gemini-flash-2.5를 지정할 수 있습니다.
- 참고: 무료 등급의 개인 Google 계정을 사용하는 경우, 할당량 문제로 인해 gemini-2.5-pro를 선택하더라도 CLI가 자동으로 gemini-flash-2.5 모델로 조정될 수 있습니다.
-p, --prompt "<프롬프트>": CLI의 대화형 세션을 시작하지 않고, 단일 질문에 대한 답변만 빠르게 얻고 싶을 때 사용합니다. 후속 질문으로 대화를 이어갈 수는 없습니다.
```
gemini -p "gcloud로 Google Cloud Run에 애플리케이션을 배포하는 명령어가 뭐야?"
```
-d, --debug: 디버그 모드를 활성화합니다. 평소에는 필요 없지만, 문제를 보고하거나 내부 동작을 이해하고 싶을 때 유용합니다.
- 디버그 모드를 사용하면 Gemini CLI가 어떻게 컨텍스트를 구성하는지 명확히 볼 수 있습니다. CLI는 현재 디렉토리에서 시작하여 상위 디렉토리로 거슬러 올라가며 루트 디렉토리에 도달할 때까지 GEMINI.md 파일을 찾습니다.
- 발견된 모든 GEMINI.md 파일의 내용은 하나로 합쳐져 모델에게 제공되는 지시적 컨텍스트(instructional context), 즉 **메모리(memory)**가 됩니다. 이 강력한 기능을 통해 프로젝트별 지침, 코딩 스타일 가이드, 기타 관련 배경 정보를 AI에 제공하여 응답을 필요에 맞게 더 정확하고 상세하게 조정할 수 있습니다.
-c, --checkpointing: 파일 편집에 대한 체크포인팅을 활성화합니다. 이 기능을 사용하면 Gemini CLI가 파일 시스템에 변경을 가할 때, 변경 전 상태를 Git 스냅샷으로 저장합니다. 이를 통해 작업 내용을 안전하게 추적하고 복원할 수 있습니다.
-y, --yolo: 'You Only Live Once' 모드로, 파일 쓰기나 명령어 실행 등 Gemini CLI가 수행하는 모든 작업을 사용자에게 묻지 않고 자동으로 수락합니다. 중요한 파일을 다룰 때는 주의해서 사용해야 합니다.

원격 측정 (Telemetry)

Gemini CLI는 OpenTelemetry를 기반으로 한 완전한 원격 측정 시스템을 제공하여 CLI의 성능, 상태, 사용 현황에 대한 상세한 데이터를 수집할 수 있습니다.

기본 통계 확인

CLI 내부에서 /stats 명령어를 실행하거나, CLI를 종료할 때 세션에 대한 간략한 통계가 표시됩니다.

Google Cloud를 이용한 상세한 원격 측정 설정

더 상세한 데이터를 원한다면, 원격 측정 데이터를 로컬 OpenTelemetry Collector를 통해 Google Cloud 프로젝트로 전송하도록 설정할 수 있습니다.

설정 과정:

OpenTelemetry Collector 설정:

OpenTelemetry Collector Contrib (opens in a new tab) 최신 버전을 다운로드합니다.
다음 내용으로 config.yaml 파일을 생성하고 Collector 실행 파일과 같은 위치에 저장합니다. YOUR_GOOGLE_CLOUD_PROJECT_ID를 자신의 프로젝트 ID로 변경해야 합니다.

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: localhost:4317
processors:
  batch:
exporters:
  googlecloud:
    project: "YOUR_GOOGLE_CLOUD_PROJECT_ID"
    metric:
      prefix: "custom.googleapis.com/gemini_cli"
    log:
      default_log_name: "gemini_cli"
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [googlecloud]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [googlecloud]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [googlecloud]

gcloud auth application-default login 명령으로 ADC(Application Default Credentials)를 설정하고, 해당 계정에 Cloud Trace Agent, Monitoring Metric Writer, Logs Writer 권한이 있는지 확인합니다.
./otelcol-contrib --config=config.yaml 명령으로 Collector를 실행합니다.

Telemetry 모드로 Gemini CLI 실행:
- 새 터미널에서 다음 명령어를 사용하여 Gemini CLI를 시작합니다. OTLP 엔드포인트는 Collector가 수신 대기하는 주소입니다.
```
gemini --telemetry=true --telemetry-target=gcp --telemetry-otlp-endpoint='http://localhost:4317'
```
Google Cloud Console에서 데이터 확인:
- 로그: Logs Explorer에서 로그 이름(gemini_cli)으로 필터링하여 CLI의 상세한 작동 기록을 볼 수 있습니다.
- 메트릭: Metrics Explorer에서 custom.googleapis.com/gemini_cli 접두사를 사용하는 메트릭(예: 요청 지연 시간)을 찾아 차트로 만들 수 있습니다.

참고: Romin Irani의 원문 작성 시점에는 트레이스 데이터가 Google Cloud로 전송되지 않는 문제가 있었다고 합니다.

Part 3: `settings.json` 및 `.env` 파일을 통한 구성 설정

세 번째 파트에서는 Gemini CLI의 설정을 영구적으로 관리하는 방법을 다룹니다. 매번 명령줄 옵션을 입력하는 대신 settings.json 파일과 .env 파일을 사용하여 사용자 전역 설정과 프로젝트별 설정을 지정할 수 있습니다.

전역(사용자) 설정과 로컬(프로젝트) 설정

Gemini CLI는 두 가지 위치의 settings.json 파일을 통해 설정을 관리합니다.

전역 (사용자) 설정:
- 위치: ~/.gemini/settings.json (사용자 홈 디렉토리)
- 용도: 모든 프로젝트에 공통적으로 적용될 개인적인 기본 설정을 정의합니다. (예: 테마, 인증 방식, 선호하는 편집기)
로컬 (프로젝트/작업공간) 설정:
- 위치: <프로젝트 루트>/.gemini/settings.json
- 용도: 특정 프로젝트에만 적용될 설정을 정의합니다. 이 파일을 버전 관리 시스템에 포함하면 팀원 전체가 일관된 설정(코딩 표준, 컨텍스트 파일 등)을 공유할 수 있습니다.

설정 적용 우선순위

설정은 여러 소스에서 적용될 수 있으며, 우선순위가 높은 설정이 낮은 순위의 설정을 덮어씁니다. 가장 높은 우선순위부터 나열하면 다음과 같습니다.

명령줄 인수: gemini --checkpointing처럼 CLI 실행 시 직접 전달하는 인수가 항상 최우선으로 적용됩니다.
환경 변수: 시스템 전반 또는 세션별 설정입니다. .env 파일에서 로드될 수 있으며, GEMINI_API_KEY 같은 변수가 대표적입니다.
프로젝트 설정 파일: 현재 프로젝트의 /.gemini/settings.json에 정의된 규칙입니다.
사용자 설정 파일: ~/.gemini/settings.json에 있는 개인 전역 설정입니다.
Gemini CLI 기본값: 애플리케이션에 하드코딩된 기본 설정(예: 기본 모델 "gemini-2.5-pro")입니다.

`settings.json`에 저장할 수 있는 설정 예시

인증 및 테마: CLI 최초 실행 시 선택한 selectedAuthType, theme 값은 자동으로 사용자 설정 파일에 저장됩니다.
```
{
  "selectedAuthType": "oauth-personal",
  "theme": "Default"
}
```
선호하는 편집기: /editor 명령으로 VS Code 같은 외부 편집기를 설정하면 preferredEditor 값이 추가됩니다.
```
{
  "preferredEditor": "vscode"
}
```
체크포인팅 활성화: 특정 프로젝트나 모든 프로젝트에 체크포인팅을 기본으로 활성화할 수 있습니다.
```
"checkpointing": {
  "enabled": true
}
```

참고: 모든 명령줄 옵션을 settings.json에 설정할 수 있는 것은 아니며, 그 반대의 경우도 마찬가지입니다. 자세한 내용은 공식 문서를 참고해야 합니다.

환경 변수 (`.env` 파일)

API 키와 같이 민감한 정보를 저장하기 위해 .env 파일을 사용하는 것이 가장 좋습니다. Gemini CLI는 다음 순서로 .env 파일을 찾아 로드합니다.

현재 작업 디렉토리의 .env 파일
상위 디렉토리로 이동하며 .env 파일을 찾음 (프로젝트 루트 .git 폴더나 홈 디렉토리까지)
사용자 홈 디렉토리의 ~/.env 파일

주요 환경 변수는 다음과 같습니다.

GEMINI_API_KEY: 개인 Gemini API 키를 설정합니다.
GOOGLE_CLOUD_PROJECT 및 GOOGLE_CLOUD_LOCATION: Vertex AI 등을 사용할 때 Google Cloud 프로젝트 ID와 위치를 지정합니다.
GOOGLE_APPLICATION_CREDENTIALS: gcloud CLI를 통해 설정된 애플리케이션 기본 사용자 인증 정보 경로입니다.

보충 설명: 생소할 수 있는 용어 정리

AI 에이전트(AI Agent): 환경을 인식하고 목표를 달성하기 위해 자율적으로 행동하는 프로그램을 말합니다. Gemini CLI는 터미널 환경에서 작동하는 AI 에이전트입니다.
CLI (Command Line Interface): 텍스트 기반으로 컴퓨터와 상호작용하는 인터페이스입니다.
Node.js: JavaScript를 브라우저 밖(서버나 로컬 머신)에서 실행할 수 있게 해주는 환경입니다. npm은 Node.js의 패키지 관리자입니다.
API 키(API Key): 특정 서비스(여기서는 Gemini API)를 사용할 때 사용자를 인증하기 위한 비밀 토큰입니다.
Vertex AI: Google Cloud의 통합 머신러닝 플랫폼입니다. 더 높은 사용량 한도나 세부적인 제어가 필요할 때 Gemini CLI와 연동하여 사용합니다.
샌드박스(Sandbox): 보안을 위해 프로그램을 외부 시스템과 격리된 환경에서 실행하는 기술입니다. 샌드박스 모드를 사용하면 AI가 시스템에 미칠 수 있는 잠재적 위험을 줄일 수 있습니다.
컨텍스트(Context): AI 모델이 응답을 생성할 때 참고하는 정보의 집합입니다. 대화 기록, @로 지정한 파일 내용 등이 컨텍스트에 포함됩니다.
Python 가상 환경(Virtual Environment): 프로젝트별로 독립된 Python 실행 환경을 만들어주는 도구입니다. 프로젝트마다 다른 버전의 패키지를 사용할 수 있어 의존성 충돌을 방지합니다.
체크포인팅(Checkpointing): 특정 시점의 작업 상태를 저장하는 것을 의미합니다. 중단된 작업을 나중에 그대로 다시 시작할 수 있게 해줍니다.
원격 측정 (Telemetry - Logs, Metrics, Traces): 시스템의 동작 및 성능에 대한 데이터를 수집하는 것을 말합니다.
- 로그(Logs): 이벤트가 발생한 기록입니다.
- 메트릭(Metrics): 요청 지연 시간, 토큰 사용량 등 숫자 값으로 측정된 데이터입니다.
- 트레이스(Traces): 단일 요청이 시스템의 여러 부분을 거치는 전체 흐름을 추적한 데이터입니다.
OpenTelemetry: 원격 측정 데이터를 수집, 처리, 내보내기 위한 오픈소스 표준 및 도구 모음입니다.

BugBot