모든 글

Gemini CLI: 한 가지 작업 따라 하기

Gemini CLI v0.65.0은 터미널에서 제미니 모델과 연동하여 코드 조작, 파일 연산, MCP 서버 확장 기능을 제공하는 오픈소스 AI 에이전트입니다.

마지막 업데이트

메뉴나 지원 기능이 달라졌다면 아래 자료 확인일과 현재 앱 버전을 함께 봐주세요.

앱 · APP
공식 자료를 읽고 정리했어요 · 직접 실행한 후기는 아직 없어요 자료 확인일:

터미널 환경에서 코딩 작업을 수행할 때, 별도의 그래픽 인터페이스 없이 대화형으로 AI 모델과 소통하고 싶었던 적이 있으신가요? 이번 글에서는 터미널 안에서 직접 제미니 모델의 강력한 기능을 활용할 수 있도록 돕는 오픈소스 AI 에이전트인 Gemini CLI를 살펴보려고 해요. 특히 로컬 코드베이스를 에디트 요청 없이 분석하는 구체적인 실습 작업을 따라 하며, 문서화된 비대화형 명령어를 어떻게 활용하는지 자세히 알아볼게요. 공식 문서에 기반한 내용을 바탕으로 차근차근 설명해 드릴 테니 개발 환경을 점검하면서 함께 확인해 보세요.

이 글은 Gemini CLI v0.65.0 공식 릴리스를 다뤄요. 공식 릴리스 기록의 공개일은 2026-10-20(UTC)이고, 자료 확인일은 2026-10-21이에요.

이 가이드는 공식 문서와 릴리스 정보를 바탕으로 작성된 documentation-based 가이드이며, 실제 개발 환경에서 직접 코드를 실행해 본 후기가 아니라는 점을 미리 알려드려요. 이 문서에서 다루는 내용은 개인용 구글 계정을 사용할 때 적용되는 무료 티어 규정과 오픈소스 저장소의 가이드라인을 기준으로 해요. 유료 크레딧이나 API 키 관리 방식에 따라 비용 정책이 달라질 수 있으므로, 앱 자체의 오픈소스 사용성과 모델 호출에 따른 요금 구조를 구분해 주세요 F3, D2. 그럼 실습을 시작하기 위해 어떤 준비물이 필요한지 다음 섹션에서 살펴볼게요.

계정과 실행 환경을 먼저 준비해요

실습을 원활하게 진행하기 위해서는 몇 가지 준비물과 시스템 환경을 갖춰야 해요. 먼저 Node.js 환경이 설치되어 있어야 하며, npx를 통해 별도 설치 과정 없이 즉시 실행하거나 npm을 통해 전역으로 설치할 수 있어요. 또한 개인용 구글 계정을 이용해 로그인하거나, Gemini API 키 또는 Vertex AI 환경 변수를 미리 설정해 두어야 해요. 버전 0.65.0 릴리스에서는 신뢰할 수 없는 폴더 내에서 읽기 전용 워크스페이스 설정을 강제하는 보안 수정 사항이 포함되어 있으므로 이 수정이 반영된 버전인지 확인해 주세요 F2. 이러한 준비가 완료되었다면 대상 프로젝트 폴더에서 다음 명령을 실행할 준비가 끝난 셈이에요 D2, F2.

분석할 프로젝트 폴더를 선택해요

터미널에서 작업을 시작하려면 대상 프로젝트 디렉토리로 이동한 뒤 기본 명령어를 입력하면 되어요. 사용자는 현재 디렉토리에 맞춰 gemini 명령을 실행하여 대화형 모드를 시작할 수 있어요. 하지만 이번 실습의 핵심은 스크립트나 자동화 작업에 유용한 비대화형 모드를 활용하는 것이에요. 대화형 인터페이스 대신 -p 플래그를 사용하면 터미널 창을 복잡하게 오가지 않고도 프롬프트를 바로 전달하여 결과를 얻을 수 있어요. 이 방식은 반복적인 코드 분석 작업이나 CI/CD 파이프라인에서 사용할 수 있도록 문서에 안내돼 있어요 F4, F7.

예시 입력: 같은 질문으로 코드 구조를 요청해요

구체적인 실습을 위해 코드베이스 분석 작업을 수행하는 입력 방법을 살펴볼게요. 비대화형 모드에서 구조화된 JSON 출력을 얻기 위해 --output-format json 플래그를 함께 조합하여 사용할 수 있어요. 이때 문서에 명시된 공통 예시 입력 문자열을 그대로 사용하는 것이 중요해요. 터미널 창에 입력할 예시 입력과 명령어는 텍스트 펜스 블록으로 아래와 같이 정리해 둘게요. 이 예시 입력은 Aider 등의 다른 터미널 기반 도구 비교에서도 동일하게 활용되는 기준점이므로 정확하게 타이핑해 주세요.

같은 입력으로 반복하거나 다른 도구와 비교할 때 사용할 질문이에요.

Explain the architecture of this codebase.

문서의 -p와 JSON 출력 옵션을 조합하고, 셸의 >로 결과를 저장하는 입력 예시는 다음과 같아요 F7. >와 파일명은 터미널의 출력 저장 방법이며 앱의 내보내기 메뉴가 아니에요.

gemini -p "Explain the architecture of this codebase." --output-format json > architecture.json

예상 결과: JSON 형식의 터미널 출력이에요

명령어를 실행한 뒤에는 터미널 화면에 출력되는 결과물을 확인하는 과정이 필요해요. 일반적인 텍스트 응답 대신 --output-format json 플래그를 지정했기 때문에, 모델의 응답은 파싱하기 쉬운 구조화된 JSON 형식으로 터미널 표준 출력에 나타나요. 만약 이 결과를 나중에 다시 확인하거나 스크립트 내에서 재사용하고 싶다면, 일반적인 쉘 리디렉션 기법을 사용하여 결과를 파일로 저장할 수 있어요. 이때 생성된 파일은 네이티브 프로젝트 내보내기 기능이 아니라 단순한 쉘 명령어 리디렉션으로 만들어진 파일임을 구분해 주세요 F7.

완료 조건: 저장 파일을 다시 열고 확인해요

결과물을 파일로 저장하고 검증하는 방법은 다음과 같이 진행할 수 있어요. 터미널 리디렉션을 이용해 명령어 출력을 architecture.json 이라는 파일로 저장한 뒤, 에디터나 뷰어를 통해 해당 파일을 다시 열어 구조가 올바르게 작성되었는지 확인해 보세요. 예상 결과로 생성되는 architecture.json 파일 안에는 코드베이스의 아키텍처 설명이 유효한 JSON 객체 형태로 담겨 있어야 해요. 완료 조건은 터미널에서 오류 없이 JSON 응답이 반환되고, architecture.json 파일이 정상적으로 생성되어 내부 내용을 문제없이 읽을 수 있는 상태가 되는 것이에요.

공식 README는 JSON 출력 옵션을 안내하지만, 여기 확보한 자료만으로 모든 응답 필드 이름과 구조를 확정하지는 않았어요 D2. 그래서 임의의 JSON 예시를 실제 응답처럼 제시하지 않고, 저장된 내용이 유효한 JSON으로 열리는지와 설명 대상이 선택한 프로젝트인지 확인하는 것으로 범위를 잡아요.

인증·설정 문제와 출력 형식을 구분해요

작업을 진행하다 보면 예기치 않은 오류나 문제 상황에 부딪힐 수 있어요. 예를 들어 인증 정보가 올바르지 않거나 API 요청 한도를 초과한 경우 오류 메시지가 발생할 수 있으므로 구글 계정 로그인 상태나 API 키 설정을 다시 한번 점검해 주세요. v0.65.0의 수정 대상은 신뢰하지 않는 폴더의 워크스페이스 설정이에요 F2. 폴더 신뢰 설정과 인증은 별도로 확인해 주세요. --output-format stream-json은 실시간 이벤트를 줄 단위 JSON으로 받는 별도 출력 방식이에요 D2. 이를 선택하면 출력 형식이 달라지므로 이번에 저장한 단일 JSON 결과와 섞어서 검사하지 않아요. 인증이나 요청 한도 문제를 고치는 방법으로 대신 쓰지는 마세요.

Gemini CLI documentation reading guide

BumbleV가 만든 자료 안내 그림이며 실제 앱 화면이나 실행 결과가 아니에요. 그림의 근거가 된 공식 발표 · CC BY 4.0 · 2026-10-21

소개

한 가지 작업 따라 하기

공식 문서로 비교하기

Gemini CLI developer interface example
개발자 저장소에 공개된 실제 화면 예시예요. 본문의 작업을 직접 실행한 결과는 아니며 현재 버전과 화면이 다를 수 있어요. 원본·출처 및 재사용 조건 · 6006c14a4dec · Apache-2.0 · 2026-10-21 · "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. copyright notice that is included in or attached to the work submitted to Licensor for inclusion in the Work by the copyright owner the copyright owner. For the purposes of this definition, "submitted" designated in writing by the copyright owner as "Not a Contribution." 2. Grant of Copyright License. Subject to the terms and conditions of copyright license to reproduce, prepare Derivative Works of, that You distribute, all copyright, patent, trademark, and You may add Your own copyright statement to Your modifications and same "printed page" as the copyright notice for easier

참고 자료