Gemini CLI 설치 방법: 구글 로그인·API 키 설정과 command not found 해결

Gemini CLI는 터미널에서 Gemini를 사용하는 오픈소스 도구다. 설치 없이 먼저 시험하려면 npx @google/gemini-cli, 계속 쓸 거라면 npm install -g @google/gemini-cli 또는 macOS/Linux의 brew install gemini-cli를 쓴다. 첫 실행에서 개인 사용자는 ‘Sign in with Google’을 선택할 수 있고, API 키 방식은 GEMINI_API_KEY 환경 변수에 키를 넣는다. gemini: command not found는 대부분 Node/npm 설치 또는 전역 실행 경로 문제다.

설치 전 Node.js 확인하기

npx와 npm 방식은 Node.js가 필요하다. 현재 설치 상태를 먼저 본다.

node --version
npm --version

둘 중 하나가 command not found라면 Gemini CLI를 반복 설치하지 말고 Node.js 공식 사이트나 운영체제의 패키지 관리자로 지원되는 Node.js를 먼저 설치한다. 요구되는 정확한 Node 버전은 Gemini CLI 공식 문서의 현재 Prerequisites를 확인한다. 버전 숫자는 시간이 지나며 바뀔 수 있으므로 오래된 블로그의 값을 고정해서 따르지 않는 편이 안전하다.

설치 없이 npx로 먼저 실행하기

공식 저장소가 안내하는 가장 빠른 체험 방법이다.

npx @google/gemini-cli

패키지를 전역 설치하지 않고 실행하므로 ‘한 번 써 보고 결정’할 때 적합하다. 여기서 정상 실행되는데 gemini만 안 된다면 Gemini 서비스나 로그인 문제가 아니라 전역 설치 또는 PATH 문제로 범위를 좁힐 수 있다.

npm 또는 Homebrew로 설치하기

macOS, Windows, Linux에서 npm 전역 설치는 다음과 같다.

npm install -g @google/gemini-cli
gemini

macOS/Linux에서 Homebrew를 이미 관리 도구로 사용한다면 공식 저장소에 다음 방법도 안내되어 있다.

brew install gemini-cli
gemini

macOS에는 MacPorts 방법도 공식 저장소에 실려 있지만, 한 컴퓨터에서 npm·Homebrew·MacPorts 설치를 모두 겹치지는 말자. 업데이트할 때 어느 패키지가 실행되는지 혼란이 생긴다.

Windows에서는 PowerShell에서 Node.js와 npm이 정상인지 확인한 뒤 npm 명령을 실행한다. 설치 후에는 PowerShell과 IDE 내장 터미널을 완전히 닫고 새 창을 연다.

구글 계정으로 로그인하기

gemini를 실행하면 인증 방식을 고르는 화면이 나온다. 개인 사용자가 브라우저 로그인 흐름을 쓰려면 Sign in with Google을 선택하고 브라우저의 안내를 따른다. 공식 저장소는 이 방식이 API 키 관리 없이 시작하는 경로라고 설명한다.

gemini

브라우저가 열리지 않거나 원격 SSH 환경이라면 터미널에 표시되는 URL과 안내를 따른다. 회사 Google Workspace 계정은 관리 정책이나 프로젝트 요구 사항이 개인 계정과 다를 수 있다. 로그인 버튼이 보인다는 사실만으로 조직 사용 권한이 보장되는 것은 아니다.

무료 요청 한도와 제공 모델은 변경될 수 있다. 숫자가 의사결정에 중요하다면 실행 당일 공식 Gemini CLI 인증 문서와 Google의 현재 할당량 페이지를 확인한다. 설치 성공 여부를 무료 한도 숫자와 섞어서 판단할 필요는 없다.

Gemini API 키로 인증하기

Google AI Studio에서 발급한 Gemini API 키를 쓸 때는 공식 저장소 예제처럼 GEMINI_API_KEY를 설정한 뒤 실행한다.

macOS/Linux/WSL의 현재 터미널 세션:

export GEMINI_API_KEY="발급받은_키"
gemini

Windows PowerShell의 현재 세션:

$env:GEMINI_API_KEY="발급받은_키"
gemini

키를 명령 기록, Git 저장소, 블로그 캡처에 남기지 않는다. .env를 쓴다면 .gitignore에 포함하고, 셸 설정 파일에 평문으로 넣기 전 해당 컴퓨터의 계정·백업·공유 범위를 생각해야 한다. 노출이 의심되면 숨기려 하지 말고 키를 폐기하고 새로 발급한다.

구글 로그인과 API 키는 ‘둘 다 반드시 해야 하는 단계’가 아니다. 사용하는 계정 유형과 배포 환경에 맞는 인증 경로를 하나 선택한다. CI나 원격 자동화에서는 브라우저 로그인이 부적합할 수 있으므로 공식 Authentication 문서에서 해당 환경에 맞는 방식을 확인한다.

gemini: command not found 해결 순서

1. npx는 되는지 확인한다

npx @google/gemini-cli

이 명령이 되면 Node.js와 패키지 접근은 대체로 동작하며, 전역 gemini 명령의 설치 위치가 PATH에 없는 가능성이 크다. npx도 안 되면 먼저 node --version, npm --version부터 본다.

2. 전역 설치 여부와 경로를 확인한다

npm list -g --depth=0
npm prefix -g

목록에 @google/gemini-cli가 있는지 확인한다. npm prefix -g는 전역 설치 기준 위치를 보여준다. 그 위치의 실행 파일 디렉터리가 현재 PATH에 포함되어야 한다. 인터넷에서 찾은 임의 경로를 그대로 추가하지 말고 자신의 명령 출력으로 경로를 판단한다.

macOS/Linux/WSL:

command -v gemini
printf '%s
' "$PATH"

Windows PowerShell:

Get-Command gemini -ErrorAction SilentlyContinue
where.exe gemini
$env:Path

3. 새 터미널을 연다

설치 후 PATH가 갱신되어도 기존 셸은 이전 값을 유지할 수 있다. 터미널과 VS Code 같은 IDE의 내장 터미널을 모두 닫고 다시 연다. Windows에서는 Node 설치 후 재로그인이 필요한 경우도 있다.

4. 설치 방법 중복을 정리한다

which -a gemini 또는 PowerShell의 Get-Command gemini -All로 여러 실행 파일이 잡히는지 확인한다. npm과 Homebrew 버전이 동시에 있으면 오래된 쪽이 먼저 실행될 수 있다. 자신이 업데이트할 한 가지 설치 방식만 남기는 것이 좋다.

5. 권한 문제를 PATH 문제로 고치지 않는다

EACCES 같은 npm 권한 오류가 났다면 무조건 sudo npm install -g로 덮지 말자. Node 버전 관리자 사용 또는 npm 공식 문서의 전역 권한 해결 방법을 따른다. command not found와 설치 중 권한 오류는 서로 다른 단계의 문제다.

정상 설치 확인

새 터미널에서 다음 세 가지가 되면 기본 설치와 인증을 분리해서 확인할 수 있다.

gemini --version
gemini

첫째, --version이 실행되면 PATH가 해결됐다. 둘째, 인증 선택 화면이나 프롬프트가 나오면 CLI가 시작됐다. 셋째, 로그인 또는 API 키 설정 후 짧은 질문에 응답하면 인증과 모델 호출까지 동작한다.

문제가 생기면 설치→PATH→인증→할당량 순으로 확인하자. 처음부터 API 키를 다시 만들거나 패키지를 여러 방식으로 재설치하면 원인이 더 불분명해진다.

출처: Gemini CLI 공식 저장소, Gemini CLI Installation, Gemini CLI Authentication, Google AI Studio API Key, npm folders