출처: https://zenn.dev/schroneko/articles/gemini-cli-tutorial

Gemini CLI 간단 튜토리얼

tl;dr

명령줄에서 대화형으로 사용할 수 있는 오픈소스 AI 에이전트
npx https://github.com/google-gemini/gemini-cli로 즉시 이용 시작
@로 로컬 파일이나 디렉토리를 AI 컨텍스트에 추가
!로 셸 명령을 직접 실행, 셸 모드로의 전환도 가능
GEMINI.md 파일로 프로젝트별 맞춤 지시를 AI가 기억하도록 설정
Google 검색과의 연동, 안전한 샌드박스에서의 실행, 도구 자체 제작 등 높은 확장성

1. 시작하기

Gemini CLI에 오신 것을 환영한다!

이 문서는 Google이 개발한 오픈소스(Apache 2.0 라이센스) 명령줄 AI 에이전트인 "Gemini CLI"의 튜토리얼이다. 코딩 작업 보조는 물론, 리서치, 콘텐츠 생성, 일상적인 정형 업무 자동화까지, 개발자의 모든 워크플로우를 가속화하는 다목적 도구로 설계되었다.

이 가이드에서는 기본적인 사용법부터 내부 구조, 그리고 응용적인 커스터마이징 방법까지 포괄적으로 설명한다. 이 가이드를 읽고 나면 Gemini CLI를 자유자재로 다루며, 개발 워크플로우의 강력한 동반자로 활용할 수 있게 될 것이다.

2. 빠른 시작

먼저 Gemini CLI를 사용하기 위한 간단한 단계들이다.

전제 조건

Node.js 버전 18 이상이 설치되어 있어야 한다.

설치 및 첫 실행

터미널을 열고 다음 명령을 실행하기만 하면 된다.

npx https://github.com/google-gemini/gemini-cli

또는 글로벌로 설치할 수도 있다.

npm install -g @google/gemini-cli

첫 실행 시에는 몇 가지 설정을 진행한다.

테마 선택: 먼저 CLI의 외관 테마를 선택한다. 원하는 것을 선택하면 된다.
인증: 다음으로 브라우저가 열리고 Google 계정으로의 로그인을 요청한다. 지시에 따라 인증을 완료한다. 이를 통해 프리뷰 기간 중에는 Gemini 2.5 Pro와 그 광대한 100만 토큰의 컨텍스트 윈도우를 분당 60회 요청, 일일 1,000회 요청까지 무료로 이용할 수 있다.

인증이 완료되면 준비 완료다!

3. Gemini CLI로 할 수 있는 것들(구체적 예시)

Gemini CLI는 단순한 채팅 도구가 아니다. 로컬 환경과 깊이 연동되어 다양한 작업을 실행할 수 있다.

새로운 코드베이스 탐색하기

# 리포지토리를 클론하고 해당 디렉토리로 이동
git clone https://github.com/some/repository
cd repository

gemini
> 이 시스템 아키텍처의 주요 부분을 설명해줘.
> 어떤 보안 메커니즘이 도입되어 있나?

기존 코드 조작하기

gemini
> GitHub Issue #123을 구현하는 초안을 작성해줘.
> 이 코드베이스를 최신 버전의 Java로 마이그레이션하는 것을 도와줘. 먼저 계획부터 세워달라.

워크플로우 자동화하기

gemini
> 최근 7일간의 git 히스토리를 기능과 담당자별로 그룹화해서 슬라이드 자료를 만들어줘.
> 가장 상호작용이 많은 GitHub Issue를 표시하는 벽걸이 디스플레이용 풀스크린 웹앱을 만들어줘.

시스템 조작하기

gemini
> 이 디렉토리에 있는 모든 이미지를 png로 변환하고, exif 데이터의 날짜를 사용해서 리네임해줘.
> PDF 청구서를 지출 월별로 정리해줘.

4. 기본적인 사용법

대화 모드(인터랙티브 모드)

프로젝트 디렉토리 또는 새로운 빈 디렉토리에서 다음 명령을 입력한다.

gemini

그러면 > 프롬프트가 표시되고, Gemini와의 대화 모드가 시작된다. 이후에는 자연스러운 한국어로 말을 걸기만 하면 된다.

대화를 종료하려면 /quit 또는 /exit를 입력한다.

비대화 모드(명령줄 모드)

셸 스크립트에 포함하는 등, 단발성 명령으로 이용하고 싶은 경우에는 --prompt(또는 -p) 플래그를 사용해 비대화 모드로 실행할 수 있다.

gemini --prompt "1부터 10까지의 소수를 나열해줘"

# 파이프로 전달하는 것도 가능하다
echo "일본의 수도는 어디인가?" | gemini

5. 명령 참조

Gemini CLI에는 3가지 종류의 명령 형식이 있다.

실행 시의 명령줄 인수 (예: gemini --model ...)
대화 모드 중의 슬래시 명령 (예: /help)
프롬프트에 포함하는 특수한 접두사 (예: @나 !)

각각을 자세히 살펴보자.

5.1. 명령줄 인수

gemini --help를 실행하면 확인할 수 있는 옵션들이다.

--model <모델명> (단축형: -m)
사용할 Gemini 모델을 지정한다. 기본값 외의 모델(예: gemini-2.5-flash-latest)을 사용하고 싶을 때 지정한다.

--prompt <프롬프트> (단축형: -p)
비대화 모드로 실행할 때의 프롬프트를 지정한다.

--all-files (단축형: -a)
현재 디렉토리 이하의 모든 파일을 재귀적으로 읽어들여 컨텍스트로 프롬프트에 포함한다.

--sandbox (단축형: -s)
도구(특히 셸 명령)의 실행을 안전한 샌드박스 환경(Docker) 내에서 수행한다.

--sandbox-image <이미지URI>
샌드박스로 사용할 커스텀 Docker 이미지를 지정한다.

--yolo
"You Only Live Once" 모드. 도구 실행 전 확인을 요구하지 않고 모두 자동으로 승인한다. 샌드박스가 활성화되어 있는 것이 권장된다.

--checkpointing
도구 실행 전에 파일 상태를 저장(체크포인트 생성)하고, /restore 명령으로 복원할 수 있도록 한다.

--debug_mode (단축형: -d)
디버그용 상세한 로그를 출력한다.

--version
CLI의 버전 정보를 표시한다.

그 외에도 텔레메트리(사용 현황 통계)에 관한 --telemetry 계열 플래그가 있다.

5.2. 슬래시 명령

대화 모드 중에 /<명령> 형식으로 입력한다.

/help 또는 /?
사용 가능한 모든 슬래시 명령과 그 설명을 표시한다.

/quit 또는 /exit
Gemini CLI를 종료한다.

/clear
터미널 표시를 지운다. (단축키: Ctrl+L)

/chat
대화 히스토리를 관리한다.

/chat save <태그명>: 현재 대화에 이름(태그)을 붙여 저장한다.
/chat resume <태그명>: 저장한 대화를 불러온다.
/chat list: 저장한 대화의 태그 목록을 표시한다.

/memory
GEMINI.md 파일에 의해 읽어들인 AI의 기억(컨텍스트)을 관리한다.

/memory show: 현재 AI가 기억하고 있는 컨텍스트의 전체 내용을 표시한다.
/memory refresh: GEMINI.md 파일을 모두 재읽기한다.
/memory add <기억시킬 텍스트>: 현재 세션에 한해 임시적인 기억을 추가한다.

/tools
현재 사용 가능한 도구의 목록을 표시한다.

/tools desc: 각 도구의 상세한 설명을 표시한다.

/mcp
연결된 MCP(Model Context Protocol) 서버와, 그곳에서 제공되는 도구의 목록을 표시한다.

/restore [tool_call_id]
--checkpointing이 활성화된 경우, 도구 실행 전 상태로 프로젝트 파일을 복원한다. ID를 지정하지 않으면 복원 가능한 체크포인트의 목록을 표시한다.

/compress
그때까지의 대화 히스토리를 AI에게 요약시키고, 그 요약으로 컨텍스트를 대체한다. 토큰을 절약하고 싶은 긴 대화 도중에 유용하다.

/stats
현재 세션에서의 토큰 사용량, API 호출 횟수, 시간 등의 통계 정보를 표시한다.

/theme
CLI 외관의 테마를 선택하는 대화상자를 연다.

/auth
인증 방법을 변경하기 위한 대화상자를 연다.

/editor
차이점 표시 등에 사용하는 에디터를 선택하는 대화상자를 연다.

/bug
버그 신고용 URL을 생성하고 브라우저에서 연다.

/about
버전이나 빌드 정보 등을 표시한다. 버그 신고 시에 도움이 된다.

5.3. 특수한 접두사

프롬프트에 포함함으로써 특별한 동작을 한다.

@<파일경로> 또는 @<디렉토리경로>
지정된 파일 또는 디렉토리의 내용을 읽어들여 프롬프트의 컨텍스트에 포함한다. .gitignore를 존중하기 때문에 불필요한 파일(node_modules 등)은 자동적으로 제외된다.

예: @src/utils.ts 이 함수의 테스트를 작성해줘.

!<셸명령>
지정된 명령을 직접 셸에서 실행하고 결과를 표시한다.

예: !git diff --staged

! (단독)
셸 모드의 on/off를 전환한다. 셸 모드 중에는 모든 입력이 셸 명령으로 취급된다.

6. 설정 파일 (settings.json)

Gemini CLI의 동작은 settings.json 파일로 세밀하게 커스터마이징할 수 있다. 설정은 다음 순서로 읽어들여지며, 나중 것이 우선된다.

글로벌 설정: ~/.gemini/settings.json
프로젝트 설정: (프로젝트 루트)/.gemini/settings.json

다음은 주요 설정 항목들이다.

theme (문자열)
CLI의 테마명. 예: "GitHub"

contextFileName (문자열 또는 문자열 배열)
컨텍스트 파일로 인식할 파일명을 지정한다. 기본값은 "GEMINI.md"이지만, "CONTEXT.md" 등으로 변경하거나 ["GEMINI.md", "PROMPT.md"]처럼 복수 지정할 수도 있다.

fileFiltering (객체)
@ 명령의 동작을 제어한다.

respectGitIgnore (불린값): true인 경우 .gitignore를 존중한다. 기본값은 true.
enableRecursiveFileSearch (불린값): @의 입력 보완을 위해 파일을 재귀적으로 찾을지 여부. 기본값은 true.

autoAccept (불린값)
true로 하면 읽기 전용 등 안전하다고 판단되는 도구의 실행 확인을 건너뛴다. 기본값은 false.

sandbox (불린값 또는 문자열)
샌드박스 이용 설정. true 또는 "docker"로 활성화된다. 기본값은 false.

checkpointing (객체)
체크포인트 기능을 설정한다.

enabled (불린값): true로 하면 /restore 명령이 활성화된다. 기본값은 false.

preferredEditor (문자열)
차이점 표시 등에 사용할 에디터를 지정한다. 기본값은 "vscode".

coreTools / excludeTools (문자열 배열)
모델에 제공할 내장 도구를 명시적으로 지정하거나 제외할 수 있다.

mcpServers (객체)
커스텀 도구를 제공하는 MCP 서버를 정의한다. 서버별로 시작 명령이나 인수, 환경변수를 설정할 수 있다.

7. 내부 구조: 프롬프트는 어떻게 만들어지는가

Gemini CLI에 프롬프트를 입력하면, 그것이 직접 AI 모델에 보내지는 것이 아니다. CLI는 AI가 더 똑똑하고 문맥에 맞는 응답을 반환할 수 있도록 다양한 정보를 추가해서 최종적인 프롬프트를 구성한다. 이 구조를 이해하면 Gemini CLI를 더욱 효과적으로 활용할 수 있다.

최종적으로 AI 모델에 보내지는 프롬프트는 주로 다음 요소들로 구성된다.

시스템 인스트럭션 (System Instruction)
도구 정의 (Tool Definitions)
대화 히스토리 (Chat History)
사용자의 최신 프롬프트 (User's Latest Prompt)

1. 시스템 인스트럭션

이것은 AI 모델의 기본적인 행동을 정의하는 지시다. 여기에는 GEMINI.md에서 읽어들인 내용이 포함된다.

CLI는 다음 장소에서 GEMINI.md(또는 contextFileName으로 지정된 파일)를 찾아 그 내용을 연결해서 시스템 인스트럭션에 추가한다.

글로벌한 컨텍스트: ~/.gemini/GEMINI.md
프로젝트의 컨텍스트: 프로젝트 루트나 그 부모 디렉토리에 있는 GEMINI.md
로컬한 컨텍스트: 현재 디렉토리 이하의 서브디렉토리에 있는 GEMINI.md

이를 통해 "이 프로젝트에서는 반드시 이 규약을 따르도록" 같은 계층적 지시가 가능해진다.

2. 도구 정의

Gemini CLI는 read_file이나 run_shell_command 같은 "도구"를 사용할 수 있다. 더불어 내장된 Google 검색 도구도 이용 가능하다. AI 모델이 이러한 도구들을 올바르게 사용할 수 있도록, 각 도구의 기능, 인수, 사용법을 정리한 "정의서"가 프롬프트에 포함된다. 이를 통해 AI는 "이 작업에는 저 도구를 사용할 수 있겠다"고 판단할 수 있게 된다.

3. 대화 히스토리

과거의 주고받기도 중요한 컨텍스트다. 그때까지의 사용자와 AI의 대화 히스토리가 모두 포함된다.

4. 사용자의 최신 프롬프트

그리고 마지막으로, 사용자가 입력한 최신 프롬프트가 추가된다. @ 명령을 사용한 경우에는 여기서 파일의 실제 내용이 전개되어 삽입된다.

8. 오픈소스와 확장성

Gemini CLI는 Apache 2.0 라이센스 하에 공개된 완전한 오픈소스 프로젝트다. 이는 누구나 소스코드를 열람, 검증하고 개선에 기여할 수 있음을 의미한다.

코드의 투명성: 내부에서 무엇이 일어나고 있는지 정확히 파악할 수 있다.
커뮤니티에 의한 기여: 버그 수정이나 새로운 기능 제안을 환영한다.
커스터마이징: 자신이 직접 포크해서 특정 요구사항에 맞춘 독자적인 버전을 만드는 것도 가능하다.

또한 이 도구는 Google의 AI 코딩 어시스턴트인 Gemini Code Assist와 기술을 공유하고 있으며, VS Code 등의 IDE에서도 동일하게 강력한 AI 에이전트 기능을 이용할 수 있다.

9. 튜토리얼은 이상이다

이 상세한 가이드가 여러분의 Gemini CLI 습득에 도움이 되기를 바란다.

소개한 명령이나 설정을 시험해보고, GEMINI.md를 활용해서 꼭 여러분의 프로젝트에 최적화된 AI 어시스턴트를 기르길 바란다.

Gemini CLI와 함께 더욱 창조적이고 효율적인 개발 라이프를 즐기길 바란다!

참고문헌

10. 마지막으로

Gemini CLI를 실제로 사용해보니, 첫인상으로는 Google 검색과 연결되어 있다는 점, MCP 연동으로 이미지·동영상·음성 생성에 연결하기 쉽다는 점, 슬래시 명령의 탭 보완 후 실행해주는 등 절묘하게 체험이 좋아서, Claude Code 사용자들 중 일정 수는 이주하게 될 것 같다는 생각이 들었다. 가벼운 개발자들에게는 무료 이용 한도가 있는 것도 반갑다.

gemini --prompt "<URL> <prompt>" 같은 식으로 Google 검색을 파이프라인으로 연결할 수도 있고, 응용 여지는 클 것 같다.

jacking75/gemini-cli-tutorial.md