제미나이 CLI 설치
터미널 속 AI 코딩 파트너, Gemini CLI
Gemini CLI는 단순한 챗봇을 넘어, 개발자의 터미널 환경에서 코드 분석, 버그 수정, 작업 자동화를 수행하는 강력한 AI 에이전트입니다. 이 가이드는 복잡한 설치 과정을 명확하고 간단하게 안내하여 여러분의 개발 생산성을 한 단계 끌어올리는 것을 목표로 합니다.
어떤 Gemini 도구를 사용해야 할까요?
Gemini라는 이름의 여러 도구가 있어 혼동하기 쉽습니다. 이 가이드는 터미널에서 대화형으로 사용하는 공식 Gemini CLI에 초점을 맞춥니다. 아래 표를 통해 자신의 목적에 맞는 도구를 확인하세요.
| 도구 이름 | 주요 기술 | 사용 사례 | 상태 |
|---|---|---|---|
| Gemini CLI | Node.js | 터미널 기반 AI 에이전트 | 활성 (권장) |
| Google Gen AI SDK | Python | Python 앱에서 API 호출 | 활성 (권장) |
| 레거시 SDK | Python | 구버전 앱에서 API 호출 | 사용 중단 |
넉넉한 무료 사용량
개인 Google 계정으로 로그인만 하면 Gemini 1.5 Pro 모델을 무료로 사용할 수 있습니다. 요청 한도는 다음과 같습니다.
1단계: 시스템 준비하기
Gemini CLI는 Node.js 런타임 환경에서 실행됩니다. 먼저 사용 중인 운영체제에 맞는 Node.js v18 이상 버전을 설치해야 합니다.
macOS & Linux (NVM 사용 권장)
NVM(Node Version Manager)을 사용하면 Node.js 버전을 쉽게 관리할 수 있습니다.
1. NVM 설치
2. Node.js LTS 버전 설치 및 사용 (터미널 재시작 후)
3. 설치 확인 (v18 이상)
2단계: Gemini CLI 설치하기
사용 목적에 따라 두 가지 설치 방법 중 하나를 선택할 수 있습니다.
방법 1: `npx` (시험 사용)
시스템에 영구 설치하지 않고, 필요할 때마다 최신 버전을 실행합니다. 가끔 사용하거나 테스트용으로 적합합니다.
방법 2: 전역 설치 (일상 사용)
시스템 전역에 영구적으로 설치하여 어디서든 `gemini` 명령어로 실행할 수 있습니다. 매일 사용하는 개발자에게 권장됩니다.
설치 후 터미널에 `gemini`를 입력하여 실행을 확인하세요!
3단계: 인증하기
Gemini 모델을 사용하려면 Google에 인증해야 합니다. 간편한 계정 로그인 방식과 고급 사용자를 위한 API 키 방식이 있습니다.
경로 1: Google 계정 로그인 (권장)
가장 간단한 방법입니다. `gemini`를 처음 실행하면 브라우저가 열리고 Google 계정으로 로그인하라는 안내가 나옵니다.
- ✔ API 키 없이 Gemini 1.5 Pro 즉시 사용
- ✔ 넉넉한 무료 사용량 자동 적용
- ✔ 별도의 키 관리 필요 없음
경로 2: API 키 사용 (고급)
자동화 스크립트나 CI/CD 환경, 또는 브라우저 인증이 어려운 환경에서 사용합니다.
- Google AI Studio에서 API 키 생성
- `GEMINI_API_KEY` 환경 변수 설정
`GEMINI_API_KEY` 환경 변수 설정 가이드
영구 설정 (`~/.zshrc` 또는 `~/.bashrc` 파일에 추가)
변경 후 `source ~/.zshrc`를 실행하거나 터미널을 재시작하세요.
4단계: 문제 해결하기
설치나 인증 중 문제가 발생했나요? 일반적인 문제와 해결책을 확인해 보세요.
로그인 실패: `GOOGLE_CLOUD_PROJECT` 오류
▼원인: 개인 계정이 Workspace 계정으로 잘못 인식되어 발생하는 인증 충돌입니다.
해결책: 가장 확실한 해결책은 API 키 인증 방식으로 전환하는 것입니다. 또는 터미널에서 `rm -rf ~/.gemini` 명령으로 캐시를 삭제하고 다시 시도해 보세요.
인증 차단: “localhost에 연결할 수 없음”
▼원인: 백신이나 방화벽 같은 보안 소프트웨어가 CLI와 브라우저 간의 인증 통신을 차단하는 경우가 대부분입니다.
해결책: 보안 프로그램을 잠시 비활성화하고 인증을 다시 시도해 보세요. 성공하면, Node.js (`node.exe`)와 사용 중인 터미널(e.g., `powershell.exe`)을 예외 목록에 추가하세요.
API 오류: `429 RESOURCE_EXHAUSTED`
▼원인: 무료 등급의 분당 요청 한도를 초과했습니다.
해결책: 1분 정도 기다린 후 다시 시도하세요. 지속적으로 높은 사용량이 필요하다면 Google Cloud에서 유료 플랜으로 전환을 고려해야 합니다.
