터미널 환경에서 인공지능 모델과 직접 상호작용할 수 있도록 돕는 도구인 Gemini CLI는 개발자가 별도의 웹 인터페이스를 거치지 않고 명령줄 인터페이스(CLI)에서 Gemini 모델에 프롬프트를 전송하고 응답을 확인할 수 있게 지원하는 오픈소스 AI 에이전트 도구입니다. Node.js 자바스크립트 런타임을 기반으로 구동되며, 구글의 AI 모델 API와 로컬 셸 환경을 유기적으로 이어주는 통로 역할을 담당합니다.
로컬 머신에서 Gemini CLI를 안정적으로 운영하려면 올바른 런타임 버전을 확보하고, 패키지 매니저(npm)를 통해 시스템 전역에 바이너리를 등록한 뒤, Google AI Studio에서 발급한 인증 키를 환경 변수로 정확히 연결해야 합니다. 설치 사전 준비 단계부터 환경 변수 주입, 실제 대화형 세션 시작 및 종료, 최신 버전 갱신까지 이어지는 표준 설정 과정을 순서대로 다룹니다.
Gemini CLI 로컬 구동을 위한 사전 요구 사양과 Node.js 점검
Gemini CLI를 로컬 시스템에 설치하여 원활하게 실행하기 위해서는 구글 공식 기술 문서에서 명시하는 최소 사양 요건을 반드시 충족해야 합니다. 가장 핵심적인 요구 사항은 Node.js 버전입니다. 로컬 환경에서 패키지를 전역 빌드하고 모듈을 실행하려면 Node.js 20.0.0 이상의 런타임 환경이 시스템에 설치되어 있어야 합니다.
시스템에 구버전 Node.js가 설정되어 있거나 런타임이 아예 존재하지 않는 상태에서 설치를 시도하면 패키지 설치 도중 구문 오류가 발생하거나 CLI 실행 바이너리가 비정상적으로 종료될 수 있습니다. 설치를 시작하기 전 운영체제의 터미널(macOS/Linux의 Bash 및 Zsh, Windows의 PowerShell 등)을 열고 현재 구동 중인 Node.js 버전을 확인하는 단계가 선행되어야 합니다.
# 1. 설치된 Node.js 버전 확인
node -v
# 2. npm 패키지 매니저 버전 확인
npm -v위 명령어를 실행했을 때 출력되는 결과가 v20.0.0 이상으로 표시되어야 설치 단계로 진입할 수 있습니다. 만약 버전 정보가 출력되지 않거나 v18 이하의 하위 버전이 표시된다면 공식 Node.js 배포처나 버전 관리 도구를 통해 20 버전 이상의 런타임을 먼저 설치한 후 다음 단계를 진행해야 합니다.
npm을 활용한 Gemini CLI 전역 설치 및 설치 상태 확인
Node.js 20 이상의 환경이 준비되었다면 npm(Node Package Manager)을 사용하여 시스템 전역에 Gemini CLI 패키지를 다운로드하고 실행 명령어를 등록합니다. 전역 설치 플래그(-g)를 부여하여 운영체제 내 어느 디렉터리에서나 gemini 명령어를 직접 호출할 수 있도록 설정합니다.
# Gemini CLI 전역 설치 명령어
npm install -g @google/gemini-cli이어서 패키지가 시스템 경로(PATH)에 올바르게 심볼릭 링크되고 정상 등록되었는지 검증하기 위해 다음과 같은 단계별 실행과 확인 작업을 거칩니다.
- 터미널을 열고
npm install -g @google/gemini-cli명령어를 입력한 뒤 엔터를 누릅니다. - 패키지 종속성 트리가 내려받아지고 전역 모듈 폴더에 등록되는 과정이 완료될 때까지 대기합니다.
- 설치가 완료된 후 터미널에
gemini --version을 입력하여 정상 설치 여부를 판정합니다.
정상 결과 확인법은 명확합니다. 터미널에 gemini --version을 입력했을 때 오류 메시지 대신 설치된 패키지의 버전 번호가 한 줄로 표시된다면 바이너리가 시스템 전역 경로에 성공적으로 안착된 것입니다.
대표적인 실패 원인과 해결 방법은 다음과 같습니다. macOS 또는 Linux 환경에서 EACCES: permission denied 오류가 발생하며 설치가 중단되는 경우가 있습니다. 이는 전역 패키지가 저장되는 시스템 디렉터리에 대한 쓰기 권한이 부족하여 발생합니다. 관리자 권한(sudo npm install -g @google/gemini-cli)을 사용하거나 Node.js 런타임 권한을 사용자 계정 소유로 설정하여 문제를 해결할 수 있습니다. command not found: gemini 오류가 출력된다면 npm의 전역 바이너리 저장 경로가 셸의 PATH 환경 변수에 누락되었는지 점검해야 합니다.
Google AI Studio API 키 발급 및 환경 변수 인증 설정
Gemini CLI를 로컬에서 구동하려면 구글의 Gemini 모델 서버와 통신할 수 있는 유효한 인증 수단이 필요합니다. 공식 문서에 따르면 Gemini CLI는 세 가지 인증 방식을 제공합니다. 웹 브라우저를 통한 Google 계정 로그인, Google AI Studio에서 생성한 API 키를 활용한 인증, 그리고 Google Cloud Vertex AI 연동 방식입니다. 개인 개발자가 로컬 터미널에서 가장 신속하고 간결하게 CLI 세션을 연결할 수 있는 공식 경로는 Google AI Studio API 키를 환경 변수에 등록하는 방식입니다.
인증 키를 연동하는 절차는 다음과 같습니다. 먼저 브라우저를 열고 Google AI Studio(aistudio.google.com/apikey)에 접속하여 새로운 API 키를 생성합니다. 키 문자열이 발급되면 터미널 세션에 환경 변수 GEMINI_API_KEY를 등록합니다.
# 1. Google AI Studio API 키를 환경 변수로 등록
export GEMINI_API_KEY="YOUR_API_KEY"
# 2. 등록된 환경 변수 값 확인 (선택 사항)
echo $GEMINI_API_KEY명령어의 "YOUR_API_KEY" 부분을 발급받은 실제 API 키 문자열로 대체하여 입력합니다. export 명령어로 등록한 환경 변수는 현재 열려 있는 터미널 세션 동안 유효합니다. 터미널 창을 닫은 뒤에도 영구적으로 설정을 유지하려면 사용 중인 셸의 설정 파일(예: ~/.bashrc 또는 ~/.zshrc)의 마지막 줄에 해당 export 구문을 추가해야 합니다.
이미 CLI 대화형 환경 내부로 진입한 상태라면 인터페이스 내에서 /auth 명령어를 입력하여 인증 선택 메뉴를 호출할 수 있으며, 이 메뉴에서 브라우저 기반 Google 계정 로그인이나 프로젝트 설정으로 전환하는 것도 가능합니다.
대화형 세션 시작과 프롬프트 실행 및 종료 방법
패키지 설치와 API 키 환경 변수 등록이 완료되면 즉시 Gemini CLI의 대화형 세션을 실행할 수 있습니다. 홈 폴더나 프로젝트 작업 디렉터리를 생성한 뒤 해당 위치에서 CLI를 호출하는 것이 권장됩니다. CLI는 현재 실행 중인 작업 폴더를 기준으로 로컬 컨텍스트를 파악하기 때문입니다.
# 프로젝트 디렉터리 생성 및 이동
mkdir gemini-cli-projects
cd gemini-cli-projects
# Gemini CLI 대화형 세션 시작
gemini터미널에서 gemini를 입력해 엔터를 치면 대화형 인터페이스가 구동됩니다. 처음 실행하는 환경에서는 터미널 화면에 사용할 테마를 선택하라는 안내가 나타날 수 있습니다. 기본 테마를 채택하거나 방향키를 사용하여 선호하는 색상 테마를 선택하면 대화형 프롬프트 대기 상태로 전환됩니다.
- 터미널에서
gemini명령어를 실행하여 대화형 세션 프롬프트를 엽니다. - 프롬프트 입력 창이 활성화되면 원하는 질의를 입력하고 엔터를 눌러 모델의 응답 스트림이 정상적으로 수신되는지 확인합니다.
- 세션에서 지원하는 명령어 목록과 단축키를 확인하려면 슬래시 명령어인
/help를 입력합니다. - 작업을 마치고 CLI 세션을 안전하게 종료하려면
/quit명령어를 입력하거나 키보드에서Ctrl-C키를 연속으로 두 번 누릅니다.
정상적으로 세션이 종료되면 터미널 화면에 해당 세션 동안 소모된 모델 사용량 및 세션 통계 메트릭이 정리되어 표시됩니다. 만약 API 키가 누락되었거나 잘못 입력된 상태에서 gemini를 실행하면 인증 방식 선택 화면이 나타나거나 API 통신 인증 오류가 반환되므로, 앞서 설정한 GEMINI_API_KEY 환경 변수가 현재 셸에 올바르게 적용되어 있는지 점검해야 합니다.
대화형 터미널을 열지 않고 단일 질의에 대한 결과만 터미널 표준 출력으로 즉시 반환받는 비대화형(non-interactive) 실행도 지원됩니다. 스크립트 작성이나 자동화 파이프라인에서 활용할 때는 -p 플래그를 결합하여 프롬프트를 전달합니다.
# 비대화형 단일 프롬프트 실행 예시
gemini -p "What is the weather today"Gemini CLI 최신 버전 업데이트 및 추가 실행 옵션
Gemini CLI 패키지는 새로운 기능 추가와 성능 개선을 위해 지속적으로 새 버전이 배포됩니다. 이미 시스템에 구버전 패키지가 설치되어 있는 상태에서 최신 안정화 버전으로 바이너리를 갱신하려면 npm의 전역 업데이트 명령어를 실행합니다.
# 전역 설치된 Gemini CLI 최신 버전 갱신
npm update -g @google/gemini-cli업데이트 명령어가 정상적으로 완료된 후 다시 gemini --version을 실행하여 판올림된 버전이 반영되었는지 확인합니다.
Gemini CLI를 기동할 때 모델 매개변수를 직접 지정하여 특정 모델로 세션을 시작할 수도 있습니다. -m 플래그를 사용하면 구동 시점에 원하는 모델 이름을 명시적으로 지정할 수 있습니다.
# 특정 모델을 지정하여 세션 실행
gemini -m "gemini-2.5-flash"
# CLI에서 지원하는 전체 명령줄 옵션 목록 확인
gemini --help지정된 모델 플래그와 함께 세션이 열리면 터미널 인터페이스 오른쪽 하단에 현재 로드된 모델 이름(예: gemini-2.5-flash)이 표시됩니다. 세션 실행 중 모델을 변경해야 할 때는 CLI 내부에서 /model 명령어를 입력하여 지원 모델 목록 대화상자를 띄우고 다른 모델로 전환할 수 있습니다. CLI에서 제공하는 전체 매개변수와 도움말 목록은 언제든지 gemini --help를 통해 터미널에서 즉시 조회할 수 있습니다.
