Gemini CLI 실전 가이드 — 터미널에서 Google AI 100% 활용하기

터미널을 벗어나지 않고 Google AI를 호출할 수 있다면 어떨까요? Gemini CLI는 바로 그 답입니다. 브라우저를 열고 AI 채팅 창에 붙여넣는 작업을 반복하던 시절은 지났습니다. 커맨드라인에서 코드 리뷰, 문서 요약, 테스트 생성까지 한 번에 처리할 수 있습니다. 13년간 터미널을 주요 작업 환경으로 삼아온 입장에서, Gemini CLI는 생산성 향상 측면에서 손에 꼽을 만한 도구입니다.

Gemini CLI란?

#

Gemini CLI는 Google이 공식 제공하는 커맨드라인 인터페이스로, Gemini 2.5 Pro 모델을 터미널에서 직접 호출할 수 있게 해줍니다. 단순한 텍스트 질의에 그치지 않고, 현재 디렉토리의 파일을 컨텍스트로 전달하거나 파이프를 통해 출력을 연결하는 등 개발 워크플로우에 자연스럽게 녹아드는 기능을 제공합니다.

핵심 특징을 먼저 짚겠습니다.

• 100만 토큰 컨텍스트 윈도우: 대규모 코드베이스 전체를 한 번에 전달 가능합니다.
• 무료 사용 한도: 개인 Google 계정 기준 월 60회 이상의 무료 요청을 제공합니다.
• 파이프라인 통합: cat file.py | gemini "이 코드 설명해줘" 형태로 Unix 파이프와 완벽히 호환됩니다.
• 멀티모달 지원: 텍스트뿐 아니라 이미지, PDF도 입력으로 처리합니다.

설치 방법

#

Node.js 18 이상이 설치된 환경이라면 npm 한 줄로 설치가 완료됩니다.

1

npm install -g @google/gemini-cli

설치 후 버전을 확인합니다.

1

gemini --version

Google 계정 인증

#

1

gemini auth login

명령 실행 시 브라우저가 열리며 Google 계정 로그인 페이지로 이동합니다. 로그인 완료 후 터미널로 돌아오면 인증이 완료됩니다. API 키를 별도로 발급받아 환경 변수로 설정하는 방식도 지원합니다.

1

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

팀 프로젝트나 CI 환경에서는 API 키 방식이 더 적합합니다.

기본 명령어

#

단순 질의

#

1

gemini "Python에서 async/await를 언제 써야 해?"

응답이 마크다운 형식으로 터미널에 출력됩니다. 기본적으로 Gemini 2.5 Pro 모델이 사용됩니다.

파일을 컨텍스트로 전달

#

1

cat src/api/users.ts | gemini "이 코드에서 보안 취약점을 찾아줘"

파이프를 통해 파일 내용을 stdin으로 전달할 수 있습니다. 여러 파일을 한 번에 전달하는 것도 가능합니다.

1

cat src/**/*.ts | gemini "이 TypeScript 코드베이스의 전반적인 아키텍처를 설명해줘"

파일을 직접 지정

#

1

gemini -f src/main.py "이 파일의 함수들을 정리해줘"

-f 플래그로 파일을 직접 지정합니다. 이미지 파일도 동일하게 전달할 수 있습니다.

1

gemini -f screenshot.png "이 UI에서 개선이 필요한 부분을 알려줘"

모델 선택

#

1

gemini --model gemini-2.5-flash "간단한 요약이 필요해"

응답 속도가 중요할 때는 Flash 모델을 선택합니다. Pro 모델보다 빠르지만 복잡한 추론에는 Pro가 더 적합합니다.

대화형 세션

#

1

gemini chat

연속 대화가 필요할 때는 채팅 모드를 사용합니다. 이전 대화 맥락을 유지하면서 여러 질문을 이어갈 수 있습니다.

코딩 실전 활용

#

코드 리뷰 자동화

#

PR을 올리기 전 로컬에서 빠르게 리뷰를 받을 수 있습니다.

1

git diff HEAD~1 | gemini "이 변경사항을 리뷰해줘. 버그, 성능 문제, 코드 품질 순으로 정리해줘"

diff 출력을 파이프로 전달하면 변경 사항만 집중적으로 분석합니다.

테스트 자동 생성

#

1

cat src/utils/dateFormatter.ts | gemini "이 모듈에 대한 Jest 테스트 코드를 작성해줘. 엣지 케이스 포함"

기존 함수 시그니처와 로직을 파악해 적절한 테스트 케이스를 생성합니다.

에러 메시지 디버깅

#

1

cat error.log | gemini "이 에러의 원인을 분석하고 해결 방법을 제안해줘"

스택 트레이스나 로그 파일을 그대로 전달하면 원인 분석과 수정 방향을 제시합니다.

문서 생성

#

1

cat src/api/payment.ts | gemini "이 API 모듈의 JSDoc 주석과 README 섹션을 작성해줘"

코드에서 직접 문서를 생성하는 작업에 특히 유용합니다.

Git 커밋 메시지 작성

#

1

git diff --staged | gemini "이 변경사항에 대한 Conventional Commits 형식의 커밋 메시지를 작성해줘"

스테이징된 변경 사항을 분석해 규격에 맞는 커밋 메시지를 제안합니다.

쉘 스크립트와 통합

#

반복 작업은 쉘 스크립트로 묶어 단축키처럼 사용할 수 있습니다.

1
2
3
4
5

#!/bin/bash
# review.sh — 현재 브랜치의 변경사항 리뷰
BRANCH=$(git branch --show-current)
echo "브랜치 $BRANCH 리뷰 시작..."
git diff main...$BRANCH | gemini "이 PR의 변경사항을 리뷰해줘. 주요 변경점, 잠재적 문제, 개선 제안 순으로 정리해줘"

1
2

chmod +x review.sh
./review.sh

.bashrc / .zshrc 에 함수로 등록

#

1
2
3
4
5
6
7
8
9

# 파일 설명 요청
gai() {
  cat "$1" | gemini "이 파일을 분석하고 핵심 내용을 한국어로 설명해줘"
}

# 에러 빠른 분석
gaierr() {
  echo "$1" | gemini "이 에러 메시지의 원인과 해결책을 한국어로 알려줘"
}

사용법은 간단합니다.

1
2

gai src/auth/middleware.ts
gaierr "TypeError: Cannot read properties of undefined (reading 'map')"

CI/CD 파이프라인 통합

#

GitHub Actions에서 PR 리뷰 자동화에 활용할 수 있습니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# .github/workflows/ai-review.yml
name: AI Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g @google/gemini-cli
      - name: AI Review
        env:
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
        run: |
          git diff origin/main...HEAD | gemini "이 PR을 리뷰해줘" > review.txt
          cat review.txt

Claude Code와의 비교

#

두 도구 모두 훌륭하지만 사용 목적이 다릅니다.

실무에서는 두 도구를 병행 사용하는 것을 권장합니다. 대규모 코드베이스 분석이나 무료 한도 내 작업에는 Gemini CLI를, 코드 직접 편집과 프로젝트 전반을 다루는 작업에는 Claude Code를 선택하는 방식입니다.

프롬프트 작성 팁

#

좋은 결과를 얻으려면 질문을 구체적으로 작성해야 합니다.

나쁜 예시:

1

gemini "코드 리뷰해줘"

좋은 예시:

1

cat auth.ts | gemini "이 인증 모듈을 리뷰해줘. 특히 JWT 검증 로직의 보안 취약점, 에러 핸들링 누락, TypeScript 타입 정확성 순으로 문제점을 찾아줘. 각 문제에는 수정 코드 예시를 포함해줘"

역할을 부여하면 더 전문적인 답변을 얻을 수 있습니다.

1

cat system.log | gemini "당신은 10년 경력의 SRE입니다. 이 로그에서 인시던트 원인을 분석하고 RCA 형식으로 정리해줘"

자주 마주치는 문제와 해결책

#

인증 만료 오류

1

gemini auth refresh

응답이 너무 길게 잘리는 경우

1

gemini --max-output-tokens 8192 "긴 답변이 필요한 질문"

한국어 응답이 원하는 경우

1

gemini "답변은 반드시 한국어로 작성해줘. 질문: ..."

시스템 프롬프트 파일을 설정 파일로 지정해두면 매번 언급하지 않아도 됩니다.

1
2
3

# ~/.gemini/system.md
당신은 한국어로 답변하는 시니어 소프트웨어 엔지니어입니다.
기술적 질문에 대해 실용적이고 간결한 답변을 제공합니다.

정리

#

Gemini CLI는 AI를 개발 워크플로우 안에 자연스럽게 녹여넣을 수 있는 실용적인 도구입니다. 터미널을 주 작업 환경으로 사용한다면 반드시 한 번은 써볼 가치가 있습니다. 특히 100만 토큰 컨텍스트와 무료 사용 한도는 다른 도구에서 찾기 어려운 장점입니다. 설치에 5분, 기본 사용법 익히는 데 10분이면 충분합니다. 오늘 당장 터미널을 열어 npm install -g @google/gemini-cli를 실행해보시기 바랍니다.