Gemini CLI 설치 가이드: Mac·Windows 사용자 완벽 활용법

Gemini CLI 설치 가이드: Mac·Windows 사용자 완벽 활용법

 

Gemini CLI는 터미널에서 직접 Google의 강력한 AI 모델을 활용할 수 있는 무료 오픈소스 도구로, 개발자 생산성을 극대화하는 혁신적인 AI 명령줄 도구입니다.

---

Gemini CLI 소개 및 핵심 기능

Gemini CLI란 무엇인가

Gemini CLI는 터미널에서 직접 Gemini의 강력한 기능을 제공하는 오픈소스 AI 에이전트입니다.

개발자들이 웹 브라우저를 열지 않고도 터미널 환경에서 바로 Google의 최신 AI 모델인 Gemini 2.5 Pro를 활용할 수 있도록 설계된 혁신적인 도구입니다.

주요 특징

 

무료 사용량: 개인 Google 계정으로 분당 60회 요청, 일일 1,000회 요청 제한으로 완전 무료 사용 가능

 

강력한 성능

• Gemini 2.5 Pro 모델 기반
• 100만 토큰 컨텍스트 윈도우 지원
• 자연어 명령 이해 및 실행

다양한 기능

• 코드 생성, 분석, 리팩토링
• 버그 수정 및 디버깅
• 파일 시스템 조작
• 웹 검색 및 정보 수집
• MCP(Model Context Protocol) 서버 연동

개발자 생산성 툴로서의 가치

Gemini CLI는 개발자가 터미널 환경을 벗어나지 않고도 Google의 강력한 Gemini AI 모델을 직접 활용할 수 있도록 돕는 도구입니다.

코딩, 디버깅, 콘텐츠 생성, 복잡한 문제 해결 등 다양한 작업을 자연어 명령으로 처리하여 개발자의 생산성을 획기적으로 높여줍니다.

---

사전 요구사항

시스템 요구사항

Mac 사용자

• macOS 10.15 이상
• Node.js 18.0 이상 권장 (최소 16.0)
• 최소 512MB RAM
• 100MB 디스크 공간

Windows 사용자

• Windows 10/11
• Node.js 18.0 이상 권장 (최소 16.0)
• PowerShell 또는 Command Prompt
• WSL2 지원 (선택사항)

Node.js 및 npm 설치 확인 방법

터미널에서 다음 명령어를 실행하여 Node.js 설치 상태를 확인하세요

node -v
npm -v

 

현재(2025년 7월 기준) Node.js 22 LTS 버전을 권장합니다.

npm 최신버전 업데이트

Node.js가 설치되어 있더라도 npm이 구버전일 수 있습니다. Gemini CLI의 원활한 설치를 위해 npm을 최신 버전으로 업데이트하는 것을 강력히 권장합니다.

 

npm 현재 버전 확인

npm -v

 

npm 최신버전으로 업데이트

Mac/Linux 사용자

# npm 최신 버전으로 업데이트
npm install -g npm@latest

# 또는 특정 버전 설치
npm install -g npm@10.8.2

 

Windows 사용자

# PowerShell을 관리자 권한으로 실행 후
npm install -g npm@latest

# npm 버전 재확인
npm -v

 

npm 업데이트 확인

npm -v
# 9.0.0 이상 버전이 권장됩니다

npm 구버전 사용 시 Gemini CLI 설치 과정에서 의존성 충돌이나 설치 오류가 발생할 수 있으므로, 반드시 최신 버전으로 업데이트 후 진행하시기 바랍니다.

Google 계정 준비

Gemini CLI 사용을 위해서는 개인 Google 계정이 필요합니다.
Google Workspace 계정도 지원하지만, 개인 계정 사용을 권장합니다.

Google 계정 만들기

---

Mac 사용자를 위한 설치 가이드

Node.js 설치 (Mac)

방법 1: nvm(Node Version Manager) 사용 (권장)

# nvm 설치
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 터미널 재시작 또는 다음 명령어 실행
source ~/.zshrc  # zsh 사용자
source ~/.bashrc # bash 사용자

# Node.js 최신 LTS 버전 설치
nvm install --lts
nvm use --lts

 

방법 2: 공식 인스톨러 사용

Node.js 공식 웹사이트에서 macOS 인스톨러를 다운로드하여 설치하세요.

Gemini CLI Mac 설치

Node.js와 npm이 최신 버전으로 설치되고 확인되면, 터미널에서 다음 명령어를 실행하여 Gemini CLI를 설치할 수 있습니다.

 

전역 설치 방법

npm install -g @google/gemini-cli

 

임시 실행 방법 (설치 없이 바로 사용)

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

macOS 권한 설정

macOS에서는 설치 과정에서 관리자 권한이 필요할 수 있습니다.
sudo 권한 요청 시 시스템 비밀번호를 입력하세요.

---

Windows 사용자를 위한 설치 가이드

Node.js 설치 (Windows)

방법 1: Winget 사용 (Windows 10/11)

# PowerShell을 관리자 권한으로 실행
winget install OpenJS.NodeJS.LTS --silent

 

방법 2: Chocolatey 사용

# Chocolatey가 설치되어 있는 경우
choco install nodejs-lts -y

 

방법 3: 공식 인스톨러 사용

Node.js 공식 웹사이트에서 Windows 인스톨러를 다운로드하여 설치하세요.

Gemini CLI Windows 설치

PowerShell 또는 Command Prompt를 관리자 권한으로 실행한 후, npm이 최신 버전인지 확인하고 다음 명령어를 입력하세요.

 

전역 설치

npm install -g @google/gemini-cli

 

설치 확인

gemini --version
where gemini

Windows 환경별 특이사항

PowerShell 사용자

• Windows PowerShell 5.1 이상 권장
• PowerShell Core 7.0 이상 지원

WSL2 사용자

• Ubuntu 18.04 이상에서 정상 동작
• Linux 설치 가이드와 동일한 방법 사용

---

초기 설정 및 인증

첫 실행 및 테마 선택

Gemini를 실행하면 먼저 화면 테마를 선택하는 화면이 나타납니다.

 

터미널에서 다음 명령어를 입력하세요

gemini

 

테마 선택 옵션

• Dark: 어두운 테마 (권장)
• Light: 밝은 테마
• High Contrast: 고대비 테마

Google 계정 인증

테마 선택 후 인증 방법을 선택하는 화면이 나타납니다.

 

인증 방법 옵션

1. Login with Google (권장): 개인 Google 계정 사용
2. API Key: Google AI Studio API 키 사용
3. Vertex AI: Google Cloud Vertex AI 사용

Login with Google 선택 시

1. 'Login with Google' 선택 후 Enter
2. 웹 브라우저가 자동으로 열림
3. Google 계정으로 로그인
4. 권한 허용
5. 인증 완료 메시지 확인

API 키를 이용한 인증 (선택사항)

더 높은 사용량이 필요한 경우 API 키 방식을 사용할 수 있습니다:

# Google AI Studio에서 API 키 발급 후
export GEMINI_API_KEY="YOUR_API_KEY"
gemini

Google AI Studio에서 API 키 발급받기

---

Gemini CLI 기본 사용법

기본 명령어 구조

Gemini CLI는 자연어 기반의 대화형 인터페이스를 제공합니다.

gemini
> 질문이나 요청을 입력하세요

주요 내장 명령어

Gemini-CLI 내에 내장된 명령어들을 적절히 활용하여 원하는 작업을 수행할 수 있습니다.

명령어	기능	사용법
/auth	인증 설정	/auth
/memory	메모리 관리	/memory show
/tools	사용 가능한 도구 목록	/tools
/mcp	MCP 서버 관리	/mcp list
/quit	CLI 종료	/quit
/help	도움말 표시	/help

파일 및 디렉토리 작업

파일 참조하기
@를 사용하여 파일이나 경로를 지정할 수 있습니다.

> @filename.py 이 파일을 분석해줘
> @./src/components 이 디렉토리 구조를 설명해줘

 

파일 생성 및 수정

> README.md 파일을 생성해서 프로젝트 설명을 작성해줘
> package.json에 새로운 의존성을 추가해줘

웹 검색 및 정보 수집

Gemini CLI는 구글 검색 기능을 내장하고 있어 실시간 정보 검색이 가능합니다.

> 최신 React 18의 주요 변경사항을 검색해서 알려줘
> 현재 JavaScript 트렌드를 조사해줘

---

고급 활용 방법

MCP 서버 연동

MCP(Model Context Protocol)는 개발자가 도메인별 특화 기능을 추가할 수 있도록 하는 개방형 표준입니다.

 

GitHub MCP 서버 설정 예시

1. 프로젝트 폴더에서 설정 파일 생성

mkdir .gemini
cd .gemini

2. mcp_settings.json 파일 생성

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_TOKEN"
      }
    }
  }
}

3. Gemini CLI 재시작 후 GitHub 기능 사용

> @github 내 오픈 풀 리퀘스트 목록을 보여줘
> @github 최근 커밋 내역을 요약해줘

코드 리뷰 및 최적화

코드 분석 및 개선

> 이 함수의 성능을 개선할 방법을 제안해줘
> 코드 스타일을 일관성 있게 정리해줘
> 단위 테스트를 작성해줘

 

버그 수정

> 이 에러를 분석하고 해결책을 제시해줘
> 메모리 누수 가능성을 점검해줘

프로젝트 자동화

문서 생성

> API 문서를 마크다운 형식으로 생성해줘
> 변경 로그를 작성해줘

 

배포 스크립트 작성

> Docker 배포를 위한 Dockerfile을 작성해줘
> CI/CD 파이프라인 설정파일을 만들어줘

---

설치 오류 해결

일반적인 설치 오류

Node.js 버전 문제

Error: Node.js version not supported

해결방법: Node.js 18 이상으로 업그레이드

 

권한 오류 (Mac/Linux)

Error: EACCES: permission denied

 

해결방법

sudo npm install -g @google/gemini-cli
# 또는 nvm 사용 권장

 

npm 구버전으로 인한 설치 실패

Error: npm version too old

 

해결방법

npm install -g npm@latest
# 설치 후 터미널 재시작
gemini --version

 

네트워크 오류

Error: network timeout

 

해결방법

• 방화벽 설정 확인
• 프록시 환경에서는 npm 프록시 설정
• VPN 연결 확인

Windows 특화 오류 해결

PowerShell 실행 정책 오류

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

저도 윈도우에 설치할때 FullyQualifiedErrorId : UnauthorizedAccess 에러가 났었는데, 윈도우 정책 문제입니다.

위 명령어를 입력하시고, y를 입력하시면 해결 되실겁니다!

 

npm 경로 문제

npm config get prefix
npm config set prefix "C:\Users\%USERNAME%\AppData\Roaming\npm"

Mac 특화 오류 해결

M1/M2 칩 호환성 문제

arch -x86_64 npm install -g @google/gemini-cli

 

Homebrew 충돌

brew unlink node
nvm use stable

---

성능 비교 및 선택 가이드

주요 AI CLI 도구 비교

특징	Gemini CLI	Claude Code	GitHub Copilot CLI
가격	무료	유료 ($20/월)	유료 ($10/월)
일일 요청 제한	1,000회	무제한	제한적
컨텍스트 윈도우	100만 토큰	20만 토큰	제한적
다국어 지원	우수	우수	보통
코드 생성	우수	최우수	우수
파일 시스템 접근	지원	지원	제한적
웹 검색	지원	미지원	미지원

사용 시나리오별 추천

개인 프로젝트: Gemini CLI (무료, 충분한 성능)

팀 협업: Claude Code (안정성, 무제한 사용)

Microsoft 생태계: GitHub Copilot CLI (깊은 통합)

---

실무 활용 사례

웹 개발 프로젝트

React 컴포넌트 생성

> 누수탐지업체를 운영중이다. 해당 업체를 소개하는 1장의 랜딩페이지를 만들어.

 

1. 위 gemini-cli 실제 테스트를 위해 폴더(gemini-test)를 하나 생성하고, 해당 디렉토리로 이동해주겠습니다.

1. gemini-cli 테스트를 위해 gemini-test디렉토리 생성 후 해당 디렉토리로 이동하는 화면

 

2. gemini 명령어 입력

2. gemini-test 디렉토리 이동 후 gemini 명령어 입력한 화면

 

3. 누수탐지업체의 1장의 기업소개 랜딩페이지를 만들어달라는 프롬프트 입력 시, gemini가 자동으로 작업 계획을 설명한다.

3. 누수탐지업체의 1장의 기업소개 랜딩페이지를 만들어달라는 프롬프트 입력 시 gemini가 작업 계획을 설명하는 화면

 

4. gemini가 알려준 작업계획 체크 후, 문제없으면 진행시키라고 명령을 하면

아래와 같이 중간중간 진행하면 되겠냐는 의미에 알림창들이 몇개 뜨는데, Yes, allow once에서 엔터를 하면 계속 진행 하게된다.

4. gemini-cli가 apply this change 물어보는 화면

 

5. 작업완료 후 gemini-test 디렉토리를 확인해보면 작업된 파일들이 들어있음을 확인 할 수 있다.

5. gemini-cli로 작업완료 후 gemini-test 디렉토리를 확인해보면 작업된 파일들이 들어있는 화면

 

6. gemini-cli로 누수탐지업체 소개 랜딩페이지 제작한 결과물과 후기

6. gemini-cli로 누수탐지업체 소개 랜딩페이지 제작 한 결과물

 

-> gemini-cli는 굉장히 빨리 생성해줘서(대략 40초 정도) 좋았고,

페이지의 품질은 조금 떨어지지만 흔히들 와꾸잡는다고 하는데 디자인 초안을 잡을때 다른 MCP들을 연결해서 사용하면 유용할 것 같습니다. 제일 좋은점은 가격인데 일일 1000회 무료로 이용가능해서 최고 장점인 것 같습니다.

 

-> 참고로 gemini cli 종료하실때는 콘트롤(ctrl)+C 두번 누르시면 터미널로 빠져나오실 수 있습니다.

 

API 연동 코드

> REST API 호출을 위한 axios 기반 서비스 클래스를 만들어줘
> 에러 처리와 재시도 로직을 포함해줘

데이터 분석

CSV 파일 처리

> @data.csv 이 파일을 분석해서 주요 통계를 요약해줘
> 데이터 시각화를 위한 Python 코드를 작성해줘

DevOps 자동화

배포 스크립트

> AWS ECS에 배포하는 스크립트를 작성해줘
> 롤백 기능을 포함해줘

 

모니터링 설정

> Prometheus와 Grafana 설정 파일을 생성해줘
> 주요 메트릭을 모니터링할 수 있도록 해줘

---

성능 최적화 팁

효율적인 프롬프트 작성

구체적인 요청

❌ "코드를 개선해줘"
✅ "이 함수의 시간 복잡도를 O(n²)에서 O(n log n)으로 개선해줘"

728x90

 

컨텍스트 제공

> @package.json @src/app.js 이 Express 앱의 보안을 강화해줘

메모리 활용

Gemini CLI는 작업 공간에서 진행하는 내용을 GEMINI.md 파일을 통해 기록합니다.

> /memory save "이 프로젝트는 React 기반의 전자상거래 플랫폼이다"
> /memory show

---

보안 고려사항

코드 학습 및 개인정보

무료 사용자는 코드를 학습에 사용하기 때문에 업무용 코드 작성 시 주의가 필요합니다.

 

보안 권장사항

• 민감한 API 키나 비밀번호 제외
• 회사 기밀 코드 업로드 금지
• 개인정보 포함 데이터 처리 시 주의

환경변수 관리

# .env 파일 생성
echo "GEMINI_API_KEY=your_key_here" >> .env
echo ".env" >> .gitignore

---

향후 업데이트 및 로드맵

예정된 기능

Gemini CLI는 지속적으로 발전하고 있으며, 매주 새로운 프리뷰 릴리스가 공개됩니다.

 

개발 중인 기능

• 향상된 MCP 서버 지원
• 더 많은 언어 모델 선택 옵션
• 성능 최적화
• VS Code 확장 기능 개선

커뮤니티 기여

기여 방법

• GitHub 레포지토리에서 이슈 리포트
• 기능 제안 및 버그 수정 PR
• 문서 개선 및 번역

---

마치며

Gemini CLI는 개발자의 생산성을 혁신적으로 향상시킬 수 있는 강력한 도구입니다.

무료로 제공되는 풍부한 기능과 Google의 최신 AI 기술을 터미널에서 바로 활용할 수 있다는 점에서 모든 개발자에게 필수적인 도구가 될 것으로 예상됩니다.

 

주요 장점 요약

• 완전 무료 사용 (일일 1,000회 제한)
• 강력한 Gemini 2.5 Pro 모델
• 100만 토큰 컨텍스트 윈도우
• 다양한 MCP 서버 연동 가능
• 오픈소스 기반 투명성

지금 바로 터미널을 열고 Gemini CLI를 설치하여 AI 기반 개발 환경의 새로운 가능성을 경험해보세요.

더 자세한 정보는 Gemini CLI 공식 문서를 참고하시기 바랍니다.

---

관련 링크

• Google AI Studio
• Node.js 공식 다운로드
• Gemini API 문서

---

같이 읽으면 좋은 글

Gemini CLI vs Claude CLI vs OpenAI CLI – 2025년 AI 명령줄 툴 완벽 비교 & 실사용 후기

Qwen3 Coder: 최신 AI 코딩 모델 특징, 성능 비교 및 실전 활용 가이드

Qoder 리뷰: 2주 무료 체험으로 경험중인 차세대 AI 코딩 플랫폼의 모든 것

Cursor AI Pro 정책 대변화! 2025년 6월 무제한 요청 시대가 열렸다

Task Master AI: 인공지능 기반 업무 자동화 도구의 실제 활용법과 생산성 혁신 사례

Claude Pro 주간 사용량 한도 및 Claude AI Weekly Limit 정책 완전정리