Post

[AI 터미널 도구 13~14일차] Gemini CLI

Posted
Preview Image
By rkgh17
14 min read
[AI 터미널 도구 13~14일차] Gemini CLI

AI CLI book cover

도서명 : AI 자율학습 클로드 코드·코덱스 CLI·제미나이 CLI 완전 활용법

이 포스팅은 길벗 출판사의 코딩 자율학습단 20기 활동의 일환으로, 개인 공부 정리용 포스팅이다.

9장 - Gemini CLI 시작하기기

9.1 - Gemini CLI 설치

  1. 로컬 환경에 CLI를 설치
  2. Google 계정 인증

설치

  • Node.js 설치
  • Gemini CLI 설치
    • npm install -g @google/gemini-cli
    • gemini --version

실행

  1. 터미널에서 현재 위치를 확인
  2. 실습용 폴더 생성 및 이동
  3. 폴더 내부에서 Gemini CLI 실행
    • gemini

9.2 - Gemini CLI 사용

Gemini CLI는 현재 작업 중인 폴더를 기준으로 파일을 읽고 수정하며, 필요할 경우 셸 명령을 실행한다.

명령 실행 방식

  1. 일회성 실행 : 단발성 작업에 적합
    • gemini "간단한 웹 페이지 구조를 index.html로 만들어줘"
  2. 대화형 실행 : 연속 작업에 적합
    • 초기 요청을 수행한 뒤, 이어지는 후속 요청을 대화 형식으로 계속 입력할 수 있습니다.
    • 실시간으로 파일을 분석하거나 여러 단계를 연속적으로 수행할 때 유용하다.

기본 대화

1
2
3
4
5
6
7
8

# 새 프로젝트 초기화
> Next.js와 TypeScript 기반 블로그 프로젝트를 초기화해줘.
# 기존 프로젝트 분석
> 이 프로젝트의 기능을 요약해줘.
> package.json의 의존성을 분석해줘.
# 구체적 작업 요청
> src/utils 폴더에 날짜 포매팅 유틸리티 함수를 추가해줘.
> utils/date.ts 파일에 단위 테스트를 작성해줘.

단축키

단축키기능
Alt + 화살표 좌우단어 단위 커서 이동
Ctrl + C한번 : 응답 중단 / 두번 : CLI 종료
Ctrl + J줄바꿈
Ctrl + L터미널 화면 지우기
Ctrl + X외부 에디터 등에서 프롬프트 편집
Ctrl + YYOLO모드 토글
Enter입력 전송
ESC한번 : 현재 입력 취소 / 두번 : 입력창 초기화
Shift + Tab자동 승인 모드 토글
화살표 위아래프롬프트 히스토리 탐색

다른 폴더 포함

기본적으로는 현재 폴더만 분석하지만, 필요하면 --include-directories 플래그를 사용해 다른 폴더도 함께 참조할 수 있다.

세션 관리

Gemini CLI는 한 번 실행된 세션 안에서 여러 대화를 이어 갈 수 있는 지속형 세션 구조를 가진다. 사용자가 입력한 요청, 코드 수정, 파일 참조 등 모든 상호작용은 컨텍스트로 저장되며, 이를 바탕으로 이전 대화를 기억한 상태에서 연속 작업을 수행한다.
이때 세션 데이터는 기본적으로 ~/.gemini/sessions 폴더에 JSONL형식으로 저장되며, 필요할 때 다시 불러와 이어서 작업할 수 있다.

  • Ctrl + C 한번 : 현재 응답 중단
  • Ctrl + C 두번 : 세션 전체 종료
  • Ctrl + D : 터미널 표준 종료
  • 터미널 창 닫기 : 세션 종료
  • 세션 이어가기 : /resume project

이미지 참조

Gemini 모델은 텍스트뿐 아니라 이미지를 함꼐 분석할 수 있는 멀티모달 기능을 지원한다. Gemini CLI는 현재 작업 폴더에 있는 이미지 파일을 인식하며, 프롬프트에서 파일 이름을 언급하는 것만으로도 해당 이미지를 컨텍스트에 포함해 분석할 수 있다.

  • design-mockup.png 파일의 레이아웃을 기반으로 React 컴포넌트를 만들어줘.
  • error-log.png의 오류 메시지를 분석해 해결 방법을 알려줘.

비대화형 모드로 일화성 작업 실행하기

간단한 요청을 빠르게 실행하고 싶을 때는 비대화형 모드를 사용할 수 있다. 이 모드는 대화형 세션으로 진입하지 않고 한 번의 명령으로 결과를 출력한 뒤 즉시 종료한다.

  • gemini "이 프로젝트의 주요 기술 스택을 요약해줘"
  • gemini "eslint 오류를 자동으로 수정해줘."

자동화 스크립트나 CI 파이프라인에서는 JSON형태의 결과가 유용할 때가 많다. 이때는 --output-format 옵션을 사용해 출력 형식을 지정할 수 있다.

  • gemini "현재 폴더의 파일 리스트를 요약해줘." --output-format json

파일 참조하기

@ 기호를 사용해 프로젝트 내부 파일을 명시적으로 참조할 수 있다. 이 기능은 Claude Code나 Codex의 방식과 유사하며, 모델이 실제 코드 내용을 정확히 이해한 상태에서 작업하도록 돕는다. 또한, 파일 경로 전체를 입력할 필요가 없다.

9.3 - 명령과 실행 옵션

Gemini CLI는 개발자가 터미널 환경에서 AI와 협업하기 쉽도록 명확하고 일관된 명령 체계를 제공한다.

  1. CLI 실행 옵션(command-line option)
    • Gemini CLI를 처음 실행할 때 지정하는 옵션으로, 세션 전체의 초기 설정을 제어한다.
    • 모델선택, 출력 형식, 자동 실행 여부 등 세션의 동작 방식을 결정
  2. 슬래시 명령어(slash command)
    • 대화형 세션이 시작된 후 /status, /save, /resume 과 같이 세션 관리, 설정 변경, 도구 실행 등을 실시간으로 제어하는 명령어

CLI 진입 명령

  • 기본 대화형 모드 : GEMINI
    • 옵션 없이 gemini만 입력하면 즉시 대화형 세션이 시작
    • AI와 실시간으로 대화를 주고받으며 코드를 작성하거나 파일을 수정할 수 있음
  • 원샷 모드 : gemini [query...]
    • 명령 인자에 질의(query)를 직접 전달하는 방식
    • 요청을 한번만 실행하고 결과를 출력한 뒤 자동으로 조ㅓㅇ료하므로 스크립트, 파이프라인, CI작업처럼 단발성 자동화에 적합
    • gemini "READ.md 파일을 요약해줘"
    • echo "이 코드를 리뷰해줘." || gemini
  • 원샷 후 대화형 전환 : gemini -i [query]
    • -i또는 --prompt-interactive 옵션을 사용하면 초기 요청을 먼저 실행한 뒤 그 결과를 그대로 이어받아 대화형 모드로 전환.
    • gemini -i "프로젝트 전체 구조를 분석해줘
    • 이 방식은 다음과 같은 상황에서 특히 유용
      • 프로젝트 초기 점검(폴더 구조, 의존성 분석 등)
      • PR 코드 리뷰
      • 리팩터링 제안 후 후속 작업 연결
      • 분석 결과에 기반해 대화를 이어가야 하는 작업 흐름

자주 사용하는 실행 옵션

  • 디버그 모드 : -d, --debug
    • CLI 내부 동작을 상세히 출력.
    • API 호출, MCP 통신, 파일 접근 등을 실시간으로 추적할 수 있다.
    • gemini -d 2>debug.log
  • 샌드박스 모드 : -s, --sandbox
    • 프로젝트 외부 파일 시스템 접근을 차단하는 보안모드. 프로젝트 폴더 내부는 자유롭게 읽고 수정할 수 있지만, 운영체제의 중요 디렉터리는 보호됨.
    • gemini --sandbox
      • 허용범위 : 프로젝트 폴더 내 파일 생성, 수정, 삭제, 명령 실행(npm build 등)
      • 차단범위 : 시스템 설정 파일, 사용자 홈의 중요 설정(.bashrc, ssh/config 등)
    • 샌드박스 모드를 사용하는 이유는 다음과 같다.
      • 보안 강화 : 시스템 파일 손상 방지
      • 환경 격리 : 프로젝트 단위로 파일 접근 경계를 명확히 설정
      • 일관성 유지 : CI/CD, 팀 환경에서 동일한 실행 결과 보장
      • 안전한 실험 : 외부 스니핏 실행 시 최소한의 보호막 제공
  • YOLO 모드 : -y, --yolo
    • 모든 파일 편집, 명령 실행을 자동 승인하는 빠른 실행 모드
    • gemini -y
  • 승인 모드 설정 : --approval-mode <모드>
    • 자동 승인 범위를 더 정밀하게 제어하고 싶을 때 사용
    • default : 모든 작업 실행 전 승인 요청(기본값)
    • auto_edit : 파일 편집만 자동 승인, 나머지는 확인 필요
    • yolo : 모든 파일 자동 승인
  • 도구 실행 권한 제어 : --allowed tools <도구명>
    • 특정 도구만 자동 실행하도록 제어
    • gemini --allwed-tools read_file, search_files
    • 주요 내장 도구
      • read_file : 읽기
      • write_file : 새 파일 작성
      • edit_file : 기존 파일 수정
      • search_files : 파일 이름 검색
      • grep : 파일 내용 검색
      • bash : 셀 명령 실행
      • web_search : 웹 검색 수행
  • 워크 스페이스 확장 : --include-directories <경로>

9.3 - 환경 관련 옵션

  • 확장 목록 확인 : -l, --list-extensions
  • 스크린 리더 모드 : --screen-reader
  • 출력 형식 지정 : -o, --output-format <text|json|md>
  • 버전 확인 : -v, --version
  • 도움말 : -h, -help

9.4 주요 슬래시 명령어

  • 워크스페이스 확장 : /directory
    • 현재 프로젝트 외 폴더를 세션 작업 공간에 추가할 때 사용
  • 메모리 관리 : /memory
    • 사용자의 스타일이나 반복되는 개인적 요청을 AI가 장기적으로 깅거하게 할 때 사용.
    • 프로젝트 문서인 GEMINI.md와는 별개로 작동
  • 세션 진단 : /status
    • 세션의 상태를 실시간으로 점검.
    • 모델별 토큰 사용량, 도구 호출 횟수, 캐시 적중률 등을 확인
  • 환경 커스터마이징
    • /settings : 인터랙티브 UI로 구성되어 있어 키보드로 항목 이동 및 선택 가능
    • /theme : CLI 색상 테마를 변경
    • /editor : VSCode, Vim과 같은 외부 에디터를 연동하며, 프롬프트를 에디터에서 작성하고 CLI가 자동으로 불러옴
    • /vim : 입력창을 Vim모드로 전환해 키 바인딩을 그대로 사용할 수 있게 함.
  • 컨텍스트 최적화 : /compress




Study
AI CLI 코딩 자율학습단 20기
This post is licensed under CC BY 4.0 by the author.