1. 소개
이 Codelab에서는 Gemini의 기능을 터미널에서 바로 사용할 수 있도록 지원하는 오픈소스 AI 에이전트인 Gemini CLI에 대해 알아봅니다.
학습할 내용
- Gemini CLI 설치 및 구성
- Gemini CLI에서 도구, 기본 제공 명령어 살펴보기 및 MCP 서버 구성
GEMINI.md파일을 통해 Gemini CLI 맞춤설정- Gemini CLI를 사용한 몇 가지 사용 사례 살펴보기
필요한 항목
이 Codelab은 Gemini CLI가 사전 설치된 Google Cloud Shell에서 처음부터 끝까지 진행할 수 있습니다.
자체 머신에서 작업하려면 Gemini CLI를 로컬로 설치하는 섹션을 참고하세요.
다음이 필요합니다.
- Chrome 웹브라우저
- Gmail 계정
이 Codelab은 초보자를 포함한 모든 수준의 사용자와 개발자를 대상으로 합니다. Codelab의 사용 사례는 개발자 작업과 비개발자 작업으로 분류되었습니다. 개발자 사용 사례에서는 Gemini CLI로 바이브 코딩하는 방법과 GitHub 저장소에서 코드 설명/이해, 문서 생성, 문제 해결 등 일반적인 개발 작업을 수행하는 방법을 보여줍니다. Codelab에서 이러한 사용 사례를 완료하는 것이 좋습니다. 끝에는 개발자 중심이 아닌 여러 일상적인 작업을 다루는 선택사항 섹션이 있습니다.
2. 시작하기 전에
프로젝트 만들기
- Google Cloud 콘솔의 프로젝트 선택기 페이지에서 Google Cloud 프로젝트를 선택하거나 만듭니다.
- Cloud 프로젝트에 결제가 사용 설정되어 있어야 하므로 프로젝트에 결제가 사용 설정되어 있는지 확인하는 방법을 알아보세요.
- bq가 미리 로드되어 제공되는 Google Cloud에서 실행되는 명령줄 환경인 Cloud Shell을 사용합니다. Google Cloud 콘솔 상단에서 Cloud Shell 활성화를 클릭합니다.
- Cloud Shell에 연결되면 다음 명령어를 사용하여 이미 인증되었는지, 프로젝트가 프로젝트 ID로 설정되었는지 확인합니다.
gcloud auth list
- Cloud Shell에서 다음 명령어를 실행하여 gcloud 명령어가 프로젝트를 알고 있는지 확인합니다.
gcloud config list project
- 프로젝트가 설정되지 않은 경우 다음 명령어를 사용하여 설정합니다.
gcloud config set project <YOUR_PROJECT_ID>
3. 설치
설정을 진행하고 Gemini CLI를 실행하기 전에, 추후 모든 프로젝트의 홈 폴더로 사용할 폴더를 만들어 보겠습니다. 홈 폴더는 Gemini CLI가 작동할 때 가장 먼저 참고하는 곳입니다. 물론 이 외에도 필요한 경우에는 사용자의 시스템에 있는 다른 폴더도 참고합니다.
샘플 폴더 (gemini-cli-projects)를 만들고 아래 표시된 명령어를 통해 해당 폴더로 이동합니다. 다른 폴더 이름을 사용하려면 그렇게 하세요.
mkdir gemini-cli-projects
해당 폴더로 이동합니다.
cd gemini-cli-projects
gemini 명령어를 통해 Gemini CLI를 직접 실행할 수 있습니다.
다음 섹션 (settings.json을 통한 Gemini CLI 구성)으로 바로 이동하세요.
Gemini CLI를 로컬로 설치하려면 아래 안내를 따르세요. Gemini CLI는 Cloud Shell 및 Cloud Workstations에 사전 설치되어 있습니다.
첫 번째 단계는 머신에 Node 20 이상을 설치하는 것입니다. 이 작업이 완료되면 다음 방법 중 하나를 통해 Gemini CLI를 설치하고 실행할 수 있습니다.
- 먼저 시스템에 Gemini CLI를 전역적으로 설치할 수 있습니다. 이 단계를 수행하려면 관리자 액세스 권한이 필요할 수 있습니다.
# option 1: install Gemini CLI
npm install -g @google/gemini-cli
# .. and then run
gemini
- 다음 명령어를 사용하여 실행합니다.
# option 2: run without installing Gemini CLI
npx https://github.com/google-gemini/gemini-cli
다음을 실행하여 CLI가 설치되었는지 확인할 수 있습니다.
gemini --version
위의 방법 중 하나를 통해 Gemini CLI를 실행한 경우, 처음 실행할 때 테마를 선택하라는 메시지가 표시될 수 있습니다. 이 경우 기본 테마를 사용하거나 원하는 테마를 선택할 수 있습니다.
다음으로 중요한 것은 인증입니다. 인증 방법을 묻는 메시지가 표시됩니다. 이 실습에서는 개인 Google 계정을 사용하고 Google 또는 Google Workspace 관련 계정은 사용하지 않는 것이 좋습니다.
Google 계정에 제공되는 현재 무료 할당량의 한도에 도달한 경우 Gemini API 키 또는 Google Cloud Vertex AI를 사용할 수 있습니다. 이 경우 프로젝트 ID와 해당 프로젝트의 위치 이름이 필요합니다. 다른 인증 방법을 사용하려는 경우 문서의 인증 섹션을 참고하세요.
Enter를 클릭합니다. 그러면 브라우저에서 Google 인증 페이지가 열립니다. Google 계정으로 인증을 진행하고 약관에 동의합니다. 인증이 완료되면 Gemini CLI가 준비되어 명령어가 입력되기를 기다립니다.
샘플 스크린샷은 아래에 나와 있습니다.
여기서는 Vertex AI 옵션을 선택했지만 개인 계정일 수도 있습니다. Gemini 2.5 모델이 선택되어 있습니다 (오른쪽 하단에 표시됨). /model 명령어를 사용하여 언제든지 특정 모델을 선택할 수 있습니다.
4. settings.json을 통한 Gemini CLI 구성
Cloud Shell을 선택하여 Gemini를 실행하면 Gemini CLI의 기본 테마와 인증 방법이 미리 선택되고 구성되어 있습니다.
머신에 Gemini CLI를 설치하고 처음 실행한 경우 테마를 선택한 다음 인증 방법을 선택했습니다.
이제 Gemini CLI를 후속 실행할 때 테마와 인증 방법을 다시 선택하라는 메시지가 표시되지 않습니다. 즉, 어딘가에 유지되고 사용되는 파일은 settings.json이라고 하며 Gemini CLI를 맞춤설정하는 방법입니다.
설정은 다음 우선순위에 따라 적용됩니다 (Cloud Shell에서는 사용자 설정만 사용할 수 있음).
- 시스템:
/etc/gemini-cli/settings.json(모든 사용자에게 적용되며 사용자 및 워크스페이스 설정을 재정의함) - 작업공간:
.gemini/settings.json(사용자 설정을 재정의함) - 사용자:
~/.gemini/settings.json
Windows 사용자: %USERPROFILE%.gemini\settings.json (일반적으로 C:\Users<YourUsername>.gemini\settings.json으로 확장됨)
시스템: %ProgramData%\gemini-cli\settings.json (일반적으로 C:\ProgramData\gemini-cli\settings.json으로 확장됨)
Mac 사용자: ~/.gemini/settings.json(/Users/<YourUsername>/.gemini/settings.json으로 확장됨)
시스템: /etc/gemini-cli/settings.json
테마를 선택할 때 사용자 설정에 설정을 저장하도록 선택한 경우 ~/.gemini folder을 방문하면 settings.json 파일이 표시됩니다.
내 settings.json 파일은 아래와 같습니다. 다른 테마를 선택한 경우 해당 이름이 표시됩니다.
{
"security": {
"auth": {
"selectedType": "oauth-personal" or "cloud-shell"
}
},
"ui": {
"theme": "Default"
}
}
5. Gemini CLI와의 첫 번째 상호작용
Gemini CLI를 시작하고 아래와 같이 첫 번째 쿼리를 입력합니다.
Give me a famous quote on Artificial Intelligence and who said that?
예상되는 대답은 다음과 같습니다.
> Give me a famous quote on Artificial Intelligence and who said that?
✦ "The only way to do great work is to love what you do." - Steve Jobs (While not directly about AI, it's a famous quote related to technology and innovation, which underpins AI development.)
Alternatively:
"The development of full artificial intelligence could spell the end of the human race." - Stephen Hawking
Gemini CLI와 Gemini CLI가 지원하는 여러 명령어에 대해 빠르게 알아보는 한 가지 방법은 /help (정방향 슬래시)를 입력하는 것입니다. 그러면 다양한 명령어와 키보드 단축키가 표시됩니다.
지금은 Gemini CLI를 종료하겠습니다. /quit 명령어를 사용하거나 대화형 Gemini CLI 터미널 세션에서 Ctrl-C를 두 번 실행하면 됩니다. Gemini CLI를 종료하면 세션, 모델 사용량, 기타 측정항목에 관한 유용한 정보를 제공하는 세션 통계가 표시됩니다.
6. Gemini CLI - 명령어 매개변수
Gemini CLI를 시작할 때 제공할 수 있는 명령줄 매개변수가 몇 개 있습니다. 옵션의 전체 목록을 가져오려면 아래와 같이 --help을 사용하면 됩니다.
gemini --help
사용 가능한 전체 옵션이 표시됩니다. 여기에서 문서를 확인하세요.
몇 가지를 살펴보겠습니다. 첫 번째 방법은 특정 Gemini 모드를 사용하도록 Gemini CLI를 구성하는 것입니다. 현재 이 실습을 업데이트하는 시점에 지원되는 모델 목록은 다음과 같습니다. 특정 모델을 사용하려면 아래와 같이 -m 매개변수를 통해 Gemini CLI를 시작할 때 지정하면 됩니다.
gemini -m "gemini-2.5-flash"
위와 같은 방식으로 시작하면 Gemini CLI 터미널의 오른쪽 하단에서 모델을 확인할 수 있습니다.
Gemini CLI 애플리케이션에 있으면 /model 명령어를 사용하여 모델을 선택할 수 있는 대화상자를 열 수 있습니다. 아래에 샘플 실행이 표시되어 있습니다. 요구사항과 제공된 안내에 따라 모델을 계속 전환하여 복잡성과 비용 관리 필요성에 따라 작업에 적합한 모델을 선택할 수 있습니다.
비대화형 모드
Gemini CLI를 비대화형 모드로 실행하는 옵션도 있습니다. 비대화형 모드로 실행하면 Gemini CLI 대화형 터미널을 열지 않아도 사용자가 프롬프트를 입력하면 Gemini가 프롬프트에 대답합니다. 이 옵션은 스크립트나 그 밖의 자동화 프로세스의 일환으로 Gemini CLI를 자동화된 방식으로 사용하려는 경우에 유용합니다. 아래와 같이 -p 매개변수를 사용하여 Gemini CLI에 프롬프트를 제공합니다.
gemini -p "What is the gcloud command to deploy to Cloud Run"
후속 질문으로 대화를 이어갈 수 없다는 점에 유의하세요. 이 모드에서는 WriteFile을 비롯한 도구를 승인하거나 셸 명령어를 실행할 수도 없습니다.
-p 매개변수를 누락하고 다음과 같이 제공하면 프롬프트와 함께 Gemini CLI가 열리고 그 안에서 계속됩니다.
gemini "What is the gcloud command to deploy to Cloud Run"
7. Gemini CLI - 기본 제공 도구
Gemini CLI에는 기본 제공 도구 모음이 함께 제공되며 도구 문서에는 'Gemini 모델은 이러한 도구를 사용하여 로컬 환경과 상호작용하고, 정보에 액세스하고, 작업을 실행합니다. 이러한 도구는 CLI의 기능을 향상하여 텍스트 생성 외에도 다양한 작업을 지원할 수 있도록 합니다.'
현재 기본 제공 도구 목록을 가져오려면 다음과 같이 /tools 명령어를 호출하세요.
Available Gemini CLI tools:
- Activate Skill (activate_skill)
- Ask User (ask_user)
- Edit (replace)
- Enter Plan Mode (enter_plan_mode)
- FindFiles (glob)
- GoogleSearch (google_web_search)
- Invoke Subagent (invoke_agent)
- List Background Processes (list_background_processes)
- Read Background Output (read_background_output)
- ReadFile (read_file)
- ReadFolder (list_directory)
- SearchText (grep_search)
- Shell (run_shell_command)
- Update Topic Context (update_topic)
- WebFetch (web_fetch)
- WriteFile (write_file)
가장 먼저 떠올려야 할 점은 Gemini CLI가 원한다면 언제든지 이러한 도구를 호출할 수 있는지 묻는 것입니다. 로컬 시스템에 쓰기, 외부 시스템에서 읽기, 외부 네트워크로 이동하기 등과 같은 민감한 작업을 수행할 때는 기본적으로 아니요라고 대답합니다.
CLI를 시작할 때 --yolo를 사용할 수 있긴 하지만 이는 일반적으로 권장되는 방식이 아닙니다. 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이라는 파일을 만들어야 합니다 (권한이 필요한 로컬 시스템의 쓰기 작업).
어떤 일이 일어나는지 살펴보겠습니다 (머신에서 동일한 작업을 진행해야 함).
Gemini CLI는 먼저 GoogleSearch 도구를 호출하여 웹을 검색하고 결과를 가져옵니다.
Searching for Finance News:
I will first search for the latest finance headlines and then save them to a file.
✓ GoogleSearch Searching the web for: "latest finance headlines"
→ Search results for "latest finance headlines" returned.
Saving Finance News: I will now save the finance headlines to the file 'finance-news-today.txt'.
이 작업을 마치면 검색한 정보를 파일에 쓸 준비가 되고 WriteFile 도구를 사용합니다. 그러나 쓰기는 민감한 작업이므로 사용자에게 권한을 요청합니다. 사용자는 권한 유형(예: allow once, allow always 등)을 정할 수 있습니다. 지금은 allow once를 선택하세요.
그러면 Gemini CLI가 이 정보를 파일에 쓰고 다음과 같이 성공 메시지를 출력합니다.
✦ I have saved the latest finance news to finance-news-today.txt.
Finance News Saved: The task is complete.
파일이 작성되었는지 확인하려면 어떻게 해야 하나요? @file를 사용하여 콘텐츠를 읽어 달라고 요청할 수 있습니다. @을 입력하면 현재 폴더에 있는 파일 목록이 표시되고 방금 생성된 파일이 표시됩니다. 선택하고 프롬프트를 제출합니다. 프롬프트는 다음과 같습니다.
read the contents of @finance-news-today.txt
이렇게 하면 필요한 도구 (ReadManyFiles, ReadFile)가 호출되고 콘텐츠가 아래와 같이 표시됩니다.
✓ ReadManyFiles Attempting to read files from finance-news-today.txt → Read 1 file(s)
Topic: Summarizing the financial news headlines.
✦ The latest finance headlines as of May 15, 2026, include:
Global Markets & Economy:
* The Dow Jones Industrial Average surpassed 50,000 for the first time, driven by strong earnings from Cisco
Systems and a 2% rise in Nasdaq due to tech stocks.
* Inflation concerns are growing, hinting at potential Fed interest rate hikes.
* Kevin Warsh has been confirmed as the new Federal Reserve head.
* A "constructive" U.S.-China summit took place in Beijing between President Trump and President Xi, with
markets watching for impacts from proposed tariffs.
Corporate & Tech News:
<REST