Gemini CLI 처음 설치하고 WSL에서 실행해보기

Claude Code나 Codex CLI를 한 번 써봤다면, 이제 “Gemini도 터미널에서 바로 쓸 수 있나?”라는 생각이 들 수 있습니다. Google의 Gemini CLI는 브라우저에서 Gemini를 여는 대신, 작업 중인 프로젝트 폴더 안에서 gemini 명령으로 AI에게 코드를 읽히고 설명을 부탁할 수 있는 도구입니다.

다만 이런 도구는 설치 명령 한 줄보다 내 WSL 환경에서 명령이 어디에 설치되고, PATH가 어떻게 잡히는지가 더 중요합니다. 글 작성 시점에 실제로 WSL 터미널에서 Node/npm 버전, npm 패키지 버전, 별도 임시 설치 경로에서의 실행 여부를 확인했습니다. 아래 캡처는 그 확인 과정의 예시입니다.

먼저 확인한 환경

이 글의 확인 환경은 다음과 같습니다.

항목	확인값
터미널	WSL 계열 리눅스 터미널
Node.js	v22.23.1
npm	10.9.8
확인한 Gemini CLI 패키지 버전	0.49.0

설치 글을 볼 때는 항상 “내 환경과 글쓴이의 환경이 같은가?”를 먼저 봐야 합니다. 특히 Node.js와 npm은 버전 매니저, apt, 직접 설치 방식에 따라 전역 설치 위치가 달라질 수 있습니다.

node -v
npm -v
npm view @google/gemini-cli version

위 세 명령으로 최소한 다음을 알 수 있습니다.

• Node.js가 WSL 안에서 정상 실행되는지
• npm 명령이 현재 셸에서 잡히는지
• 현재 npm registry에 올라온 Gemini CLI 버전이 무엇인지

여기서 node나 npm이 command not found로 나온다면 Gemini CLI 설치부터 진행하지 말고, Node.js와 버전 관리 도구 글을 먼저 보고 Node 환경을 정리하는 편이 좋습니다.

Gemini CLI가 어떤 도구인가

Gemini CLI는 Google Gemini를 터미널에서 사용할 수 있게 해주는 오픈소스 AI 에이전트입니다. 단순히 질문에 답하는 챗봇이라기보다, 현재 폴더의 파일을 읽고, 코드 구조를 설명하고, 필요한 경우 수정 방향을 제안하는 개발 보조 도구에 가깝습니다.

비슷한 계열의 도구로는 Claude Code, OpenAI Codex CLI가 있습니다. 셋 모두 “작업 폴더 안에서 실행한다”는 점은 비슷하지만, 사용하는 계정, 모델, 설정 방식, 권한 확인 흐름은 조금씩 다릅니다. 그래서 처음에는 여러 도구를 한꺼번에 자동화하기보다, 하나씩 설치하고 기본 동작을 확인하는 편이 안전합니다.

WSL에서 설치하기

Gemini CLI의 표준 설치 흐름은 npm을 사용합니다. WSL 터미널에서 아래 명령을 실행합니다.

npm install -g @google/gemini-cli

여기서 -g는 전역 설치(global)를 뜻합니다. 특정 프로젝트 안에서만 쓰는 라이브러리가 아니라, 터미널 어디서나 gemini 명령을 실행할 수 있게 설치하는 방식입니다.

다만 전역 설치는 환경마다 결과가 다를 수 있습니다. 예를 들어 npm 전역 prefix가 /usr처럼 시스템 경로를 가리키면 권한 문제를 만날 수 있습니다. 그럴 때는 sudo를 붙여 억지로 밀어붙이기보다, Node를 nvm 같은 버전 매니저로 관리하는 쪽이 나중에 덜 꼬입니다.

설치가 제대로 되는지 별도 경로에서 검증해보기

전역 설치 전에 패키지가 실제로 내려받아지고 실행 파일이 만들어지는지 확인하고 싶다면, 임시 경로에 설치해 보는 방법도 있습니다. 글 작성 시점에는 별도 prefix를 지정해 설치한 뒤, 생성된 실행 파일로 버전을 확인했습니다.

npm install --prefix /tmp/gemini-cli-check @google/gemini-cli
/tmp/gemini-cli-check/node_modules/.bin/gemini --version

이 방식은 실제 사용을 위한 설치라기보다 패키지 자체가 정상 설치되는지 확인하는 검증용입니다. 평소 사용할 때는 앞의 전역 설치 명령을 쓰는 편이 간단합니다.

전역 설치 후에는 다음 명령으로 확인합니다.

gemini --version

버전 숫자가 출력되면 설치가 정상적으로 된 것입니다.

gemini 명령을 못 찾을 때

설치 후 가장 흔하게 만나는 상황은 이것입니다.

gemini: command not found

이 메시지를 보면 설치가 실패했다고 생각하기 쉽지만, 실제로는 설치 위치가 현재 PATH에 잡히지 않은 문제일 때가 많습니다. 먼저 아래 명령으로 확인합니다.

npm prefix -g
command -v gemini

확인 순서는 이렇게 잡으면 됩니다.

1. npm prefix -g로 npm 전역 설치 기준 경로를 확인합니다.
2. command -v gemini로 현재 셸에서 gemini 명령이 잡히는지 확인합니다.
3. 전역 prefix가 /usr처럼 시스템 경로라면 권한 문제 가능성을 봅니다.
4. nvm을 쓴다면 새 터미널에서 nvm 초기화가 제대로 되는지 확인합니다.
5. 설치 직후라면 터미널을 닫고 다시 열어 PATH가 갱신되는지 확인합니다.

입문 단계에서는 “안 되면 sudo”로 가기보다, 어디에 설치됐고 현재 셸이 그 위치를 보고 있는지를 먼저 확인하는 편이 안전합니다.

작업 폴더에서 첫 실행하기

설치가 끝났다면 아무 폴더에서나 실행하지 말고, 도움을 받고 싶은 프로젝트 폴더 안에서 실행합니다.

예를 들어 연습용 프로젝트가 ~/projects/my-app에 있다면 이렇게 이동합니다.

cd ~/projects/my-app
gemini

처음 실행하면 대화형 화면이 열리고, 인증 방식을 묻는 안내가 나옵니다. 공식 빠른 시작 문서는 가장 간단한 방식으로 Login with Google을 안내합니다. 화면에서 Google 로그인 방식을 선택하면 브라우저 인증 흐름으로 이어집니다.

계정 이름, 인증 토큰, API 키가 보이는 화면은 블로그에 그대로 올리지 않는 편이 좋습니다. 캡처가 필요하다면 계정명과 토큰은 반드시 가리고 올리세요.

첫 질문은 파일 수정이 아니라 읽기부터

Gemini CLI를 처음 켰다면 바로 “이 프로젝트를 고쳐줘”라고 하기보다, 읽기 중심 요청부터 시작하는 편이 좋습니다.

이 프로젝트에서 먼저 읽어야 할 파일과 실행 방법을 찾아서 요약해줘.

또는 다음처럼 범위를 좁혀 요청할 수 있습니다.

package.json과 README를 보고 이 프로젝트의 실행 방법만 정리해줘.

이렇게 시작하면 Gemini CLI가 현재 폴더를 어떻게 이해하는지 확인할 수 있습니다. 파일 수정은 그다음 단계입니다.

파일 수정 전 확인할 것

AI CLI 도구가 파일을 고치겠다고 제안할 때는 바로 승인하기보다, 어떤 파일을 어떻게 바꾸는지 확인해야 합니다. 특히 아래 파일은 작은 변경도 영향을 크게 줄 수 있습니다.

• .env, .env.local 같은 환경변수 파일
• 배포 설정 파일
• 인증·토큰 관련 파일
• package.json, lockfile
• GitHub Actions 같은 자동화 설정

입문 단계에서는 자동 승인이나 무제한 실행 옵션을 켜기보다, 한 번씩 확인하며 진행하는 기본 흐름에 익숙해지는 것을 권합니다.

Google 로그인과 API 키 방식

Gemini CLI는 여러 인증 방식을 지원합니다. 공식 저장소에는 Google 계정 로그인, Gemini API 키, Vertex AI 같은 선택지가 소개되어 있습니다. 입문자라면 먼저 Google 로그인 방식으로 시작하는 편이 단순합니다.

API 키를 쓰는 방식은 자동화나 별도 모델 선택에는 유용할 수 있지만, 키 관리가 필요합니다. API 키를 터미널에 붙여넣거나 설정 파일에 저장할 때는 절대 공개 저장소에 올라가지 않도록 조심해야 합니다.

Claude Code·Codex CLI와 같이 쓸 때

티발자랩의 흐름대로라면 이미 Claude Code 처음 설치하고 실행해보기나 WSL에 OpenAI Codex CLI 설치하기를 봤을 수 있습니다. Gemini CLI까지 설치하면 한 WSL 환경 안에 여러 AI 코딩 도구가 공존하게 됩니다.

이때 중요한 것은 “어떤 도구가 더 좋다”를 빨리 결론내리는 것이 아니라, 같은 프로젝트에서 다음 기준으로 비교해 보는 것입니다.

• 설치와 로그인 과정이 얼마나 단순한가
• 현재 프로젝트 구조를 얼마나 잘 설명하는가
• 파일을 수정하기 전에 변경 의도를 명확히 보여주는가
• 긴 로그나 에러 메시지를 읽고 원인을 잘 좁혀 주는가
• 내가 쓰는 작업 방식과 비용·한도가 맞는가

특히 무료 사용량이나 모델 정책은 시간이 지나며 바뀔 수 있습니다. 검색 결과나 예전 블로그 글만 믿기보다 공식 문서에서 최신 기준을 확인하는 습관이 필요합니다.

초보자가 자주 막히는 부분

• npm이 없는 상태에서 설치 명령부터 실행 — 먼저 node -v, npm -v로 준비 상태를 확인하세요.
• 윈도우 PowerShell과 WSL 터미널을 섞음 — 이 글의 명령은 WSL 우분투 터미널 기준입니다. 어느 터미널에서 실행 중인지 확인하세요.
• 설치 후 gemini 명령을 못 찾음 — 터미널을 새로 열고, npm 전역 설치 경로와 PATH를 확인합니다.
• 전역 prefix가 /usr로 잡힘 — 권한 문제가 날 수 있으니 Node 설치 방식을 점검합니다.
• 엉뚱한 폴더에서 실행 — 작업하려는 프로젝트 폴더로 cd 한 뒤 실행하세요.
• 처음부터 파일 수정을 맡김 — 첫 사용은 프로젝트 설명, 실행 방법 찾기, 에러 로그 분석처럼 읽기 중심 작업부터 시작하는 편이 안전합니다.
• API 키를 공개 저장소에 커밋 — API 키 방식으로 인증한다면 .env, 설정 파일, Git 추적 여부를 반드시 확인하세요.

출처

이 글은 아래 공식 자료를 기준으로 설치 명령과 기본 흐름을 확인했습니다. Gemini CLI는 릴리스가 빠른 도구이므로, 실제 설치 전에는 최신 문서를 한 번 더 확인하는 것을 권합니다.

• Gemini CLI 공식 빠른 시작 문서
• google-gemini/gemini-cli — GitHub 저장소
• @google/gemini-cli — npm 패키지

정리

WSL에서 Gemini CLI를 설치하는 핵심은 Node.js와 npm 확인 → 패키지 버전 확인 → 설치 → gemini --version 확인 → 작업 폴더에서 첫 실행입니다.

설치 명령 한 줄만 보면 쉬워 보이지만, 실제로는 PATH와 전역 설치 경로에서 막히는 경우가 많습니다. 그래서 설치가 안 된다고 바로 단정하지 말고, 현재 터미널이 어떤 Node/npm을 보고 있는지, gemini 실행 파일이 PATH에 잡히는지부터 차분히 확인해 보세요.