GeminiCLI.net

npm으로 Gemini CLI 설치하는 방법: 2025년 완전 가이드

Gemini 가이드가 2025. 8. 26.에 작성

npm은 Gemini CLI를 설치하는 가장 인기 있고 권장되는 방법입니다. 이 포괄적인 가이드에서는 설치 과정을 안내하고, 일반적인 문제를 해결하며, Google의 강력한 AI 명령줄 도구 사용법을 보여드립니다.

🚀 빠른 시작: npm으로 Gemini CLI 설치

사전 요구사항

  • Node.js (버전 18 이상)
  • npm (Node.js와 함께 제공)
  • Google 계정 (API 키용)

원커맨드 설치

npm install -g @google/gemini-cli

이제 완료되었습니다! Gemini CLI가 시스템에 전역으로 설치되었습니다.

📋 상세 설치 단계

1단계: Node.js와 npm 확인

먼저 필요한 버전이 있는지 확인하세요:

node --version  # 18.0.0 이상이어야 함
npm --version   # 8.0.0 이상이어야 함

2단계: Gemini CLI 설치

npm install -g @google/gemini-cli

이 명령어가 하는 일:

  • Gemini CLI 최신 버전 다운로드
  • 전역 설치 (-g 플래그)
  • gemini 명령어를 시스템 전체에서 사용 가능하게 함

3단계: 설치 확인

gemini --version

다음과 같은 출력이 나타나야 합니다:

@google/gemini-cli/1.0.0 darwin-x64 node-v18.17.0

4단계: API 키 받기

  1. Google AI Studio 방문
  2. Google 계정으로 로그인
  3. "API 키 만들기" 클릭
  4. 생성된 키 복사

5단계: API 키 설정

macOS/Linux:

# 셸 프로필에 추가
echo 'export GOOGLE_API_KEY="your-api-key-here"' >> ~/.zshrc
source ~/.zshrc
 
# 또는 bash 사용자의 경우
echo 'export GOOGLE_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

Windows:

# 환경 변수 설정
setx GOOGLE_API_KEY "your-api-key-here"
 
# 터미널 재시작 또는 실행
refreshenv

6단계: 설치 테스트

gemini "안녕하세요, Gemini CLI가 작동하고 있습니다!"

🔧 대체 설치 방법

npx 사용 (전역 설치 없음)

전역으로 설치하고 싶지 않은 경우:

npx @google/gemini-cli "여기에 프롬프트 입력"

Yarn 사용

npm 대신 Yarn을 선호하는 경우:

yarn global add @google/gemini-cli

pnpm 사용

pnpm을 사용하는 경우:

pnpm add -g @google/gemini-cli

🛠️ 일반적인 문제 해결

문제 1: 권한 거부 오류

오류: EACCES: permission denied

해결책:

# 옵션 1: sudo 사용 (macOS/Linux)
sudo npm install -g @google/gemini-cli
 
# 옵션 2: 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

문제 2: 명령어를 찾을 수 없음

오류: gemini: command not found

해결책:

# 설치되었는지 확인
npm list -g @google/gemini-cli
 
# 필요시 재설치
npm uninstall -g @google/gemini-cli
npm install -g @google/gemini-cli
 
# PATH 확인
echo $PATH
which gemini

문제 3: API 키가 인식되지 않음

오류: API key not found

해결책:

# 환경 변수가 설정되었는지 확인
echo $GOOGLE_API_KEY
 
# 다시 설정
export GOOGLE_API_KEY="your-actual-api-key"
 
# 즉시 테스트
gemini "테스트"

문제 4: 네트워크 문제

오류: fetch failed 또는 network error

해결책:

# 인터넷 연결 확인
ping google.com
 
# 다른 DNS 시도
nslookup aistudio.google.com
 
# 필요시 VPN 사용
# 방화벽 설정 확인

📦 패키지 정보

현재 버전

npm view @google/gemini-cli version

패키지 세부사항

  • 패키지명: @google/gemini-cli
  • 게시자: Google
  • 라이선스: Apache-2.0
  • 저장소: GitHub

의존성

npm view @google/gemini-cli dependencies

🔄 Gemini CLI 업데이트

업데이트 확인

npm outdated -g @google/gemini-cli

최신 버전으로 업데이트

npm update -g @google/gemini-cli

특정 버전 설치

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

🎯 모범 사례

1. 전역 설치 사용

CLI 도구에는 전역 설치가 권장됩니다:

npm install -g @google/gemini-cli

2. 최신 상태 유지

정기적인 업데이트로 최신 기능과 버그 수정을 확보:

npm update -g @google/gemini-cli

3. API 키 보안 유지

API 키를 버전 관리에 커밋하지 마세요:

# 좋음: 환경 변수 사용
export GOOGLE_API_KEY="your-key"
 
# 나쁨: 스크립트에 하드코딩
gemini --key="your-key" "prompt"

4. 버전 관리 사용

프로젝트에서는 .nvmrc 파일 사용을 고려:

# .nvmrc
18.17.0

🚀 설치 후 시작하기

시도해볼 첫 번째 명령어

# 기본 상호작용
gemini "Gemini CLI란 무엇인가요?"
 
# 파일 분석
gemini -f package.json "이 package.json 파일을 설명해주세요"
 
# 코드 리뷰
gemini -f src/ "이 코드의 잠재적 문제를 리뷰해주세요"
 
# 문서 생성
gemini -f src/ "이 프로젝트의 README 문서를 생성해주세요"

워크플로우와 통합

# VS Code 통합
# VS Code의 tasks.json에 추가
{
  "label": "코드 리뷰",
  "type": "shell",
  "command": "gemini",
  "args": ["-f", "${file}", "이 코드의 버그와 개선사항을 리뷰해주세요"],
  "group": "build"
}
 
# Git 훅
# .git/hooks/pre-commit에 추가
#!/bin/sh
git diff --cached | gemini "컨벤셔널 커밋 메시지를 생성해주세요"

📊 성능 팁

속도 최적화

# 가능한 한 디렉토리 대신 특정 파일 사용
gemini -f src/main.js "이 파일을 리뷰해주세요"
 
# 관련 요청을 일괄 처리
gemini -f src/ "모든 파일의 보안 문제, 성능 문제, 코드 품질을 리뷰해주세요"

API 사용량 줄이기

# 테스트용으로 시뮬레이터 사용
# 방문: https://geminicli.net/simulator
 
# 최적화된 명령어용 프롬프트 생성기 사용
# 방문: https://geminicli.net/prompt-generator

🔍 고급 설정

사용자 정의 설정 파일

~/.gemini/config.json 생성:

{
  "model": "gemini-2.5-pro",
  "temperature": 0.7,
  "maxTokens": 4096
}

환경 변수

# 기본 모델 설정
export GEMINI_MODEL="gemini-2.5-pro"
 
# 온도 설정
export GEMINI_TEMPERATURE="0.7"
 
# 최대 토큰 수 설정
export GEMINI_MAX_TOKENS="4096"

🎉 결론

npm으로 Gemini CLI를 설치하는 것은 간단하고 신뢰할 수 있습니다. 전역 설치로 시스템 전체에서 사용 가능하며, 공식 Google 패키지로 최신 기능과 보안 업데이트를 확실히 받을 수 있습니다.

핵심 포인트:

  • 설치에는 npm install -g @google/gemini-cli 사용
  • API 키를 환경 변수로 설정
  • 패키지를 정기적으로 업데이트
  • 워크플로우 최적화를 위해 무료 도구 사용

시작할 준비가 되셨나요? 설치 없이 Gemini CLI를 경험하려면 온라인 시뮬레이터를 시도하거나, 단계별 지침은 대화형 설치 가이드를 따르세요.

도움이 필요하신가요? 일반적인 질문은 FAQ를 확인하거나, 지원은 커뮤니티에 참여하세요.

이 글 공유하기: