Gemini CLI (2) - 내장도구 사용 방법 (Gemini CLI 기초 - gemini 기본 사용 방법)

안녕하세요! 갓대희 입니다. :-)

이전 포스팅에서 Gemini CLI 설치방법, CLI 명령어에 대해 알아 보았는데, 

몇가지 별도의 세션에서 다룰만한 내용들이 있어 별도의 세션으로 빼보았다. 

 

그래서 해볼 오늘의 주제는 Gemini CLI의 내장 도구이다. 😊

파일 정리나 데이터 수집 작업에을 예제로 한번 진행해 보려고 한다. 나양한 방법으로 gemini cli를 활용해보자. 

 

Gemini CLI 내장 도구 체험기
간단히 체험 후 써본 후기 - ReadFolder부터 멀티모달까지 살펴보자.

현 시점 내 버전은 다음과 같다 : 0.1.13

 

글을 잘못 작성한 것들이 있나 확인차 들어왔는데 2025.08.04 기준 0.1.16 버전이 최신 버전이다. 

 

내장도구는 당장 알고 활용하기보다 1편을 보고 바로 넘어오셨다면

아 이런 컨셉이구나? 정도로 눈으로 보고 넘어가도 좋을 것 같다. 

바로 MCP로 넘어 가기엔 아쉬워 살펴본 기능이다.

 

내장 도구 둘러보기

먼저 `/tools` 명령어로 현재 사용할 수 있는 내장 도구들을 확인해보자.

// Gemini CLI 실행 후 도구 목록 확인

Gemini > /tools

Available Gemini CLI tools:
- Edit - 파일 수정 (diff 방식)
- FindFiles - 파일 패턴 검색 (glob)
- GoogleSearch - 구글 검색
- ReadFile - 파일 내용 읽기
- ReadFolder - 폴더 내용 읽기 (ls)
- ReadManyFiles - 여러 파일 동시 읽기
- Save Memory - 메모리에 정보 저장
- SearchText - 텍스트 검색 (grep)
- Shell - 시스템 명령어 실행
- WebFetch - 웹페이지 내용 가져오기
- WriteFile - 새 파일 생성

💡 중요!
Gemini CLI는 기본적으로 모든 민감한 작업(파일 쓰기, 명령어 실행 등)에 대해 사용자 승인을 요구한다.
물론 --yolo 모드도 있지만 파일 삭제, 생성 등은 민감한 부분이 아닐까? 직접 승인 하는것도 괜찮을 것 같다.

 

파일 시스템 도구 실전 활용법

가장 많이 쓰게 되는 건 역시 파일 관련 도구들이다. 파일 시스템 관련해서만 6개정도.

도구명	기능	실무 활용 예시
ReadFolder	디렉토리 내용 조회 (ls)	프로젝트 구조 파악, 파일 목록 정리
ReadFile	단일 파일 내용 읽기	코드 분석, 설정 파일 확인
ReadManyFiles	여러 파일 동시 읽기	glob 패턴으로 관련 파일들 한 번에 분석
FindFiles	파일 패턴 검색 (glob)	특정 확장자 파일 찾기, config 파일 위치
SearchText	텍스트 검색 (grep)	TODO 찾기, 함수명 검색, 에러 로그 분석
Edit	파일 수정 (diff 방식)	코드 수정, 버그 픽스, 리팩토링
WriteFile	새 파일 생성	README 자동 생성, 설정 파일 생성

ex) - 프로젝트 폴더 일괄 정리

Gemini > 현재 폴더의 모든 하위 폴더를 확인하고, README.md가 없는 폴더에는 
기본 README를 생성해줘. package.json이 있으면 프로젝트명과 설명도 포함시켜줘.

🔍 폴더 스캔을 시작합니다...
📁 ./project-a 폴더 확인 중...
📝 README.md 생성: ./project-a/
📁 ./project-b 폴더 확인 중...  
📝 README.md 생성: ./project-b/
...
✅ 총 12개 폴더 처리 완료!

ex)

 

FindFiles vs SearchText : 헷갈리는 두 도구

이 둘을 구분해서 쓰는 게 중요하다. 많은 사람들이 헷갈려하는 부분이다.

차이점

FindFiles : 파일명이나 경로로 찾기

예시: "*.test.js 파일들 찾아줘", "config 이름이 들어간 파일 찾기"

SearchText : 파일 내용에서 텍스트 찾기

예시: "TODO 주석이 있는 곳 찾아줘", "useEffect 사용한 컴포넌트 찾기"

 

GoogleSearch + WebFetch  

이미 다들 채팅 모델들도 web search를 통해 최신 데이터, 공식문서등을 확인 하는데 많이 사용해 봤을 것 이다 .

정보 수집 워크플로우

1. GoogleSearch로 관련 자료 검색 및 URL 수집
2. WebFetch로 각 페이지 내용 상세 분석
3. 수집된 정보를 요약하여 구조화된 문서로 작성
4. 필요시 추가 검색으로 보완

실제 사용 예시 - 기술 동향 리포트 자동 생성

Gemini > React 19의 새로운 기능들을 조사해서 정리된 리포트를 만들어줘. 
공식 문서와 주요 개발 블로그들의 내용을 포함해서.

🔍 React 19 관련 자료 검색 중...
📄 React 공식 블로그 분석 중...
📄 주요 개발 블로그 5곳 내용 수집 중...
📝 리포트 작성 중...

✅ react-19-features-report.md 파일 생성 완료

 

ex) GoogleSearch를 사용하여 정보 수집하는 모습

 

ex) WebFetch로 데이터를 확인 하게 해보았다.

 

멀티모달 기능

멀티 모달 기능도 사용 가능하다고 한다. 간단하게 이미지 관련된 예시만 확인하고 넘어가자.

 

ex) 영수증 정리

영수증 일괄 처리 예시

Gemini > receipts 폴더의 모든 영수증 이미지를 분석해서 
날짜, 상호명, 금액을 추출하여 Excel 형태로 정리해줘.

🔍 receipts 폴더 스캔 중...
📊 inv1.png 분석 중... ✅
📊 inv2.png 분석 중... ✅
📊 inv3.png 분석 중... ✅
...
📝 expense_report_2024.csv 생성 중...

✅ 처리 완료: 12개 영수증 → 구조화된 데이터

ex) 이미지 리스트 요약 정리

 

Save Memory : 세션 간 컨텍스트 유지 위하여

한 번 저장한 정보를 다음 세션에서도 기억한다.

`~/.gemini/GEMINI.md` 파일에 저장되어 지속적으로 컨텍스트를 유지한다.

1편에서 이미 init을 통해 기본적인 내용이 작어되어 있을 텐데, 꼭 gemini가 기억했으면 하는 내용을 GEMINI.md에 기록해 두면 이를 gemini가 이후에도 참조하게 된다. 

Save Memory

1. 프로젝트 기본 정보 : 기술 스택, 아키텍처, 주요 기능
2. 개발 컨벤션 : 코딩 스타일, 네이밍 규칙, 폴더 구조
3. 자주 쓰는 패턴 : 명령어, 설정, 워크플로우
4. 프로젝트별 특이사항 : 제약 조건, 비즈니스 로직

// 실제 저장한 정보 예시

Gemini > 이 프로젝트는 Next.js 14 + TypeScript + Prisma ORM을 사용하는 
e-커머스 플랫폼이야. 컴포넌트는 PascalCase, 파일명은 kebab-case로 하고, 
모든 API는 tRPC로 구현했어. DB는 PostgreSQL이고, 배포는 Vercel이야. 
코딩 스타일은 Prettier + ESLint 기본 설정을 따르고, 
2스페이스 들여쓰기를 사용해. 이 정보를 기억해둬.

🧠 메모리에 저장됩니다...
✅ ~/.gemini/GEMINI.md 파일에 저장 완료

# 저장된 내용 확인
Gemini > /memory show

이제 새로운 터미널 세션을 시작해도 "상품 등록 API 분석해줘"라고 하면, 프로젝트 구조를 이미 알고 있어서 적절한 파일들을 찾아 분석한다.

 

보안과 권한 관리

Gemini CLI의 가장 인상적인 부분 중 하나가 보안에 대한 접근 방식이다.

기본적으로 모든 민감한 작업에 대해 사용자 승인을 요구하도록 되어 있다..

🔐 권한 요청 예시:

Gemini wants to use WriteFile tool to create 'report.md'
Allow: [o]nce, [a]lways, [n]ever?

💡 권한 관리
• 파일 읽기는 대부분 'always' 허용해도 안전
• 파일 쓰기는 'once'로 설정해서 매번 확인
• 시스템 명령어 실행은 특히 신중하게 판단
• --yolo 모드는 신중히 사용하자.

 

실무에서 자주 쓰는 활용 패턴들

자주 사용하는 명령 패턴

• 로그 분석 (SearchText) : "error.log 파일을 분석해서 가장 자주 발생하는 에러 5개를 찾아줘"
• 파일 찾기 (FindFiles) : "*.config.js 파일들을 모두 찾아서 설정 내용을 확인해줘"
• 코드 분석 (ReadManyFiles) : "src/components/*.tsx 파일들을 읽어서 공통 패턴을 찾아줘"
• 자동 수정 (Edit) : "모든 console.log를 console.debug로 바꿔줘"
• 메모리 활용 (Save Memory) : "이 프로젝트의 아키텍처 정보를 기억해둬"

 

활용 방안 

생산성 극대화

• GEMINI.md 파일 활용 : 프로젝트 루트에 만들어두면 매번 컨텍스트 설명할 필요 없다
• @ 활용 : @src/components/ 처럼 특정 폴더나 파일을 직접 참조 하자.
• 단축키 : Ctrl+Y로 YOLO 모드 토글, Shift+Tab으로 자동 승인 모드
• 정기적인 /clear : 주기적으로 또는 새로운 작업을 진행할때는 컨텍스트 정리하자.

 

회사에서 실제로 써본 사례들

ex1) 로그 분석 자동화

Gemini > logs 폴더의 모든 .log 파일을 분석해서 에러 유형별로 
분류하고, 발생 빈도와 함께 주간 리포트를 만들어줘.

ex2) API 문서 자동 생성

Gemini > routes 폴더의 모든 .js 파일을 분석해서 
API 엔드포인트, 파라미터, 응답 형식을 정리한 문서를 만들어줘.

 

자주 겪는 문제들

문제	원인	해결법
응답이 느려짐	무료 티어 제한으로 모델 다운그레이드	잠시 기다리거나 API 키 설정
인증 에러	구글 계정 세션 만료	/auth 명령어로 재인증
이상한 답변	컨텍스트가 너무 길어짐	/clear 또는 /compress 사용

 

MCP와의 차이점 이해하기

많은 분들이 내장 도구와 MCP 서버를 헷갈려하시는데, 간단히 구분하자면:

• 내장 도구: 기본적으로 제공되는 도구 (파일 시스템, 웹 검색 등)
• MCP 서버: 외부에서 추가로 설치하는 확장 도구들 (Slack, Google Drive 등)

개인 의견
내장 도구만으로도 충분히 유용하다. MCP는 너무 중요하니 별도의 세션에서 알아보자.

 

참고 자료 📚 

• Gemini CLI 공식 GitHub 저장소 - 최신 문서와 소스 코드
• Built-in Tools 공식 문서 - 내장 도구 상세 가이드
• Gemini API 문서 - API 레퍼런스 및 사용량 확인
• Google AI Studio - API 키 발급 및 관리

다음 글에서는 MCP 서버를 활용한 기능들에 대해 다뤄볼 생각이다.