이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다.
Gemini CLI를 설치하고 프로젝트 루트에 GEMINI.md를 두면, 매번 “npm을 써라”, “테스트부터 실행해라” 같은 규칙을 다시 적지 않아도 된다. 이번에는 설치에서 끝내지 않고, 작은 샘플 저장소에 규칙 파일을 만들고 실제로 불러왔는지 확인하는 데까지 해본다.
공식 설치 문서 기준 권장 환경은 macOS 15 이상, Windows 11 24H2 이상, Ubuntu 20.04 이상이며 Node.js 20.0.0 이상, Bash·Zsh·PowerShell, 인터넷 연결이 필요하다. 아래 명령은 macOS·Linux의 Bash/Zsh에서 실행한다. Windows에서는 WSL을 쓰거나 PowerShell 문법에 맞게 바꿔야 한다.
개인 Google 계정으로 로그인하는 무료 경로가 있다. 요청 한도와 데이터 처리 조건은 인증 방식에 따라 달라지므로 시작 전 공식 요금·쿼터 안내를 확인하는 편이 안전하다. 유료 구독이나 Google Cloud 프로젝트는 개인 계정의 기본 로그인에는 필수가 아니지만, 회사·학교·Workspace 계정은 Cloud 프로젝트가 필요할 수 있다.
Gemini CLI 설치 전 버전 확인
터미널에서 먼저 Node.js와 npm 버전을 확인한다.
입력
node --version
npm --version출력 예시(버전 번호는 환경마다 다름)
v22.18.0
10.9.3출력의 의미
첫 줄의 주 버전이 20 이상이면 현재 Gemini CLI 설치 요구 사항을 만족한다. 두 번째 줄은 함께 설치된 npm 버전이다. 이 명령은 시스템을 바꾸지 않고 버전만 읽는다.
이제 안정 채널의 최신 패키지를 전역 설치한다. latest를 생략해도 안정 채널이지만, 여기서는 의도를 분명히 적었다.
입력
npm install -g @google/gemini-cli@latest출력 예시(패키지 수와 시간은 달라짐)
added 546 packages in 24s출력의 의미
added ... packages 뒤에 npm error 없이 셸 프롬프트가 돌아오면 설치가 끝난 것이다. 전역 npm 실행 경로에 gemini 명령이 추가된다. 안정판은 주 단위로 갱신될 수 있으므로 버전 숫자는 고정하지 않는다.
설치된 명령을 확인한다.
입력
gemini --version출력 예시(공식 릴리스 중 한 버전 예시)
0.44.0출력의 의미
버전 한 줄이 나오면 셸이 실행 파일을 찾았다는 뜻이다. 실제 숫자는 설치 시점의 안정판에 따라 달라진다.
Google 계정으로 한 번 로그인하기
로컬 PC에서 가장 간단한 인증은 브라우저를 여는 Google 로그인이다. API 키를 셸 기록이나 글 속에 넣을 필요가 없다.
입력
gemini출력 예시(공식 문서에 나온 선택지이며 표현은 버전에 따라 달라질 수 있음)
How would you like to authenticate for this project?
1. Sign in with Google
2. Use Gemini API key
3. Vertex AI출력의 의미
개인 계정이라면 Sign in with Google을 선택하고 브라우저에서 승인을 마친다. 자격 증명은 이후 세션을 위해 로컬에 캐시된다. 회사나 학교 계정에서 프로젝트 입력을 요구하면 오류가 아니라 계정 유형의 차이일 수 있다. 정확한 분기는 공식 인증 안내에 정리돼 있다.
로그인 뒤 대화 화면이 나타나면 /quit를 입력해 일단 빠져나온다. 여기까지는 설치이고, 이제 프로젝트 규칙을 붙인다.
GEMINI.md로 프로젝트 규칙 고정하기
예제 폴더를 만들고 Git 저장소로 초기화한다. GEMINI.md의 프로젝트 경계를 명확히 보여주기 위해 git init도 함께 실행한다.
입력
mkdir -p gemini-context-demo
cd gemini-context-demo
git init
printf '%s\n' '# Project rules' '- Use npm only.' '- Run tests before changing code.' > GEMINI.md출력 예시(경로와 기본 브랜치 안내는 환경마다 다름)
Initialized empty Git repository in /home/user/gemini-context-demo/.git/출력의 의미
Initialized empty Git repository가 저장소 생성을 확인한다. 마지막 명령은 현재 폴더에 세 줄짜리 GEMINI.md를 새로 만든다. 같은 이름의 파일이 이미 있다면 덮어쓰므로, 기존 프로젝트에서는 먼저 test -e GEMINI.md && echo exists로 확인해야 한다.
Gemini CLI는 전역 ~/.gemini/GEMINI.md, 작업공간과 상위 폴더의 파일, 필요할 때 발견한 하위 폴더의 파일을 계층적으로 읽는다. 자세한 순서는 공식 GEMINI.md 문서에서 확인할 수 있다. 모든 프로젝트에 공통인 취향은 전역 파일에, 저장소 고유 규칙은 프로젝트 루트에 두는 편이 관리하기 쉽다.
파일이 제대로 생겼는지 먼저 셸에서 확인한다.
입력
cat GEMINI.md출력 예시
# Project rules
- Use npm only.
- Run tests before changing code.출력의 의미
세 줄이 그대로 보이면 현재 작업 디렉터리에 규칙 파일이 있다. 아직 모델이 읽었다는 뜻은 아니므로 다음 단계에서 메모리 목록을 확인한다.
Gemini CLI를 다시 열고 내장 명령을 입력한다.
입력
$ gemini
> /memory list
> /memory show출력 예시(경로 표시는 환경에 따라 달라짐)
Loaded context files:
/home/user/gemini-context-demo/GEMINI.md
# Project rules
- Use npm only.
- Run tests before changing code.출력의 의미
/memory list 결과에 현재 프로젝트의 GEMINI.md 경로가 있고, /memory show에 두 규칙이 보이면 로딩이 끝난 것이다. 실행 중 파일을 수정했다면 /memory refresh로 다시 읽을 수 있다. 이 명령들의 현재 이름은 공식 CLI 명령 참고서에서도 확인된다.
예전에는 패키지 설치 권한 문제가 생기면 시스템 설정을 바로 바꾸는 경우가 많았다. 이 블로그의 pip externally-managed-environment 오류 기록처럼 설치 도구가 시스템 영역을 보호하는 경우도 있으니, npm에서도 무조건 sudo를 붙이기보다 Node 버전 관리자나 사용자 쓰기 가능한 설치 경로를 택하는 편이 낫다.
오류 해결
Node.js 버전이 낮다는 경고
실패 출력 예시
npm WARN EBADENGINE Unsupported engine
npm WARN EBADENGINE required: { node: '>=20.0.0' }진단 입력
node --version
command -v node출력 예시
v18.19.0
/usr/bin/node출력의 의미
Node 18이 잡혀 있어 요구 버전을 만족하지 못한다. 이미 nvm을 쓰는 환경이라면 nvm install 22와 nvm use 22로 LTS 계열을 선택한 뒤 설치 명령을 다시 실행한다. 버전 관리자가 없다면 Node.js 공식 다운로드에서 지원 중인 LTS 설치법을 고른다. 출처가 불분명한 curl | sh 설치 명령은 쓰지 않는다.
설치됐는데 gemini 명령을 못 찾는 경우
실패 출력 예시
zsh: command not found: gemini진단 입력
npm prefix -g
command -v gemini출력 예시(경로는 환경마다 다름)
/Users/user/.nvm/versions/node/v22.18.0출력의 의미
첫 줄은 전역 npm 경로이고, 두 번째 줄이 비어 있으면 그 경로의 실행 파일 디렉터리가 현재 PATH에 없다는 뜻이다. 새 터미널을 연 뒤 다시 확인하고, nvm을 쓴다면 셸 시작 파일에서 nvm이 정상 로드되는지 확인한다. 공식 문제 해결 문서도 전역 설치의 경우 npm 실행 경로와 PATH 확인을 안내한다.
대화형 화면이 열리지 않는 경우
실패 출력 예시
$ gemini
$진단 입력
env | grep -E '^(CI|CI_)' || true출력 예시
CI=true출력의 의미
명령이 오류 메시지 없이 바로 프롬프트로 돌아오고 CI=true 같은 값이 보인다면 CI 환경으로 감지된 경우를 의심할 수 있다. 로컬 터미널에서 불필요하게 설정된 CI 변수만 unset CI로 해제하고 다시 실행한다. 자동화 환경이라면 대화형 로그인을 억지로 열지 말고 공식 인증 문서의 headless 방식과 별도 비밀 저장소를 사용해야 한다.
마지막으로 셸과 Gemini CLI 양쪽을 짧게 확인한다.
입력
test -f GEMINI.md && gemini --version && echo 'GEMINI.md ready'출력 예시
0.44.0
GEMINI.md ready출력의 의미
버전과 GEMINI.md ready가 연달아 나오면 명령 설치와 프로젝트 규칙 파일은 준비된 상태다. 이어서 gemini를 열어 /memory list에 현재 경로가 보이면 Gemini CLI 설정까지 확인이 끝난다.