Gemini CLI 설치부터 API 키 영구 세팅

최근 터미널 창을 벗어나지 않고 AI 코딩 어시스턴트를 활용하는 워크플로우가 개발자들 사이에서 큰 인기를 끌고 있습니다. Aider나 Claude Code 같은 강력한 CLI 기반 AI 에이전트 도구들처럼, 구글에서도 터미널 환경에서 모델을 직접 호출하고 코드 베이스를 분석할 수 있는 Gemini CLI(@google/gemini-cli)를 제공하고 있습니다.

오늘은 웹 브라우저를 오갈 필요 없이, 터미널에서 구글의 최신 AI를 바로 사용할 수 있도록 Gemini CLI 설치부터 API 키 영구 세팅(macOS/zsh 기준), 그리고 실전 활용법까지 완벽하게 정리해 보겠습니다.

---

1. Gemini CLI 도구 설치하기

Gemini CLI는 Node.js 환경의 npm이나 macOS의 패키지 관리자인 Homebrew를 통해 간단히 설치할 수 있습니다. 터미널을 열고 아래 명령어 중 본인에게 맞는 것을 하나 선택해 실행해 주세요. (npm 설치를 권장합니다.)

# npm으로 전역 설치 (권장)
npm install -g @google/gemini-cli

# 또는 Homebrew로 설치
brew install gemini-cli

2. Gemini API 키 발급 및 영구 세팅

최초 실행 시 브라우저 인증을 거칠 수도 있지만, 원활한 사용과 커스텀 확장을 위해서는 API 키를 직접 발급받아 환경 변수에 등록하는 방식이 훨씬 편리합니다.

① API 키 발급받기

Google AI Studio에 접속해 로그인한 뒤, Create API key 버튼을 눌러 새로운 키를 생성하고 복사해 둡니다.

② .zshrc 파일에 환경 변수 등록하기

매번 터미널을 열 때마다 키를 입력하는 번거로움을 없애기 위해, macOS의 기본 쉘 설정 파일인 .zshrc에 키를 영구적으로 저장합니다. 터미널에 아래 명령어를 입력하세요. (본인의_API_키 부분에 복사한 키를 넣으시면 됩니다.)

echo 'export GEMINI_API_KEY="본인의_API_키"' >> ~/.zshrc

③ 변경 사항 즉시 적용

설정 파일에 추가한 내용을 현재 터미널 창에 바로 적용하려면 아래 명령어를 입력합니다.

source ~/.zshrc

3. Gemini CLI 실행 및 실전 인터페이스 활용법

세팅이 끝났다면 터미널에 gemini라고 입력해 보세요. 브라우저 창이 열리지 않고 곧바로 대화형 인터페이스로 진입하게 됩니다.

화면 하단에 > Type your message or @path/to/file 형태의 프롬프트 창이 나타나면 성공입니다! 이 인터페이스에서 꼭 알아두어야 할 핵심 기능 3가지를 소개합니다.

• 파일 및 폴더 참조 (@ 명령어): 프롬프트 창에 @를 입력하면 현재 디렉토리의 파일 목록이 팝업됩니다. 화살표 키로 경로를 선택해 질문과 함께 보낼 수 있습니다. (예: @src/main.py 이 코드의 성능을 최적화해 줘)
• 코드 수정 사항 즉시 적용 (Shift + Tab): AI가 기존 코드에 대한 수정(Edit)을 제안했을 때, 해당 제안이 마음에 든다면 키보드의 Shift + Tab을 눌러 보세요. 내 로컬 파일에 변경 사항이 즉각적으로 덮어씌워집니다.
• 대화 종료: 작업을 마치고 일반 터미널 환경으로 빠져나가려면 Ctrl + C를 누르시면 됩니다.

4. 실무 활용 꿀팁: 프로젝트 컨텍스트 고정하기

특정 프로젝트를 작업할 때마다 매번 폴더 구조나 코딩 컨벤션을 설명하기 귀찮으신가요?

작업 중인 프로젝트 폴더의 최상단(루트)에 GEMINI.md라는 파일을 하나 만들어두세요. 해당 폴더에서 Gemini CLI를 실행할 때마다 이 파일 안의 내용(아키텍처 설명, 코드 작성 규칙 등)을 AI가 기본 컨텍스트로 자동 반영하여 훨씬 스마트한 답변과 코드 리뷰를 제공해 줍니다.

---

마무리하며
터미널 안에서 AI와 대화하고 파일을 조작하는 것은 개발 생산성을 비약적으로 높여주는 경험입니다. 이번 가이드를 통해 Gemini CLI를 성공적으로 세팅하시고, 여러분만의 쾌적한 AI 개발 환경을 구축해 보시길 바랍니다!