초보자도 쉬운 Gemini CLI 입문: Tools와 Extensions 를 활용해 보자!

AONEKO·2026년 3월 27일

AI

목록 보기

4/5

Gemini CLI 란?

💡 Gemini 명령줄 인터페이스 (CLI)는 터미널에서 직접 Gemini에 액세스할 수 있는 오픈소스 AI 에이전트입니다. Gemini CLI는 기본 제공 도구와 로컬 또는 원격 MCP 서버와 함께 추론 및 행동(ReAct) 루프를 사용하여 버그 수정, 새로운 기능 생성, 테스트 범위 개선과 같은 복잡한 사용 사례를 완료합니다. Gemini CLI는 코딩에 탁월할 뿐만 아니라 콘텐츠 생성, 문제 해결, 심층 조사, 작업 관리 등 다양한 작업에 사용할 수 있는 다목적 로컬 유틸리티입니다.
출처 : Gemini for Google Cloud

Gemini CLI 설치하기

준비 → 설치 → 인증 → 동작 확인하는 단계로 진행한다.

1. 사전 준비 : Node.js 설치하기

Gemini CLI를 설치하기 전에 우선적으로 node.js 설치해야 한다. (node Version 20 이상)

왜 node.js를 먼저 설치해야 하는가? 크게 2가지 이유가 있다.
- JavaScript 런타임 환경 (Runtime Environment) : 많은 오픈소스 gemini-cli 도구들이 JavaScript나 TypeScript로 작성되어 있다. 이를 윈도우나 리눅스 터미널에서 실행하려면 코드를 해석하고 시스템 리소스(CPU, 메모리)를 할당해 줄 Node.js라는 "구동기"가 필수적이다.
- 패키지 관리자: NPM (Node Package Manager) : Node.js를 설치하면 npm이라는 강력한 패키지 관리 도구가 함께 설치된다.

💡 Node.js 란? 웹 브라우저 외부에서 JavaScript 코드를 실행할 수 있게 해주는 오픈 소스, 크로스 플랫폼 JavaScript 런타임 환경이다.
본래 JavaScript는 웹 브라우저 내부에서만 동작하도록 설계된 언어였다. 하지만 Node.js는 브라우저 외부(OS 레벨)에서 JavaScript 코드를 실행할 수 있게 해주는 엔진(V8)과 라이브러리의 집합이다.

Node.js를 설치하는 방법 : 아래의 링크를 클릭하여 설치 프로그램을 다운로드한다.

➡️ https://nodejs.org/ko/download ⬅️

msi 파일을 다운로드하여 설치를 진행한다. 별도의 변경이나 설정없이 무지성으로 그냥 next 버튼을 눌러서 설치하면 된다.
설치 확인하기 : 설치 완료 후 잘 설치되었는지 다음 명령어로 확인한다.

윈도우 시작 ==> powershell 검색 ==> 클릭

⬇️ powershell 창에서 `npm -v` 명령어로 설치된 npm의 버전을 확인한다. ⬇️

❌ 주의 ❌ 만약 해당 명령어 실행시 "npm : 이 시스템에서 스크립트를 실행할 수 없으므로... " 라는 에러 메세지가 나올 때
원인 : 해당 에러가 발생하는 이유는?
Windows는 기본적으로 악성 스크립트 실행을 방지하기 위해 Restricted 정책을 유지한다. npm은 내부적으로 PowerShell 스크립트를 호출하므로 정책 위반으로 차단되는 것이다.
해결법
powershell을 관리자 권한으로 실행하고 다음 명령어를 실행하여 시스템 전역 설정을 변경한다. (반드시 powershell을 관리자 권한으로 실행해야 한다.)

Set-ExecutionPolicy RemoteSigned

⬇️ powershell을 관리자 권한으로 실행 ⬇️

다음 명령어를 실행한다. `Set-ExecutionPolicy RemoteSigned` → 그리고 Y를 입력한다.

참고) 해당 설정을 기본값으로 돌리고자 할 때
Set-ExecutionPolicy Undefined -Scope LocalMachine

설치를 확인한다.
npm -v 에서 현재 설치 버전을 확인하여 에러 없이 버전이 표시 되면 설치 확인 완료!

💡 보안 참고사항
RemoteSigned 정책은 로컬에서 작성한 스크립트는 허용하고, 인터넷에서 다운로드한 스크립트는 신뢰할 수 있는 게시자의 서명이 있는 경우에만 실행하도록 제한하는 중도적인 보안 설정이다. 개발 환경에서는 이 설정이 사실상 표준이다.
혹시 특정 IDE(Cursor, VS Code 등)의 내장 터미널에서만 문제가 지속된다면, 해당 IDE를 재시작한다. 그러면 변경된 환경 변수와 정책을 다시 로드되고 문제가 해결된다.

2. Gemini CLI 설치하기

설정을 진행하고 Gemini CLI를 실행하기 전에, 추후 모든 프로젝트의 홈 폴더로 사용할 폴더를 만든다.

mkdir gemini-cli-projects

해당 폴더로 이동한다.

cd gemini-cli-projects

다음 명령어로 시스템에 Gemini CLI를 전역적으로 설치한다.(추천)

npm install -g @google/gemini-cli

다음을 실행하여 CLI가 설치되었는지 확인할 수 있다.⬇️

gemini --version

gemini 명령어를 통해 Gemini CLI를 직접 실행할 수 있다.
이때 해당 폴더에 대한 보안 경고가 뜰 수 있다. 현재 디렉토리(gemini-cli-projects)에 포함된 로컬 설정 파일이나 스크립트를 자동으로 실행할 수 있는 권한을 요청하기 때문이다. Trust folder를 선택하고 enter한다.⬇️
인증 방법을 묻는 메시지가 표시된다. ⬇️
1. Sign in with Google을 선택한다. 개인 Google 계정을 사용하면 된다. Google 또는 Google Workspace 관련 계정은 사용하지 않는 것이 좋다. 이 무료 라이선스를 통해 Gemini 2.5 Pro와 100만 토큰 컨텍스트 윈도우를 사용할 수 있다. 무료 등급에서는 분당 60개의 모델 요청과 일일 1,000개의 요청을 무료로 허용한다. (자세한 할당량 및 한도는 별도 참조)
Google 계정에 제공되는 현재 무료 할당량의 한도에 도달한 경우 Gemini API 키 또는 Google Cloud Vertex AI를 사용할 수 있다. 이 경우 프로젝트 ID와 해당 프로젝트의 위치 이름이 필요하다. 다른 인증 방법을 사용하려면 다음을 참고하라.
1. Sign in with Google : 구글 계정으로 로그인해 사용하는 방식이다. 별도의 키 발급이나 추가 설정 없이 바로 사용할 수 있어, 개인 개발, 학습, 테스트 용도로 가장 간단한 선택지이다.
2. Use Gemini API Key : Gemini API Key를 발급해 연동하는 방식이다. Gemini API 키를 사용하는 AI Studio 사용자 또는 Headless mode 유형에 사용한다.
3. Vertex AI : Google Cloud Vertex AI 사용자, Google Cloud 기반의 Vertex AI와 연동해 사용하는 방식이다. 기업 환경이나 대규모 프로젝트에서 사용된다.

사용자 유형 / 시나리오	권장 인증 방법	Google Cloud 프로젝트 필요 여부
개인 Google 계정	Sign in with Google	아니요 (예외 있음)
회사, 학교 또는 Google Workspace 계정을 사용하는 조직 사용자	Sign in with Google	예
Gemini API 키를 사용하는 AI Studio 사용자	Use Gemini API Key	아니요
Google Cloud Vertex AI 사용자	Vertex AI	예
Headless mode	Use Gemini API Key 또는 Vertex AI 사용	아니요 (API 키 사용 시) 예 (Vertex AI 사용 시)

💡 참고사항

Headless mode: 디스플레이 장치(모니터)나 GUI 없이 서버나 터미널에서만 동작하는 환경을 의미한다. 자동화 스크립트나 서버 백엔드 구축 시 주로 활용된다.

Vertex AI vs AI Studio: 기업용 인프라와 결합된 보안 모델을 원한다면 Vertex AI(프로젝트 필요)를, 빠른 프로토타이핑과 개인 프로젝트를 원한다면 AI Studio(API 키 방식)를 선택하는 것이 일반적이다.

1. Sign in with Google 선택 후 Enter. → 그러면 별도의 브라우저에서 Google 인증 페이지가 열린다. → 본인의 Google 계정으로 인증을 진행하고 약관에 동의하면 인증이 완료된다.
⬇️ 구글 계정으로 인증 완료한 후 R을 눌러 재시작한다.

⬇️ Gemini CLI가 준비되어 명령어가 입력되기를 기다린다.

3. settings.json을 통한 Gemini CLI 구성

settings.json 파일을 활용한 Gemini CLI 구성은 전역 설정이나 프로젝트별 동작 방식을 정의하는 방법이다.

파일 위치 : 보통 Gemini CLI의 설정 파일은 각 운영체제의 사용자 홈 디렉토리 내 .gemini 또는 AppData 폴더에 위치한다.
설정 우선 순위 : 설정은 다음 우선순위에 따라 적용된다.
1. 시스템: /etc/gemini-cli/settings.json (모든 사용자에게 적용되며 사용자 및 워크스페이스 설정을 재정의함)
2. 작업공간: .gemini/settings.json (사용자 설정을 재정의함)
3. 사용자: ~/.gemini/settings.json

💡windows 기준 settings.json 파일 위치
사용자 : 일반적으로 C:\Users\사용자이름\.gemini\settings.json
시스템 : 일반적으로 C:\ProgramData\gemini-cli\settings.json
⬇️ settings.json 파일의 기본적인 내용

{
  "security": {
    "auth": {
      "selectedType": "oauth-personal"
    }
  }
}

4. Gemini CLI와의 상호작용

Gemini에게 인공지능과 관련된 농담을 시켜보았다. 썰렁한 농담을 답변이라고 내놓았다. (이 농담... 나만 안웃김?😱)

Gemini CLI를 종료하려면 /quit 명령어를 사용하면 된다.

/help 명령어를 사용하면 기본 명령어에 대한 도움말을 참조할 수 있다.
Gemini 기본 명령어 참조는 여기 링크를 참조하면 된다.

Gemini CLI - tools

Gemini CLI는 로컬 환경과 상호작용하고, 정보를 접근하며, 사용자를 대신해 작업을 수행하는 도구를 사용한다.

도구는 일반적으로 Gemini CLI가 행동을 수행해야 할 때 자동으로 호출한다. 특정 도구를 수동으로 호출할 수도 있다.
사용자 확인 필요 : 파일을 수정하거나 하는 경우 사용자가 도구의 실행을 승인해야 한다.
Trusted folders : 모델이 시스템 도구를 사용할 수 있도록 어떤 디렉터리를 설정할 수 있다.
Gemini CLI에는 기본 제공 도구 모음이 함께 제공된다. Tools 관련 문서는 여기 링크 를 참조하면 된다.
현재 기본 제공 도구 목록을 가져오려면 다음과 같이 /tools 명령어를 호출한다.

도구 사용 예제

다음과 같은 프롬프트를 사용해 보자.

오늘 금융계의 최신 헤드라인을 검색하여 finance-news-today.txt라는 파일에 저장하세요.

이 요청은 Google 검색을 실행(GoogleSearch)하여 금융 뉴스를 제공할 수 있는 관련 정보 소스에서 뉴스를 가져와야 한다. 그리고 다음 콘텐츠가 포함된 finance-news-today.txt이라는 파일을 생성해야 한다 로컬 파일 시스템에 쓰기 작업(WriteFile) 권한이 필요하다.
Gemini CLI가 선택한 도구를 실행하려고 할 때 사용자에게 권한을 요청하는 메시지가 표시된다. 사용자는 권한을 거부하거나, 한 번만 실행하도록 허용하거나, 항상 실행되도록 권한을 부여할 수 있다.
Gemini CLI는 먼저 GoogleSearch 도구를 호출하여 웹을 검색하고 결과를 가져온다.
검색한 정보를 파일에 쓸 준비가 되고 WriteFile 도구를 사용한다. 이때 사용자에게 권한을 요청한다. 사용자는 권한 유형(예: allow once, allow always 등)을 정할 수 있다. Allow once를 선택한다.
⬇️ 그러면 Gemini CLI가 이 정보를 파일에 쓰고 다음과 같이 성공 메시지를 출력한다.
파일이 작성되었는지 확인해보자.
@file를 사용하여 콘텐츠를 읽어 달라고 요청할 수 있다. @을 입력하면 현재 폴더에 있는 파일 목록이 표시되고 방금 생성된 파일(finance-news-today.txt)이 표시된다.
⬇️ @finance-news-today.txt 의 내용을 읽어줘. 라고 프롬프트를 제출한다. 이렇게 하면 필요한 도구 (ReadManyFiles, ReadFile)가 호출되고 콘텐츠가 아래와 같이 표시된다. (한글 번역을 요청하지 않았는데 한글로 번역하여 내용을 출력한다.)
추가적인 실습
추가적으로 다음 프롬프트를 실행해 보자.

가장 최근의 GeekNews RSS Feed를 확인하고 핵심 사항을 보기 좋게 정리된 목록으로 표시해줘.

Google Search 도구를 사용하여 "GeekNews RSS feed URL Korea"를 찾고 WebFetch 도구를 통해 최신 기술을 가져온다.

이어서 핵심 소식을 마크다운을 사용한 형태로 정리하여 화면에 출력했다.

Gemini CLI - Shell mode

메시지 상자에서 !를 사용하면 Shell 모드로 전환된다. !를 다시 누르거나 ESC 키를 누르면 되돌아간다.
ls 같은 shell명령어를 사용할 수 있다.
cat 명령어를 사용하여 파일 내용을 출력한다.

Gemini CLI 확장 프로그램

Gemini CLI 확장 프로그램은 Gemini 명령줄 인터페이스 (CLI)의 기능과 통합을 강화하도록 설계된 자체 포함 패키지이다.
LLM의 능력을 로컬 개발 환경이나 특정 워크플로우에 결합하는 '모듈형 도구 상자' 역할을 한다. 확장 프로그램을 사용하면 Gemini CLI의 기능을 확장하고 다른 사용자와 공유할 수 있다.

확장 프로그램의 핵심 구성 요소
- 프롬프트 패키징 (Prompt Packaging): 반복적으로 사용되는 복잡한 시스템 프롬프트나 페르소나를 템플릿화한다. 미리 정의된 확장 프로그램을 실행하여 원하는 결과를 얻을 수 있다.
- MCP 서버 (Model Context Protocol): 모델이 로컬 파일 시스템, 데이터베이스, 혹은 외부 API와 안전하게 상호작용할 수 있게 해주는 표준 규격이다. 이를 통해 Gemini가 "에이전트"로의 역할을 수행할 수 있다.
- 커스텀 명령어 (Custom Commands): .toml 파일. 자주 사용하는 워크플로우를 CLI 명령어 하나로 압축한다. (예: gemini review-code 명령어로 특정 폴더의 변경 사항만 골라 리뷰 수행)
- 컨텍스트 파일 (GEMINI.md)을 사용하여 모델에 구체적인 요청 사항과 가이드라인을 제공
확장 프로그램 갤러리 링크 : 공식 Google 제작 확장 프로그램과 서드 파티 확장 프로그램을 찾을 수 있는 중앙 마켓플레이스
powershell 창을 열고 gemini extensions 명령어를 실행해 보자. 이 명령어는 extentions의 설치/제거, 목록, 업데이트, 사용 설정/사용 중지 등에 활용된다.
현재 목록 확인하기 : gemini extensions list 명령어를 실행한다. 아직 설치된 확장 프로그램이 없어서 다음과 같이 출력된다.

실습 삼아 Google Workspace 확장 프로그램을 설치해 보고 테스트 해보자.

Google Workspace 확장 프로그램 사용해보기

Google Workspace 확장 프로그램 Gemini 확장 프로그램 갤러리(https://geminicli.com/extensions/) 에서 찾을 수 있다.

이 확장 프로그램은 특정 Google Workspace API 엔드포인트를 LLM이 호출할 수 있는 '도구'에 매핑한다.

파일 관리 (Drive)
문서 작성 (Docs)
시간 관리 (캘린더)
커뮤니케이션 (Gmail/Chat)

Google Workspace 확장 프로그램을 설치

먼저 Google Workspace 확장 프로그램을 설치한다.
확장 프로그램 갤러리 링크에서 google workspace를 검색하고 클릭한다.

해당 설치 명령어를 copy하여 powershell에서 실행한다.

gemini extensions install https://github.com/gemini-cli-extensions/workspace

실행하면 확인이 필요하다는 메시지가 표시된다. Y를 입력하여 승인한다. 그러면 Google Workspace 확장 프로그램이 성공적으로 설치된다.
gemini extensions list 명령어를 실행하면 아래와 같이 Google Workspace 확장 프로그램이 설치된 것을 확인할 수 있다.
Gemini CLI를 실행한다. Gemini를 실행한 다음 /mcp list 명령어를 사용하여 확장 프로그램이 성공적으로 설치되었는지 확인할 수 있다.

💡 아래에 제시된 프롬프트를 입력하면 Gemini CLI가 Google Workspace 도구에서 사용할 올바른 도구를 식별하고 도구를 호출할 수 있는 권한을 요청한다. 따라서 적절하게 승인해 주어야 한다.

예제 1) 구글 드라이브 문서 검색

다음과 같은 프롬프트를 작성하여 구글 드라이브 내의 파일을 검색한다.
Search for <DOC_NAME> in Google Drive : <DOC_NAME> 부분에 파일명을 작성하면 된다. (한글로 작성해도 된다.)

⬇️ 작업을 실행하기 위한 구글 계정에 대한 액세스 요청 화면 ⬇️

내 구글 드라이브에 있는 파일에 대해서 검색을 요청했다. 문서 검색의 작업 수행 결과는 다음과 같다.
해당 파일을 요약해줘라고 요청했을 때 작업 승인을 요청한다.
요청 승인후 해당 파일의 요약 내용을 확인할 수 있다.

예제 2) 구글 검색의 결과를 정리하여 구글 문서로 생성한다.

다음과 같은 프롬프트를 작성한다. 특정 검색 내용 정리하고 해당 내용을 구글 드라이브내에 doc 파일로 생성한다.

구글 터보 퀀트에 대한 내용을 찾아보고, 
관련 정보를 담은 1페이지 분량의 문서를 구글 드라이브에 doc 파일로 작성해줘.

작업 중간, 중간에 파일을 생성하기 위해 작업 승인을 요청한다. 1. Allow once를 선택하여 승인 요청을 허락해준다.

⬇️ 최종적으로 파일을 생성한다.
⬇️ 해당 링크를 클릭하면 생성된 구글 드라이브내 문서를 확인할 수 있다.

🎯 참조

AONEKO

The Road Not Taken

이전 포스트

Vibe Coding과 Agentic Coding

다음 포스트