Gemini CLI 설치 가이드 (Homebrew 이용)

사실 한국어도 한다. ^^;;

Intro

이 문서는 Windows(WSL Ubuntu)와 macOS(Zsh) 환경에서

패키지 매니저인 Homebrew를 사용하여 Gemini CLI를 설치하는 방법을 안내함.

---

Gemini CLI란?

Gemini CLI는 구글의 Gemini를 터미널(Terminal) 환경에 통합한 도구임.

 

복잡한 명령어를 암기하는  대신 자연어로 컴퓨터와 소통하며 시스템 제어, 코딩, 파일 관리 등을 수행할 수 있도록 도와주는 tool.

 

1. 핵심 기능 (Key Features)
   • 자연어 명령어 처리: "파일 복사해줘", "폴더 정리해줘"와 같은 일상 언어를 운영체제에 맞는 정확한 명령어(Command)로 변환함.
   • 시스템 제어 및 자동화: 단순한 대답을 넘어, 사용자의 동의하에 파일을 생성하거나 스크립트를 실행하는 등 실질적인 작업을 수행함.
   • 컨텍스트 인식: 현재 작업 중인 폴더의 내용이나 프로젝트의 성격을 파악하여 상황에 맞는 최적의 답변을 제공함.
   • 크로스 플랫폼 지원: Windows(CMD/PowerShell), macOS(Zsh), Linux 등 다양한 운영체제 환경을 모두 지원함.
2. 활용 가치 (Why Use It?)
   • 진입 장벽 완화: 터미널 환경이 낯선 초보자가 명령어 문법을 몰라도 시스템을 쉽게 제어할 수 있음.
   • 생산성 향상: 반복적인 작업이나 복잡한 환경 설정 과정을 AI에게 위임하여 업무 효율을 높임.
   • 실시간 학습 도구: 에러 발생 시 즉각적인 원인 분석과 해결책을 제시받아, 문제 해결 능력을 키우는 튜터(Tutor)로 활용 가능함.
3. 작동 방식 (How It Works)
   1. 입력: 사용자가 터미널에서 gemini "바탕화면의 txt 파일을 백업 폴더로 옮겨줘"라고 입력.
   2. 변환: AI가 사용자의 운영체제(Windows/Mac)를 파악하여 적절한 명령어(move 또는 mv) 생성.
   3. 실행: 사용자의 승인을 거쳐 명령어를 실행하고 결과를 출력함.

Gemini CLI는 딱딱한 CLI(명령 줄 인터페이스) 환경을 대화형 AI 인터페이스로 변환하여, 누구나 쉽고 강력하게 컴퓨터를 다룰 수 있게 해주는 차세대 도구임.

 

관련한 문서 자료(공식 사이트)는 다음 URL을 확인할 것:

https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#gemini-cli

GitHub - google-gemini/gemini-cli: An open-source AI agent that brings the power of Gemini directly into your terminal.

---

 

WSL을 사용한 이유.

• Windows 의 일반적인 터미널인 cmd(command prompt)와 powershell 에서 Gemini CLI를 사용하는 것보다 wsl이 보다 궁합이 잘 맞음.
• 2025.12.26 현재 Gemini CLI 의 /copy 명령어가 cmd와 powershell 모두 동작하지 않는 등의 문제가 있으나 wsl에서는 문제가 없었음.
  Ubuntu를 많이 쓰기 때문에 Ubuntu로 기술했으나, Debian의 경우도 큰 차이는 없음.

https://dsaint31.tistory.com/423

[CE] Introduction of WSL

---

 

Homebrew를 사용한 이유.

• 사실 npm (Node Package Manager)을 사용하여 Gemini CLI를 설치하는 것이 보다 일반적임.
• 개인적으로 npm을 별로 사용하지 않고, macOS나 Linux에서 똑같은 방법으로 설치하길 원해서 Homebrew를 선택함.

2024.09.08 - [utils] - [Utils] homebrew - Summary

[Utils] homebrew - Summary

---

0. 정식 설치 안내

가장 빠른 설치법은 여기를 참고하는게 정석임:

https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quick-install

GitHub - google-gemini/gemini-cli: An open-source AI agent that brings the power of Gemini directly into your terminal.

---

1. macOS 설치 (Zsh 환경)

macOS는 Gemini CLI를 Homebrew로 설치하기가 매우 쉬움(사실 Homebrew는 macOS에서 가장 널리 사용되는 패키지 매니저임).

 

Homebrew 설치 시 필요한 개발 도구(Xcode Command Line Tools)가 자동으로 구성됨.

---

1단계: Homebrew 설치

• Terminal (or iterm2)에서 공식 설치 스크립트를 실행하여 Homebrew를 설치함.
• 이 과정에서 관리자 권한(비밀번호)을 요구할 수 있으며, Xcode Command Line Tools가 없다면 자동 설치 팝업이 뜸.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

 

다음 내용을 보고 따라서 설치하는 것을 권함:
https://ds31x.tistory.com/336#%EC%84%A4%EC%B9%98%ED%95%98%EA%B8%B0

[Utils] homebrew - Summary

---

2단계: 경로(Path) 설정 (필수)

• 설치가 끝났다고 바로 brew 명령어가 되지 않음.
• macOS 시스템이 brew 명령어의 위치를 알 수 있도록 path(경로)를 등록해야 함.
• 설치 완료 로그 맨 하단 "Next steps:" 에 나오는 명령어 2~3줄을 복사해서 실행하는 것이 가장 정확함.

(Apple Silicon 모델 예시)

(echo; echo 'eval "$(/opt/homebrew/bin/brew shellenv)"') >> ~/.zshrc
eval "$(/opt/homebrew/bin/brew shellenv)"

 

• 이건 예시일 뿐, 가급적 설치 완료  로그 에서 지시하는대로 해야함.
• Intel Mac의 경우 경로가 조금 다르므로 꼭 설치완료 로그의 지시사항을 따르는 것을 권장함.

---

3단계: Gemini CLI 저장소 연결 및 설치 (Tap 연결 필수 아님.)

현재 Gemini CLI는 Homebrew 공식 formula로 설치가 가능하므로 tap 연결이 필요 없음.

• Tap 연결 (brew tap):
  • Gemini CLI는 Homebrew의 기본 목록(Core)에 없으므로,
  • 구글이 관리하는 전용 저장소(google-gemini/gemini-cli)를 내 컴퓨터에 연결해줘야 함.
• 설치 (brew install):
  • 연결된 저장소에서 Gemini CLI 패키지를 다운로드하고 설치함.

# brew tap google-gemini/gemini-cli #시도할 경우 인증이 필요하니 tap연결하지 말 것.
brew install gemini-cli

tap의 개념은 다음을 참고:

2023.12.15 - [Mac] - [Homebrew] Formula 와 cask 의 차이 + tap

[Homebrew] Formula 와 cask 의 차이 + tap

---

4단계: 설치 결과 확인

• 설치된 Gemini CLI의 버전을 출력하여 정상적으로 실행되는지 검증함.

gemini --version

---

2. Windows 설치 (WSL: Ubuntu 환경)

Windows에서는 리눅스 가상 환경인 WSL(Windows Subsystem for Linux)을 통해 설치를 진행함.

리눅스 환경은 macOS와 달리 기본 개발 도구가 없으므로 추가적인 라이브러리 설치가 필요함.

---

1단계: Zsh 설치 및 기본 셸 설정

• Ubuntu의 기본 셸인 Bash 대신, 더 강력한 기능을 제공하는 Zsh를 설치하고 기본값으로 변경함.

  sudo apt update && sudo apt install -y zsh
  chsh -s $(which zsh)
  zsh
  # (설정 마법사가 나오면 숫자 '2'를 눌러 추천 설정을 적용)

서버 시스템에선 bash가 보다 권장되나... Gemini CLI를 서버에 설치하진 않을 것으므로 개인용에 적합한 zsh을 사용한다.

추가로 oh my zsh도 설치해주면 좋다.

---

2단계: 필수 의존성 라이브러리 설치 (build-essential)

• 왜 필요한가?:
  • Homebrew는 프로그램 설치 시 소스 코드를 직접 컴파일(Build)해야 하는 경우가 빈번함.
  • Formula는 소스를 빌드하여 시스템에서 사용 가능하게 만드는 명세서이므로 실제 빌드 과정을 요구함.
  • 미리 빌드된 바이너리인 Bottle이 제공되기도 하지만, 모든 패키지나 환경에서 이를 보장할 수 없으므로 로컬 빌드 환경 구축이 필수적임.
• 역할:
  • gcc(C언어 컴파일러), make(빌드 도구) 등 리눅스에서 소프트웨어를 설치하고 실행하는 데 필수적인 도구 모음을 설치함.
  • 이 과정이 없으면 brew install 도중 에러가 발생할 확률이 매우 높음.

sudo apt-get install build-essential curl procps file git

• 사실 build-essential과 curl만으로 충분하다. 

---

3단계: Linux용 Homebrew 설치

• 리눅스 환경에 최적화된 Homebrew 설치 스크립트를 실행함.
• 아래 스크립트는 curl을 사용함. 없다면 설치를 미리 해야 함: sudo apt-get install curl

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

 

다음 url을 읽어보면서 설치해도 됨 (3단계와 4단계를 커버함):

2023.09.05 - [Linux] - [Linux] homebrew 설치하기 (Ubuntu)

[Linux] homebrew 설치하기 (Ubuntu)

---

4단계: Linux용 경로 설정 (필수)

• 리눅스용 Homebrew는 /home/linuxbrew/.linuxbrew라는 특수 경로에 설치됨.
• 이 경로를 Zsh 설정 파일(.zshrc)에 등록해야만 brew 명령어를 어디서든 사용할 수 있음.

(echo; echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"') >> ~/.zshrc
eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"

 

• Linux용 Homebrew는 기본적으로 /home/linuxbrew/.linuxbrew라는 비표준 경로에 설치됨.
• 리눅스 시스템은 이 경로에 명령어들이 있다는 것을 모르기 때문에, "여기에도 실행 파일이 있으니 찾아봐라" 라고 알려주는 설정이 필요함.
• 첫번째 줄
  • ( ... ): 괄호 안의 명령어들을 하나의 그룹으로 묶어서 실행함.
  • echo: 빈 줄을 하나 출력함. (설정 파일의 기존 내용과 섞이지 않게 줄바꿈을 하기 위함)
  • echo 'eval ...': 홑따옴표 안의 문자열 내용을 그대로 출력함.
  • eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)":
    • $(...)은 가로안의 명령어를 실행한 결과 문자열로 치환됨
    • eval "..."은 쌍따옴표의 명령어를 실행.
  •  >> ~/.zshrc: 앞에서 출력된 내용을 Zsh 설정 파일(.zshrc)의 맨 끝에 추가(Append)함.
  • 결과: 이제 터미널을 새로 열 때마다 이 설정이 자동으로 실행되어 brew를 쓸 수 있게 됨.
•  두 번째 줄: 즉시 적용
  • $( ... ): 괄호 안의 명령어를 실행하고, 그 결과값으로 대체됨.
  • /home/linuxbrew/.linuxbrew/bin/brew shellenv 를 실행하면, PATH, MANPATH 등 필요한 환경 변수 설정 스크립트가 출력됨.
  • eval: 위에서 출력된 스크립트 코드를 현재 터미널에서 즉시 실행함.
  • 결과: 터미널을 껐다 켜지 않아도 방금 설치한 brew 명령어를 바로 사용할 수 있게 됨.
• 요약
  • 첫 번째 줄: "다음번에 터미널을 켤 때부터 brew를 쓰게 해줘." (영구 설정)
  • 두 번째 줄: "지금 당장 brew를 쓰게 해줘." (즉시 적용)

사실, 설치 완료 로그에 해당 내용에 대한 안내가 나온다.
이 문서의 내용보다 해당 로그의 내용대로 해야 정확하다.
이 문서는 해당 로그의 내용을 반영하여 작성했으나 추후에 변경이 이루어질수도 있으므로 반드시 설치로그를 확인할 것.

---

5단계: Gemini CLI 저장소 연결 및 설치 (Tap 필수 아님)

• macOS와 동일하게 전용 저장소(tap)를 연결한 후 패키지 설치를 진행함.

  # brew tap google-gemini/gemini-cli # 실행시 인증요구하고 에러로 이어짐. 주석처리
  
  # 현재 core formula이므로 tap 추가 없이 설치가능함.
  brew install gemini-cli

---

6단계: 설치 결과 확인

• 버전 정보를 확인하여 설치가 성공적으로 완료되었는지 테스트함. 

gemini --version

---

같이 보면 좋은 자료들

2023.12.15 - [Mac] - [Homebrew] 사용법 요약본

[Homebrew] 사용법 요약본

2025.12.26 - [CE] - Gemini CLI와 함께하는 터미널(CLI) 명령어 학습하기

Gemini CLI와 함께하는 터미널(CLI) 명령어 학습하기

---