이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Gemini CLI 직접 사용

1. 소개

이 Codelab에서는 Gemini의 기능을 터미널에서 직접 사용할 수 있도록 지원하는 오픈소스 AI 에이전트인 Gemini CLI에 대해 알아봅니다.

Gemini CLI 프로젝트는 오픈소스이며 공개 로드맵은 여기에서 확인할 수 있습니다.

Codelab을 통해 다음과 같은 활동에서 단계별 접근 방식을 사용합니다.

Gemini CLI 설치
기본 구성
Gemini CLI의 도구 및 기본 제공 명령어 살펴보기
GEMINI.md 파일을 통해 Gemini CLI 맞춤설정
Gemini CLI로 몇 가지 사용 사례 살펴보기

필요한 항목

Chrome 웹브라우저
Gmail 계정
Node 20 이상이 설치된 로컬 머신

이 Codelab은 초보자를 포함한 모든 수준의 사용자 및 개발자를 위해 설계되었습니다.

2. 설치

설정을 실행하고 Gemini CLI를 실행하기 전에 폴더를 만들어 보겠습니다. 이 폴더는 이 폴더 내에서 만들 수 있는 모든 프로젝트의 홈 폴더로 사용됩니다. 이는 Gemini CLI가 작동하는 시작점입니다. 필요에 따라 시스템의 다른 폴더도 참조하며 이에 대해서는 나중에 설명합니다.

샘플 폴더 (gemini-cli-projects)를 만들고 아래에 표시된 명령어를 통해 해당 폴더로 이동합니다. 다른 폴더 이름을 사용하려면 그렇게 하세요.

mkdir gemini-cli-projects

해당 폴더로 이동합니다.

cd gemini-cli-projects

Gemini CLI를 실행하려면 다음 방법 중 하나를 사용하면 됩니다.

다음 명령어를 사용하여 실행합니다.

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

먼저 시스템에 Gemini CLI를 전역적으로 설치할 수 있습니다. 이를 수행할 수 있는 관리자 권한이 있는지 확인합니다.

npm install -g @google/gemini-cli

그런 다음 다음 명령어를 사용하여 실행합니다.

gemini

위의 방법 중 하나를 통해 Gemini CLI를 실행했다면 테마 선택을 묻는 다음 화면이 표시됩니다. 다음 중 원하는 것을 선택하세요.

이 옵션을 선택하면 인증 방법을 묻는 메시지가 표시됩니다. 이 실습에서는 개인 Google 계정을 사용하고 Google 또는 Google Workspace 관련 계정은 사용하지 않는 것이 좋습니다. 이 무료 라이선스를 통해 Gemini 2.5 Pro와 100만 토큰 컨텍스트 윈도우를 사용할 수 있습니다. 무료 등급에서는 분당 60개의 모델 요청과 일일 1,000개의 요청을 무료로 허용합니다.

Google 계정에 제공되는 현재 무료 할당량에 도달한 경우 Gemini API 키 또는 Google Cloud Vertex AI를 사용할 수 있습니다. 이 경우 프로젝트 ID와 해당 프로젝트의 위치 이름이 필요합니다. 다른 인증 방법을 사용하려면 문서의 인증 섹션을 참고하세요.

Enter를 클릭합니다. 그러면 브라우저에서 Google 인증 페이지가 열립니다. Google 계정으로 인증을 진행하고 약관에 동의하면 인증이 완료된 후 Gemini CLI가 준비되어 명령을 기다리고 있음을 확인할 수 있습니다. 샘플 스크린샷은 아래와 같습니다.

/help (슬래시)를 입력하면 아래와 같이 다양한 명령어와 단축키가 표시됩니다.

Gemini CLI와의 첫 번째 상호작용

상자에 첫 번째 메시지를 입력합니다. 다음과 같은 쿼리를 입력합니다.

쿼리 결과로 호출된 GoogleSearch 도구 (Gemini CLI의 내장 도구)가 표시됩니다. 이것은 Gemini CLI의 강력한 내장 도구 중 하나인 GoogleSearch를 이미 사용한 흥미로운 방법입니다. 이 도구는 웹에서 가져온 정보를 기반으로 대답을 제공합니다. 도구에 대한 자세한 내용은 다음 섹션에서 살펴보겠습니다.

지금은 Gemini CLI를 종료하겠습니다. /quit 명령어를 사용하거나 대화형 Gemini CLI 터미널 세션에서 Ctrl-C를 두 번 실행하면 됩니다.

Gemini CLI 맞춤설정 파일 : settings.json

Gemini CLI를 처음 시작했을 때 테마와 인증 방법을 선택하라는 메시지가 표시되었습니다. 이후 Gemini CLI를 실행할 때는 테마와 인증 방법을 다시 선택하라는 메시지가 표시되지 않습니다. 즉, 어딘가에 지속되고 사용되는 파일은 settings.json이라고 하며 Gemini CLI를 맞춤설정하는 방법입니다.

설정은 다음 우선순위에 따라 적용됩니다.

작업공간: .gemini/settings.json (사용자 및 시스템 설정보다 우선함)
사용자: ~/.gemini/settings.json (시스템 설정 재정의)
시스템: /etc/gemini-cli/settings.json (모든 사용자에게 적용됨)

테마를 선택할 때 사용자 설정에 설정을 저장하도록 요청했습니다. ~/.gemini folder을 방문하면 settings.json 파일이 표시됩니다.

내 settings.json 파일은 아래와 같습니다. 다른 테마를 선택한 경우 해당 이름이 표시됩니다.

{
  "theme": "Default",
  "selectedAuthType": "oauth-personal"
}

3. Gemini CLI 명령어 매개변수

Gemini CLI를 시작할 때 제공할 수 있는 몇 가지 명령줄 매개변수가 있습니다. 옵션의 전체 목록을 가져오려면 아래와 같이 --help를 사용하면 됩니다.

gemini --help

그러면 사용 가능한 전체 옵션이 표시됩니다. 여기에서 문서를 확인하세요.

몇 가지를 살펴보겠습니다. 첫 번째 방법은 Pro 또는 Flash 모델을 사용하도록 Gemini CLI를 구성하는 것입니다. 현재 이 실습을 작성하는 시점에는 이 두 모델만 지원됩니다. 기본적으로 Gemini 2.5 Pro 모델이 사용되지만 Flash 모델을 사용하려면 아래와 같이 -m 매개변수를 통해 Gemini CLI를 시작할 때 사용하면 됩니다.

gemini -m "gemini-2.5-flash"

위와 같은 방식으로 시작하면 아래와 같이 Gemini CLI 터미널의 오른쪽 하단에서 모델을 확인할 수 있습니다.

비대화형 모드

비대화형 모드에서 Gemini CLI를 실행하는 것도 흥미로운 옵션입니다. 즉, 프롬프트를 직접 제공하면 Gemini CLI 대화형 터미널이 열리지 않고 바로 응답합니다. 스크립트 또는 기타 자동화 프로세스의 일부로 자동화된 방식으로 Gemini CLI를 사용하려는 경우에 매우 유용합니다. 아래와 같이 -p 매개변수를 사용하여 Gemini CLI에 프롬프트를 제공합니다.

gemini -p "What is the gcloud command to deploy to Cloud Run"

후속 질문으로 대화를 이어갈 수는 없습니다.

4. Gemini CLI - 기본 제공 도구

Gemini CLI에는 기본 제공 도구 세트가 함께 제공되며 도구 문서에는 'Gemini 모델은 이러한 도구를 사용하여 로컬 환경과 상호작용하고, 정보에 액세스하고, 작업을 실행합니다. 이러한 도구는 CLI의 기능을 향상시켜 텍스트 생성을 넘어 다양한 작업을 지원할 수 있습니다.'

현재 내장 도구 목록을 가져오려면 아래와 같이 /tools 명령어를 호출하면 됩니다.

가장 먼저 떠올려야 할 점은 Gemini CLI가 원할 때 이러한 도구를 간단히 호출할 수 있는지 묻는 것입니다. 로컬 시스템에 쓰거나, 외부 시스템에서 읽거나, 외부 네트워크로 이동하는 등 민감한 작업의 경우 기본 대답은 아니요입니다.

CLI를 시작할 때 --yolomode가 제공되지만 사용하지는 않습니다. Gemini CLI에서 선택한 도구를 실행할 권한을 요청하는 메시지가 표시됩니다. 권한을 거부하거나, 한 번 실행하도록 허용하거나, 항상 실행되도록 전체 권한을 부여할 수 있습니다. 모든 것을 완전히 제어할 수 있어야 합니다.

Gemini CLI가 실행할 내장 도구 중 하나를 선택하고 모든 작동 방식을 잘 이해할 수 있는 프롬프트를 입력해 보겠습니다.

전 세계의 최신 금융 뉴스를 확인하고 Gemini CLI를 실행한 로컬 작업 디렉터리의 파일에 저장하고 싶습니다. 다음과 같은 프롬프트를 입력합니다.

Search for the latest headlines today in the world of finance and save them in a file named finance-news-today.txt

잠시 동안 무엇을 해야 하는지 상상해 보세요. 이상적으로는 Google 검색을 실행하여 금융 뉴스를 제공할 수 있는 관련 정보 소스에서 뉴스를 가져와야 합니다. 그런 다음 콘텐츠가 포함된 finance-news-today.txt라는 파일을 만들어야 합니다 (권한이 필요한 로컬 시스템의 쓰기 작업).

어떤 일이 일어나는지 살펴보겠습니다 (머신에서도 동일한 작업을 진행해야 함).

가장 먼저 GoogleSearch 도구를 호출하여 웹을 검색합니다.

검색이 완료되면 아래와 같이 데이터를 가져옵니다.

이 작업이 완료되면 파일에 쓸 준비가 되고 WriteFile 도구를 사용하지만 민감한 작업 (쓰기)이므로 권한을 요청합니다. '한 번만 허용', '항상 허용' 등 권한 유형을 결정할 수 있습니다. 여기서는 '한 번만 허용'을 선택합니다.

그러면 정보가 파일에 기록되고 아래에 성공 메시지가 표시됩니다.

파일이 작성되었는지 확인하려면 어떻게 해야 하나요? @file를 사용하여 콘텐츠를 읽어 달라고 요청할 수 있습니다. 아래와 같이 프롬프트를 제공합니다. @을 입력하면 현재 폴더의 파일 목록이 표시되고 방금 만든 파일이 표시됩니다. 이 옵션을 선택하고 프롬프트를 제출합니다. 프롬프트는 다음과 같습니다.

read the contents of @finance-news-today.txt

이렇게 하면 필요한 도구 (ReadManyFiles, ReadFile)가 호출되고 콘텐츠가 아래와 같이 표시됩니다.

이때 Gemini CLI 내에서 셸을 직접 사용하는 방법을 알아보는 것도 좋습니다. 메시지 상자에서 !를 눌러 셸 모드로 전환할 수 있습니다. 셸 모드로 전환됩니다. !를 다시 누르거나 ESC 키를 누르면 돌아갈 수 있습니다.

셸 모드에서는 아래와 같이 프롬프트 시작 부분에 !가 표시됩니다.

아래와 같이 pwd 및 ls와 같은 표준 명령어를 사용하여 직접 확인할 수 있습니다.

현재 cat 명령어를 통해 파일의 콘텐츠를 출력할 수 있습니다.

연습: 다음은 시도해 볼 수 있는 간단한 연습입니다. 원하는 RSS 피드를 선택합니다. Gemini CLI에 프롬프트를 제공하여 RSS 피드의 콘텐츠를 가져오고 결과를 특정 방식으로 포맷합니다. 이는 하루를 시작할 때 작업을 자동화하는 좋은 방법입니다.

도움말: Gemini CLI가 WebFetch 도구를 사용하도록 해야 합니다.

5. 모델 컨텍스트 프로토콜 (MCP) 서버 구성

MCP 서버는 모델 컨텍스트 프로토콜을 통해 Gemini CLI에 도구와 리소스를 노출하여 외부 시스템 및 데이터 소스와 상호작용할 수 있도록 하는 애플리케이션입니다. MCP 서버는 Gemini 모델과 로컬 환경 또는 API와 같은 기타 서비스 간의 브리지 역할을 합니다.

MCP 서버를 사용하면 Gemini CLI가 도구를 검색하고 실행할 수 있으므로 데이터베이스, API, 맞춤 스크립트 또는 전문 워크플로와 상호작용하는 등 기본 제공 기능을 넘어 작업을 실행할 수 있도록 Gemini CLI의 기능이 확장됩니다.

Gemini CLI는 맞춤 도구를 검색하고 사용하기 위한 MCP 서버 구성을 지원합니다. Gemini CLI가 실행된 경우 아래와 같이 /mcp 명령어를 통해 구성된 MCP 서버를 확인할 수 있습니다.

MCP 서버를 구성하지 않은 경우 Gemini CLI의 MCP 서버 문서가 실행됩니다.

~/.gemini/settings.json 파일 또는 프로젝트의 루트 디렉터리에서 전역 수준으로 MCP 서버를 구성할 수 있습니다. .gemini/settings.json 파일을 만들거나 엽니다. 파일 내에 아래와 같이 mcpServers 구성 블록을 추가해야 합니다.

"mcpServers": {
    "server_name_1": {},
    "server_name_2": {},
    "server_name_n": {}
 }

각 서버 구성은 다음 속성을 지원합니다 ( 참조 문서).

필수 (다음 중 하나)

command (문자열): Stdio 전송 실행 파일의 경로
url (문자열): SSE 엔드포인트 URL입니다 (예: "http://localhost:8080/sse")
httpUrl (문자열): HTTP 스트리밍 엔드포인트 URL

선택사항

args (string[]): Stdio 전송의 명령줄 인수
headers (객체): url 또는 httpUrl을 사용할 때의 맞춤 HTTP 헤더
env (객체): 서버 프로세스의 환경 변수입니다. 값은 $VAR_NAME 또는 ${VAR_NAME} 구문을 사용하여 환경 변수를 참조할 수 있습니다.
cwd (문자열): Stdio 전송의 작업 디렉터리
timeout(숫자): 요청 제한 시간(밀리초)(기본값: 600,000ms = 10분)
trust (불리언): true인 경우 이 서버의 모든 도구 호출 확인을 우회합니다 (기본값: false).
includeTools (string[]): 이 MCP 서버에서 포함할 도구 이름 목록입니다. 지정된 경우 여기에 나열된 도구만 이 서버에서 사용할 수 있습니다 (허용 목록 동작). 지정하지 않으면 서버의 모든 도구가 기본적으로 사용 설정됩니다.
excludeTools (string[]): 이 MCP 서버에서 제외할 도구 이름 목록입니다. 여기에 나열된 도구는 서버에서 노출되더라도 모델에서 사용할 수 없습니다. 참고: excludeTools가 includeTools보다 우선합니다. 도구가 두 목록에 모두 있으면 제외됩니다.

GitHub를 사용하는 경우 필요할 수 있는 주요 MCP 서버 중 하나를 구성해 보겠습니다. Gemini CLI는 시스템에 있는 git 도구를 호출하며, 대신 해당 도구를 사용하도록 Gemini CLI에 지시할 수도 있습니다. 따라서 명령을 지원하고 실행하는 데 도움이 되지만 시스템에 이러한 도구가 설정되어 있어야 합니다.

GitHub MCP 서버

GitHub 공식 MCP 서버는 노출하는 도구와 이를 구성하는 방법에 관한 충분한 문서를 제공합니다. Gemini CLI는 원격 MCP 서버도 지원하므로 로컬 또는 원격으로 실행할 수 있습니다.

이 튜토리얼에서는 GitHub의 원격 MCP 서버 옵션을 사용합니다. 이를 위해서는 먼저 GitHub의 개인 액세스 토큰 (PAT)이 있어야 합니다.

이러한 서버가 있으면 settings.json 파일에 MCP 서버 객체를 추가해야 합니다. 내 시스템의 전체 settings.json 파일은 아래와 같습니다. 추가 설정이 있을 수 있지만 mcpServers 객체는 아래와 같아야 합니다.

{
  "theme": "Default",
  "selectedAuthType": "oauth-personal",
  "mcpServers": {
       "github": {
            "httpUrl": "https://api.githubcopilot.com/mcp/",
            "headers": {
                "Authorization": "GITHUB_PAT"
            },
            "timeout": 5000
       }
  }
}

Github MCP 서버 구성으로 settings.json를 업데이트한 후 Gemini CLI를 다시 시작하거나 /mcp refresh 명령어를 실행하면 됩니다. 아래 스크린샷은 내 머신에 구성된 GitHub MCP 서버와 이제 Gemini CLI에서 MCP와 함께 사용할 수 있는 다양한 도구를 강조 표시합니다.

GitHub MCP 서버의 도구 중 하나를 호출하는 프롬프트로 시작해 보겠습니다. 다음 프롬프트를 입력합니다.

GitHub MCP 서버에서 올바른 도구를 선택하지만 다른 내장 도구와 마찬가지로 도구를 호출할 명시적 권한을 제공해야 합니다. 출력을 확인해 보세요.

이제 GitHub 프로젝트 중 하나를 사용해야 합니다. 다음과 같이 자연어로 질문을 입력하세요.

<repo-name>을 설명해 줘.
내 로컬 머신에서 <repo-name>을 클론해 줘.
@<파일 이름> 또는 @<디렉터리 이름>을 설명해 줘.
이 저장소의 구성요소에는 무엇이 있나요?
필요한 변경사항을 적용했습니다. 변경사항을 GitHub에 푸시하고 GitHub MCP 서버 도구를 사용하여 이를 수행할 수 있나요?

실습 후반부에서 GitHub MCP 서버를 자세히 다루는 연습이 있습니다.

Context7 MCP 서버

Context7은 LLM 및 AI 코드 편집기에 관한 최신 문서를 제공합니다. 선택한 프레임워크의 최신 문서를 사용하여 LLM에 컨텍스트를 제공하려는 경우 Context7 MCP 서버를 구성하는 것이 좋습니다.

Context7 홈페이지에 라이브러리가 표시되어 있는지 확인합니다.

settings.json 파일에 추가해야 하는 MCP 서버는 다음과 같습니다.

"context7": {
      "httpUrl": "https://mcp.context7.com/mcp"
    }

MCP 서버가 구성되고 Gemini CLI가 MCP 서버와 함께 로드되면 아래와 같이 Context7 도구를 볼 수 있습니다.

이제 프롬프트에서 구체적으로 지정하여 특정 XYZ 프레임워크를 사용하여 애플리케이션이나 코드 스니펫을 생성할 때 최신 문서를 위해 Context7를 사용하도록 Gemini CLI에 요청할 수 있습니다.

다음은 Google의 에이전트 개발 키트 (ADK)를 사용하여 에이전트를 작성하려는 프롬프트의 예입니다. 프롬프트에서 Context7 MCP 서버를 통해 동일한 문서를 조회하도록 지정하고 있습니다.

I am working on coding an Agent using the Agent Development Kit (ADK) from Google. I would like to know how to create the LLMAgent in Python. Use Context7 for the latest documentation on ADK and specifically use /google/adk-python, /google/adk-docs and adk.wiki

수신된 출력은 다음과 같습니다.

Google Slides MCP 서버

https://github.com/matteoantoci/google-slides-mcp의 GitHub 프로젝트는 Google Slides API와 상호작용하기 위한 MCP 서버를 제공합니다. 이를 통해 프로그래매틱 방식으로 Google Slides 프레젠테이션을 만들고, 읽고, 수정할 수 있습니다.

MCP 서버를 구성하는 단계는 프로젝트에 나와 있습니다. 서버를 빌드하고, Google Cloud 프로젝트 및 OAuth 2.0 토큰을 구성한 다음, settings.json 파일에서 MCP 서버를 구성하는 Node.js 환경이 필요합니다.

설정이 완료되면 다음과 같은 프롬프트를 실행할 수 있습니다.

'web_url'에서 최신 정보를 추출하고 핵심 사항으로 요약한 다음 'my_presentation'이라는 프레젠테이션을 만들어 줘.

한번 사용해 보세요.

MCP 서버 더보기

다음은 관심이 있을 수 있는 MCP 서버의 추가 목록입니다.

Firebase MCP 서버
Google 생성형 AI 미디어 서비스 (Imagen, Veo, Lyria)
데이터베이스용 MCP 도구 상자 (Firestore, BigQuery, Google Cloud 데이터베이스 사용)
Google Workspace MCP 서버 (Docs, Sheets, Calendar, Gmail과 호환)

위 MCP 서버 설정에 관한 안내는 이 블로그 게시물에 게시되어 있습니다.

6. 시도해 볼 사용 사례

Gemini CLI는 개발자와 비개발자 모두에게 적용되는 광범위한 사용 사례에 적용할 수 있습니다. 다음은 몇 가지 시나리오이며 관심 분야에 따라 일부 또는 전체를 시도해 볼 수 있습니다.

이러한 각 경우에 프롬프트가 제공됩니다. Gemini CLI를 실행할 때 -p 매개변수를 통해 Gemini CLI 대화형 모드 또는 비대화형 모드에서 이를 자유롭게 사용해 볼 수 있습니다.

파일/폴더 정리

필요에 따라 Gemini CLI를 사용하여 다양한 폴더의 유형에 따라 파일을 정리할 수 있습니다. 컴퓨터에서 .txt, .png, .jpg, .pdf, .mp4 등의 파일이 여러 개 있는 폴더로 이동합니다. 바탕 화면 또는 다운로드 폴더일 가능성이 큽니다.

해당 폴더로 이동하여 Gemini CLI를 시작합니다. 먼저 이미지, 문서, 동영상과 같은 여러 폴더를 만들어 달라고 요청한 다음 폴더에 있는 파일을 정리해 달라고 요청합니다.

Gemini CLI는 명령어를 실행하기 전에 권한을 요청하는 경우가 많으며, 특히 파일 시스템을 수정하는 명령어 (예: 파일 쓰기, 이동, 삭제)의 경우 더욱 그렇습니다. 권한을 부여하기 전에 항상 이러한 메시지를 주의 깊게 검토하세요. 이는 안전망과 같습니다.

Create the following folders "Images","Documents","Videos"

그런 다음 다음 프롬프트를 입력합니다.

Go through all the files in this folder and then organize them by moving all the files ending with .jpg, .jpeg, .gif into the "Images" folder. Move all ".txt" files into the "Documents" folder. Move all the ".mp4" files in the "Videos" folder.

기타 정리 시나리오 (프롬프트는 각 시나리오 옆에 제공됨):

요약: 'Documents' 폴더의 각 문서에 대해 문서의 주요 사항을 3문장으로 요약한 'summary_ORIGINAL_FILENAME.txt'라는 txt 파일을 동일한 폴더에 만듭니다.
유형별 분류: 이 디렉터리의 모든 PDF 및 DOCX 파일을 스캔합니다. 이름이나 콘텐츠에 '인보이스'가 포함된 모든 파일을 '재무/인보이스' 폴더로 이동해 줘. '영수증'이 포함된 파일을 '재무/영수증'으로 이동합니다. 다른 .docx 파일은 '보고서'에 저장됩니다.
주요 정보 추출 (및 '태그'): 'Financial/Invoices' 폴더에 있는 각 PDF 파일의 콘텐츠를 읽습니다. 날짜를 찾은 경우 YYYY-MM-DD 형식으로 날짜를 포함하도록 파일 이름을 바꿉니다.예를 들면 다음과 같습니다. ‘invoice_2025-07-26_original_name.pdf'.