1. Intro
이 가이드는 Gemini-CLI를 로컬 환경에서 실행하기 위한 설정 방법을 다룹니다. Node.js 22 설치부터 간단한 사용법까지의 과정을 안내합니다.
1.1 Gemini-CLI 개요
Gemini-CLI는 개발자가 터미널 환경을 벗어나지 않고도 Google의 강력한 Gemini AI 모델을 직접 활용할 수 있도록 돕는 오픈소스 명령줄 인터페이스(CLI) 도구입니다. 코딩, 디버깅, 콘텐츠 생성, 복잡한 문제 해결 등 다양한 작업을 자연어 명령으로 처리하여 개발자의 생산성을 획기적으로 높여줍니다.
핵심 기능은 다음과 같습니다.
•
코드 이해 및 생성: 로컬 파일 시스템의 코드를 읽고, 수정하며, 새로운 코드를 생성할 수 있습니다.
•
자연어 명령 실행: "버그 수정해 줘", "테스트 코드 작성해 줘"와 같은 자연어 명령을 이해하고 실행합니다.
•
다양한 작업 지원: 코딩 외에도 아이디어 구상, 리서치, 작업 관리 등 광범위한 업무에 활용 가능합니다.
•
무료 사용: 개인 Google 계정으로 로그인하면 Gemini 2.5 Pro 모델을 분당 60회, 하루 1,000회까지 무료로 사용할 수 있습니다.
1.2 사전 준비
Gemini-CLI는 Google 계정으로 로그인하여 사용할 수도 있지만, API 키를 사용하면 더 안정적으로 서비스에 접근하거나 유료 플랜을 통해 더 많은 요청을 처리할 수 있습니다.
API Key 생성
1.
2.
API 키 생성 동의 : 서비스 약관 등이 나타나면 동의하고 계속 진행합니다.
3.
'Get API key' 클릭 : 좌측 메뉴나 메인 화면에서 'Get API key' (API 키 받기) 버튼을 찾아서 클릭합니다.
4.
새 프로젝트에서 API 키 생성 : '+ Create API key in new project' (새 프로젝트에서 API 키 생성) 버튼을 클릭하면 새로운 API 키가 생성됩니다.
5.
API 키 복사 및 보관 : 생성된 API 키 문자열을 복사하여 안전한 곳에 보관합니다. 이 키는 외부에 노출되지 않도록 주의해야 합니다.
Project ID 확인
1.
API Key 생성 : 위의 카테고리인 API Key 생성 과정을 마쳐야 합니다.
2.
1.3 환경설정
Terminal을 키도 유저 최상단 경로에 .env 파일을 생성합니다. 생성된 파일 내에 아래와 같은 정보를 입력해줍니다.
# ~/.env
GEMINI_MODEL="gemini-2.5-flash"# 혹은 gemini-2.5-pro 원하는 모델 입력
GEMINI_API_KEY="AIz....XY"# 확인된 API Key 입력
GOOGLE_CLOUD_PROJECT="gen-lang-....87"# 확인된 구글 클라우드 Project ID 입력
Shell
복사
2. Gemini-CLI 로컬 환경 설정
Gemini-CLI를 실행하려면 Node.js 18 버전 이상이 필요합니다. 이미 설치되어 있다면 이 단계를 건너뛰셔도 됩니다.
2.1. nvm
•
Terminal 혹은 iTerm을 실행합니다.
•
Terminal에 아래의 command를 입력하여 nvm을 설치합니다.
◦
nvm의 경우 최신 버전으로 설치하는 것을 권장드립니다.
◦
아래의 버전은 v0.39.7 설치 명령어 입니다.
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
Shell
복사
•
(Optional) 설정 파일 확인을 위해 아래의 내용을 따라해볼 수 있습니다.
nano나 vi 같은 텍스트 편집기로 해당 파일을 열어 NVM 관련 내용이 추가되었는지 확인할 수 있습니다.
# zsh 사용자의 경우:
nano ~/.zshrc
# bash 사용자의 경우:
nano ~/.bashrc
Shell
복사
파일 맨 아래에 다음과 유사한 내용이 추가되어 있을 것입니다.
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"# This loads nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"# This loads nvm bash_completion
Shell
복사
•
설치된 nvm을 터미널에 반영하기 위해 터미널을 재시작하거나 아래의 명령어를 실행합니다.
# zsh 사용자의 경우:
source ~/.zshrc
# bash 사용자의 경우:
source ~/.bashrc
Shell
복사
2.2. Node.js 22 설치
LTS(Long Term Support) 버전 다운로드: 일반적으로 안정적인 LTS 버전을 권장합니다. 현재(2025년 7월 기준) Node.js 22 LTS 버전을 다운로드하여 설치합니다. 운영체제에 맞는 설치 파일을 선택하세요 (Windows Installer, macOS Installer, Linux binaries 등)
방법 1. 공식 웹 사이트 접속하여 설치하기
1.
2.
설치 진행: 다운로드한 설치 파일을 실행하고, 설치 마법사의 지시에 따라 설치를 완료합니다. 특별한 설정이 필요하지 않다면 기본 설정을 그대로 사용해도 좋습니다.
3.
설치 확인: 터미널(명령 프롬프트 또는 PowerShell)을 열고 다음 명령어를 입력하여 Node.js와 npm(Node Package Manager)이 제대로 설치되었는지 확인합니다.
방법 2. Terminal 명령어 입력
만약 위의 nvm 설치 과정을 마쳤다면, nvm으로 node.js 22 버전을 설치할 수 있습니다.
# node.js 22 버전 설치
nvm install 22
# node.js 22 버전 사용
nvm use 22
Shell
복사
설치가 완료됐는지 확인하려면 아래의 명령어 둘 중 하나로 확인이 가능합니다.
node -v
npm -v
Shell
복사
3. Gemini-CLI
3.1. Gemini-CLI 설치
node.js 설치 과정을 모두 마쳤다는 가정하에 아래의 과정을 실행해주어야 합니다.
# Gemini-CLI를 어떤 경로에서도 실행 되도록 Global 설치
npm install -g @google/gemini-cli
Shell
복사
3.2. Gemini-CLI 인증
Gemini 실행
먼저 Gemini를 실행합니다. 실행을 위해 터미널에서 원하는 위치(경로)에서 gemini 를 입력합니다. 입력 후 아래와 같이 실행한 내용이 나타납니다.
위의 화면에서 화면 테마를 선택해주고, 인증을 요구하거나 console에 /auth라는 명령어를 입력하면 다음과 같은 화면이 나타납니다.
Gemini 인증 - Login with Google
Login with Google을 선택하여 로그인하고자 할 경우, 선택하게 되면, 로그인 된 Chrome (혹은 다른 인터넷 브라우저)가 켜지면서 Google 계정으로 로그인하라는 화면이 나타납니다. 이때 원하는 계정으로 로그인하게 되면 아래와 같이 인증됨을 알 수 있습니다.
•
사용량
◦
@7/18/2025 기준으로 Gemini 2.5 Flash/Pro 모델 기준으로 분당 60회 요청(RPM, Requests Per Minute)으로 제한되고 1일 1,000회로 제한됩니다.
◦
이 용량은 개발, 학습, 프로토타이핑 목적에는 충분하지만, 상용 서비스에 적용하기에는 부족할 수 있습니다.
◦
Gemini 인증 - Use Gemini API Key
“1.2 사전 준비”에서 입력해둔 API Key를 설정해두었으면, 별다른 인터렉션 없이 바로 사용이 가능합니다.
•
사용량
◦
Gemini 2.5 Flash/Pro 모델 기준으로 1일 최대 100개의 요청을 보낼 수 있습니다.
◦
API 키 방식 자체는 사용량에 영향을 주지 않으며, 해당 키가 연결된 구글 프로젝트의 등급에 따라 사용량이 결정됩니다.
이외의 설정의 경우 추천하는 방법을 따라하면 됩니다.
Gemini 인증 - Vertex AI
유료이므로 넘어가도록 하겠습니다.
3.3. Gemini-CLI 사용하기
Gemini-CLI 내에 내장된 명령어는 아래와 같습니다. 적절한 명령어를 이용하여 원하는 작업을 할 수 있습니다.
파일/경로 선택하여 명령해보기
•
요청 예시
Gemini-CLI를 실행한 경로에서 HTMX라는 디렉토리가 있습니다. 이 디렉토리 내에 있는 파일의 구조를 tree 구조로 설명해달라는 명령을 하기 위해 @HTMX 라고 파일 혹은 경로를 지정해주고, 뒤에 명령을 입력합니다.
@HTMX 의 경로에 대해 tree 구조로 설명해줘.
Plain Text
복사
•
응답 예시
╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✔ ReadManyFiles Will attempt to read and concatenate files using patterns: `HTMX/**` (within target directory: `/Users/0x0w1/Docu │
│ │
│ ### ReadManyFiles Result (Target Dir: `/Users/0x0w1/Documents/Personals`) │
│ │
│ Successfully read and concatenated content from **1 file(s)**. │
│ │
│ **Processed Files:** │
│ - `HTMX/index.html` │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
✦ /Users/0x0w1/Documents/Personals/HTMX/
└───index.html
Plain Text
복사
내장된 명령어 목록
•
명령어 목록
◦
/help: 모든 명령어랑 간단한 설명 보여줌.
•
인증 및 계정 관리
◦
/auth: 구글 계정 인증 관리함.
▪
login: 로그인함.
▪
logout: 로그아웃함.
▪
status: 지금 로그인 상태 확인해줌.
•
메모리 및 설정 관리
◦
/memory: Gemini 장기 기억(사용자 정보) 관리함.
▪
list: 저장된 기억 다 보여줌.
▪
clear: 기억 다 지워줌.
◦
/config: CLI 설정 관리함.
▪
list: 설정 키랑 값 다 표시해줌.
▪
get : 특정 설정 값 확인해줌.
▪
set : 특정 설정 값 바꿔줌.
▪
reset: 모든 설정 기본값으로 돌려놓음.
•
유틸리티 및 기타 기능
◦
/bug: 버그 신고 시작함.
◦
/feedback: 피드백 제출함.
◦
/clear: 터미널 화면 지워줌.
◦
/history: 이 세션에서 쓴 명령어 기록 보여줌.
◦
/retry: 마지막으로 실패한 명령어 다시 시도함.
◦
/exit 또는 /quit: Gemini-CLI 세션 끝냄.
◦
/theme: CLI 색깔 테마 바꿔줌.
◦
/workspace: 작업 디렉토리 정보 보여주거나 바꿔줌.
◦
/mode: 도구 사용 확인 모드(자동/수동) 전환함.
◦
/log: CLI 로그 확인해줌.
◦
/share: 이 세션 공유 링크 만들어줌.
◦
/undo: 마지막 작업 취소함.
◦
/redo: 취소했던 작업 다시 실행함.