Gemini CLI 사용법: 설치, API 키 설정, 터미널 자동화까지 2026 가이드

Gemini CLI 사용법: 설치, API 키 설정, 터미널 자동화까지 2026 가이드#

Gemini CLI는 터미널에서 Gemini 모델을 바로 사용하는 도구입니다. 브라우저를 열지 않고 코드 설명, 파일 요약, 문서 작성, 간단한 자동화까지 처리할 수 있습니다.

하지만 처음 쓰는 사람에게는 헷갈리는 지점이 있습니다.

• Node.js 버전은 몇 이상이어야 할까?
• API 키는 어디에 넣어야 할까?
• GEMINI_API_KEY와 GOOGLE_API_KEY는 뭐가 다를까?
• 로컬 파일을 읽고 쓰는 권한은 어떻게 관리할까?
• 회사나 팀에서 여러 모델을 함께 쓰려면 어떻게 해야 할까?

이 글은 Gemini CLI 사용법을 설치부터 실전 예제까지 한 번에 정리합니다.

Gemini CLI란?#

Gemini CLI는 명령줄에서 Gemini 모델을 호출하고, 필요하면 로컬 파일이나 셸 명령과 함께 작업할 수 있게 해주는 개발자 도구입니다.

일반 챗봇과 다른 점은 "터미널 안에서 작업한다"는 것입니다. 예를 들어 다음과 같은 일을 시킬 수 있습니다.

• 현재 프로젝트의 README 요약
• 에러 로그 분석
• 테스트 코드 초안 작성
• 파일 생성 또는 수정
• 웹 검색 후 결과를 파일로 저장
• MCP 서버나 외부 도구와 연결

Google Codelab에서도 Gemini CLI가 내장 도구를 통해 파일 읽기, 파일 쓰기, 검색, 셸 실행 같은 작업을 수행할 수 있다고 설명합니다. 단, 민감한 작업은 사용자의 권한 확인을 거칩니다.

준비물#

Node.js가 오래된 버전이면 먼저 업데이트하세요.

node -v
npm -v

Node.js 20 이상이 아니라면 nvm, fnm, Homebrew, winget 같은 도구로 업데이트하는 편이 안전합니다.

Gemini CLI 설치#

가장 간단한 방법은 npx로 바로 실행하는 것입니다.

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

자주 쓸 계획이라면 전역 설치를 선택할 수 있습니다.

npm install -g @google/gemini-cli

설치 후에는 다음처럼 실행합니다.

gemini

설치가 안 되거나 명령어를 찾을 수 없다는 오류가 나오면 npm 전역 경로가 PATH에 들어가 있는지 확인하세요.

Gemini API 키 설정#

Google의 API 키 문서에서는 환경 변수 사용을 권장합니다. Gemini API 클라이언트는 보통 GEMINI_API_KEY 또는 GOOGLE_API_KEY를 감지합니다. 둘 다 설정된 경우 일부 환경에서는 GOOGLE_API_KEY가 우선될 수 있습니다.

macOS / Linux#

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

영구 적용하려면 셸 설정 파일에 추가합니다.

echo 'export GEMINI_API_KEY="your-gemini-api-key"' >> ~/.zshrc
source ~/.zshrc

bash를 쓰면 ~/.bashrc 또는 ~/.bash_profile에 넣으면 됩니다.

Windows PowerShell#

setx GEMINI_API_KEY "your-gemini-api-key"

새 PowerShell 창을 열고 확인합니다.

$env:GEMINI_API_KEY

키가 잘 들어갔는지 확인#

printenv GEMINI_API_KEY

Windows PowerShell에서는:

echo $env:GEMINI_API_KEY

실제 운영 환경에서는 API 키를 코드에 직접 쓰지 마세요. .env, CI secret, OS 환경 변수 중 하나를 사용하세요.

첫 실행: 터미널에서 질문하기#

Gemini CLI를 실행한 뒤 간단히 질문해 봅니다.

gemini

프롬프트가 열리면 다음처럼 입력합니다.

이 프로젝트의 package.json을 읽고 어떤 앱인지 5줄로 설명해줘.

현재 폴더에 파일이 있다면 Gemini CLI가 파일을 읽을 권한을 요청할 수 있습니다. 권한 요청이 나오면 내용을 확인하고 허용하세요.

기본 명령어와 사용 패턴#

Gemini CLI는 단순 답변 도구가 아니라 작업 흐름 도구에 가깝습니다. 그래서 좋은 프롬프트는 "답만 줘"보다 "계획 → 확인 → 실행" 구조가 좋습니다.

예시:

이 저장소의 인증 코드를 개선하고 싶다.
1. 먼저 관련 파일을 찾아라.
2. 변경 계획을 제안하라.
3. 내가 확인하기 전에는 파일을 수정하지 마라.

파일 읽기와 쓰기 권한 이해하기#

Gemini CLI는 로컬 환경과 상호작용할 수 있습니다. 이 점이 강력하지만 동시에 조심해야 합니다.

처음에는 --yolo 같은 자동 허용 모드를 쓰지 않는 편이 좋습니다. 생산성보다 안전이 먼저입니다.

실전 예제 1: 에러 로그 분석#

cat error.log | gemini -p "이 로그에서 가장 가능성 높은 원인 3개와 확인 명령어를 알려줘"

또는 대화형 모드에서:

@error.log 파일을 읽고 장애 원인을 우선순위별로 정리해줘. 수정은 하지 말고 확인 명령어만 제안해줘.

좋은 출력은 다음을 포함해야 합니다.

• 가장 가능성 높은 원인
• 재현 방법
• 확인 명령어
• 위험한 수정과 안전한 수정 구분

실전 예제 2: README 자동 업데이트#

현재 저장소를 읽고 README.md에 빠진 설치/실행/테스트 명령어를 추가하는 계획을 세워줘. 먼저 diff 계획만 보여줘.

계획이 괜찮으면 다음 단계로 진행합니다.

좋아. README.md만 수정해줘. 다른 파일은 건드리지 마.

수정 후에는 반드시 확인합니다.

git diff README.md

실전 예제 3: API 클라이언트 코드 만들기#

Gemini CLI에게 OpenAI 호환 API 클라이언트 예제를 만들게 할 수도 있습니다. 예를 들어 여러 모델을 한 인터페이스에서 바꾸고 싶다면 다음 구조를 사용할 수 있습니다.

from openai import OpenAI

client = OpenAI(
    api_key="your-api-key",
    base_url="https://crazyrouter.com/v1"
)

response = client.chat.completions.create(
    model="gemini-3-flash-preview",
    messages=[
        {"role": "user", "content": "한국어로 Gemini CLI 사용법을 5줄로 설명해줘."}
    ]
)

print(response.choices[0].message.content)

이 방식은 Gemini만 쓰는 것이 아니라 Claude, GPT, DeepSeek, Qwen 같은 모델도 같은 OpenAI 호환 클라이언트에서 바꾸고 싶은 팀에 유용합니다.

Gemini CLI와 API Gateway를 함께 쓰는 이유#

Gemini CLI 자체는 Google 생태계에 잘 맞습니다. 하지만 팀에서는 보통 Gemini 하나만 쓰지 않습니다.

• 코딩 리뷰에는 Claude를 쓰고 싶다.
• 긴 문서 요약에는 Gemini를 쓰고 싶다.
• 저렴한 분류 작업에는 DeepSeek나 Haiku급 모델을 쓰고 싶다.
• 이미지나 영상 모델도 같은 과금 체계에서 관리하고 싶다.

이럴 때는 API gateway가 편합니다. With Crazyrouter, you can route requests to 627+ models through one API key and keep OpenAI-compatible client code for many workflows.

예를 들어 개발 도구에서는 Gemini CLI를 쓰고, 앱 서버에서는 Crazyrouter base_url로 여러 모델을 호출하는 구성을 만들 수 있습니다.

문제 해결: Gemini CLI 사용 중 자주 보는 오류#

안전한 Gemini CLI 워크플로우#

처음에는 아래 규칙을 추천합니다.

1. 항상 git 저장소 안에서 작업한다.
2. 큰 변경 전에는 브랜치를 만든다.
3. "먼저 계획만 세워줘"라고 요청한다.
4. 파일 수정 권한은 필요한 경우에만 1회 허용한다.
5. 수정 후 git diff를 확인한다.
6. 테스트 명령어를 직접 실행한다.
7. API 키는 코드에 넣지 않는다.

예시:

git checkout -b gemini-cli-test

이 기능을 구현하기 전에 변경할 파일 목록과 테스트 계획만 작성해줘. 아직 코드는 수정하지 마.

Gemini CLI 사용법 요약#

FAQ: Gemini CLI 사용법#

Gemini CLI 사용법을 배우려면 무엇부터 해야 하나요?#

Node.js 20 이상을 설치하고, Gemini API 키를 환경 변수로 설정한 뒤, gemini 또는 npx로 실행해 작은 질문부터 테스트하면 됩니다.

Gemini CLI는 무료인가요?#

도구 자체는 사용할 수 있지만, 모델 호출은 Google 계정의 무료 할당량이나 API 과금 정책을 따릅니다. 사용량이 많다면 요금과 rate limit을 확인해야 합니다.

GEMINI_API_KEY와 GOOGLE_API_KEY 중 무엇을 써야 하나요?#

Gemini API 문서는 환경 변수 사용을 권장하며, 보통 GEMINI_API_KEY 또는 GOOGLE_API_KEY를 사용할 수 있습니다. 둘 다 설정된 경우 환경에 따라 우선순위가 달라질 수 있으므로 하나만 명확히 쓰는 편이 안전합니다.

Gemini CLI가 로컬 파일을 마음대로 수정하나요?#

민감한 작업은 보통 권한 확인을 거칩니다. 그래도 안전을 위해 자동 허용 모드를 피하고, 수정 전 계획을 요청하고, 수정 후 git diff를 확인하세요.

Gemini CLI에서 Crazyrouter를 꼭 써야 하나요?#

아니요. Gemini CLI 자체는 Google Gemini 사용에 적합합니다. 다만 앱 서버나 자동화 스크립트에서 Gemini 외에 Claude, GPT, DeepSeek, Qwen 같은 모델도 함께 쓰려면 Crazyrouter 같은 OpenAI 호환 API gateway가 편합니다.

관련 링크#

• Google Gemini API 키 문서
• Google Gemini CLI Codelab
• Crazyrouter Pricing
• Crazyrouter API Docs