Gemini CLI 구성 (Gemini CLI configuration)

25. 9. 17. 구성 형식에 대한 참고 사항: settings.json 파일의 형식이 더 체계적인 새로운 구조로 업데이트되었습니다.

새로운 형식은 **[25. 9. 10.]**부터 안정적인 릴리스에서 지원됩니다.

이전 형식에서 새 형식으로의 자동 마이그레이션은 **[25. 9. 17.]**에 시작됩니다.

이전 형식에 대한 자세한 내용은 v1 구성 문서를 참조하세요.

Gemini CLI는 환경 변수, 명령줄 인수 및 설정 파일을 포함하여 동작을 구성하는 여러 가지 방법을 제공합니다. 이 문서에서는 다양한 구성 방법과 사용 가능한 설정에 대해 설명합니다.

구성 계층 (Configuration layers)

구성은 다음 우선 순위(낮은 숫자는 높은 숫자에 의해 재정의됨)에 따라 적용됩니다.

기본값 (Default values): 애플리케이션 내의 하드코딩된 기본값입니다.
시스템 기본 파일 (System defaults file): 다른 설정 파일에 의해 재정의될 수 있는 시스템 전체 기본 설정입니다.
사용자 설정 파일 (User settings file): 현재 사용자에 대한 전역 설정입니다.
프로젝트 설정 파일 (Project settings file): 프로젝트별 설정입니다.
시스템 설정 파일 (System settings file): 다른 모든 설정 파일을 재정의하는 시스템 전체 설정입니다.
환경 변수 (Environment variables): .env 파일에서 로드될 수 있는 시스템 전체 또는 세션별 변수입니다.
명령줄 인수 (Command-line arguments): CLI를 실행할 때 전달되는 값입니다.

설정 파일 (Settings files)

Gemini CLI는 지속적인 구성을 위해 JSON 설정 파일을 사용합니다. 이러한 파일의 위치는 네 곳입니다.

팁: JSON 인식 편집기는 이 저장소의 schemas/settings.schema.json에 있는 생성된 스키마를 가리켜 자동 완성 및 유효성 검사를 사용할 수 있습니다. 저장소 외부에서 작업할 때는 https://raw.githubusercontent.com/google-gemini/gemini-cli/main/schemas/settings.schema.json에 호스팅된 스키마를 참조하세요.

시스템 기본 파일:
- 위치: /etc/gemini-cli/system-defaults.json (Linux), C:\ProgramData\gemini-cli\system-defaults.json (Windows) 또는 /Library/Application Support/GeminiCli/system-defaults.json (macOS). 경로는 GEMINI_CLI_SYSTEM_DEFAULTS_PATH 환경 변수를 사용하여 재정의할 수 있습니다.
- 범위: 시스템 전체 기본 설정의 기본 계층을 제공합니다. 이 설정은 가장 낮은 우선 순위를 가지며 사용자, 프로젝트 또는 시스템 재정의 설정에 의해 재정의되도록 의도되었습니다.
사용자 설정 파일:
- 위치: ~/.gemini/settings.json (여기서 ~는 홈 디렉터리입니다).
- 범위: 현재 사용자의 모든 Gemini CLI 세션에 적용됩니다. 사용자 설정은 시스템 기본값을 재정의합니다.
프로젝트 설정 파일:
- 위치: 프로젝트 루트 디렉터리 내의 .gemini/settings.json.
- 범위: 해당 프로젝트에서 Gemini CLI를 실행할 때만 적용됩니다. 프로젝트 설정은 사용자 설정 및 시스템 기본값을 재정의합니다.
시스템 설정 파일:
- 위치: /etc/gemini-cli/settings.json (Linux), C:\ProgramData\gemini-cli\settings.json (Windows) 또는 /Library/Application Support/GeminiCli/settings.json (macOS). 경로는 GEMINI_CLI_SYSTEM_SETTINGS_PATH 환경 변수를 사용하여 재정의할 수 있습니다.
- 범위: 시스템의 모든 사용자, 모든 Gemini CLI 세션에 적용됩니다. 시스템 설정은 재정의 역할을 하여 다른 모든 설정 파일보다 우선합니다. 기업의 시스템 관리자가 사용자의 Gemini CLI 설정을 제어하는 데 유용할 수 있습니다.

설정의 환경 변수에 대한 참고 사항: settings.json 및 gemini-extension.json 파일 내의 문자열 값은 $VAR_NAME 또는 ${VAR_NAME} 구문을 사용하여 환경 변수를 참조할 수 있습니다. 이러한 변수는 설정이 로드될 때 자동으로 확인됩니다. 예를 들어 MY_API_TOKEN 환경 변수가 있는 경우 settings.json에서 "apiKey": "$MY_API_TOKEN"과 같이 사용할 수 있습니다. 또한 각 확장 프로그램은 디렉터리에 자체 .env 파일을 가질 수 있으며, 이 파일은 자동으로 로드됩니다.

기업 사용자를 위한 참고 사항: 기업 환경에서 Gemini CLI를 배포하고 관리하는 지침은 기업 구성 문서를 참조하세요.

프로젝트의 `.gemini` 디렉터리

프로젝트 설정 파일 외에도 프로젝트의 .gemini 디렉터리에는 다음과 같은 Gemini CLI 작동과 관련된 다른 프로젝트별 파일이 포함될 수 있습니다.

사용자 정의 샌드박스 프로필 (예: .gemini/sandbox-macos-custom.sb, .gemini/sandbox.Dockerfile).

Available settings in `settings.json`

Settings are organized into categories. All settings should be placed within their corresponding top-level category object in your settings.json file.

`general`

general.preferredEditor (string):
- Description: 파일을 열 때 선호하는 에디터입니다.
- Default: undefined
general.vimMode (boolean):
- Description: Vim 키 바인딩을 활성화합니다.
- Default: false
general.defaultApprovalMode (enum):
- Description: 도구 실행에 대한 기본 승인 모드입니다. 'default'는 승인을 요청하고, 'auto_edit'는 편집 도구를 자동 승인하며, 'plan'은 읽기 전용 모드입니다. 'yolo'는 아직 지원되지 않습니다.
- Default: "default"
- Values: "default", "auto_edit", "plan"
general.devtools (boolean):
- Description: 실행 시 DevTools 검사기를 활성화합니다.
- Default: false
general.enableAutoUpdate (boolean):
- Description: 자동 업데이트를 활성화합니다.
- Default: true
general.enableAutoUpdateNotification (boolean):
- Description: 업데이트 알림 메시지를 활성화합니다.
- Default: true
general.checkpointing.enabled (boolean):
- Description: 복구를 위한 세션 체크포인트를 활성화합니다.
- Default: false
- Requires restart: 예
general.enablePromptCompletion (boolean):
- Description: 입력 중 AI 기반 프롬프트 완성 제안을 활성화합니다.
- Default: false
- Requires restart: 예
general.retryFetchErrors (boolean):
- Description: "exception TypeError: fetch failed sending request" 오류 발생 시 재시도합니다.
- Default: false
general.debugKeystrokeLogging (boolean):
- Description: 콘솔에 키입력 디버그 로깅을 활성화합니다.
- Default: false
general.sessionRetention.enabled (boolean):
- Description: 자동 세션 정리를 활성화합니다.
- Default: false
general.sessionRetention.maxAge (string):
- Description: 세션 유지 최대 기간 (예: "30d", "7d", "24h", "1w")
- Default: undefined
general.sessionRetention.maxCount (number):
- Description: 대안: 유지할 최대 세션 수 (최신순)
- Default: undefined
general.sessionRetention.minRetention (string):
- Description: 최소 보존 기간 (안전 제한, 기본값 "1d")
- Default: "1d"

`output`

output.format (enum):
- Description: CLI 출력 형식입니다. text 또는 json일 수 있습니다.
- Default: "text"
- Values: "text", "json"

`ui`

ui.theme (string):
- Description: UI 색상 테마입니다. 사용 가능한 옵션은 테마 가이드를 참조하세요.
- Default: undefined
ui.autoThemeSwitching (boolean):
- Description: 터미널 배경색에 따라 밝은/어두운 테마를 자동으로 전환합니다.
- Default: true
ui.terminalBackgroundPollingInterval (number):
- Description: 터미널 배경색 폴링 간격(초)입니다.
- Default: 60
ui.customThemes (object):
- Description: 커스텀 테마 정의입니다.
- Default: {}
ui.hideWindowTitle (boolean):
- Description: 창 제목 표시줄을 숨깁니다.
- Default: false
- Requires restart: 예
ui.inlineThinkingMode (enum):
- Description: 모델의 사고 과정을 인라인으로 표시할지 여부입니다. (끄기 또는 전체 표시)
- Default: "off"
- Values: "off", "full"
ui.showStatusInTitle (boolean):
- Description: 작업 중일 때 터미널 창 제목에 Gemini CLI 모델의 사고를 표시합니다.
- Default: false
ui.dynamicWindowTitle (boolean):
- Description: 현재 상태 아이콘으로 터미널 창 제목을 업데이트합니다. (준비: ◇, 조치 필요: ✋, 작업 중: ✦)
- Default: true
ui.showHomeDirectoryWarning (boolean):
- Description: 홈 디렉토리에서 Gemini CLI를 실행할 때 경고를 표시합니다.
- Default: true
- Requires restart: Yes
ui.hideTips (boolean):
- Description: UI에서 유용한 팁을 숨깁니다.
- Default: false
ui.showShortcutsHint (boolean):
- Description: 입력창 위에 "? for shortcuts" 힌트를 표시합니다.
- Default: true
ui.hideBanner (boolean):
- Description: 애플리케이션 배너를 숨깁니다.
- Default: false
ui.hideContextSummary (boolean):
- Description: 입력창 위에 컨텍스트 요약(GEMINI.md, MCP 서버)을 숨깁니다.
- Default: false
ui.footer.hideCWD (boolean):
- Description: 바닥글에서 현재 작업 디렉토리 경로를 숨깁니다.
- Default: false
ui.footer.hideSandboxStatus (boolean):
- Description: 바닥글에서 샌드박스 상태 표시를 숨깁니다.
- Default: false
ui.footer.hideModelInfo (boolean):
- Description: 바닥글에서 모델 이름과 컨텍스트 사용량을 숨깁니다.
- Default: false
ui.footer.hideContextPercentage (boolean):
- Description: 컨텍스트 윈도우 잔여 비율을 숨깁니다.
- Default: true
ui.hideFooter (boolean):
- Description: UI에서 바닥글을 숨깁니다.
- Default: false
ui.showMemoryUsage (boolean):
- Description: UI에 메모리 사용 정보를 표시합니다.
- Default: false
ui.showLineNumbers (boolean):
- Description: 채팅에 줄 번호를 표시합니다.
- Default: true
ui.showCitations (boolean):
- Description: 생성된 텍스트에 대한 인용을 채팅에 표시합니다.
- Default: false
ui.showModelInfoInChat (boolean):
- Description: 채팅에서 각 모델 턴마다 모델 이름을 표시합니다.
- Default: false
ui.showUserIdentity (boolean):
- Description: UI에 로그인한 사용자의 신원(이메일 등)을 표시합니다.
- Default: true
ui.useAlternateBuffer (boolean):
- Description: UI에 대체 화면 버퍼를 사용하여 쉘 기록을 보존합니다.
- Default: false
- Requires restart: 예
ui.useBackgroundColor (boolean):
- Description: UI에서 배경색을 사용할지 여부입니다.
- Default: true
ui.incrementalRendering (boolean):
- Description: UI 점진적 렌더링을 활성화합니다. 이 옵션은 깜빡임을 줄일 수 있지만 렌더링 아티팩트가 발생할 수 있습니다. useAlternateBuffer가 활성화된 경우에만 지원됩니다.
- Default: true
- Requires restart: 예
ui.showSpinner (boolean):
- Description: 작업 중 스피너를 표시합니다.
- Default: true
ui.customWittyPhrases (array):
- Description: 로딩 중에 표시할 사용자 정의 재치 문구입니다. 제공되면 기본값 대신 이 문구들이 순환됩니다.
- Default: []
ui.accessibility.enableLoadingPhrases (boolean):
- Description: 작업 중 로딩 문구를 활성화합니다.
- Default: true
- Requires restart: 예
ui.accessibility.screenReader (boolean):
- Description: 스크린 리더 접근성을 높이기 위해 일반 텍스트로 출력을 렌더링합니다.
- Default: false
- Requires restart: 예

`ide`

ide.enabled (boolean):
- Description: IDE 통합 모드를 활성화합니다.
- Default: false
- Requires restart: 예
ide.hasSeenNudge (boolean):
- Description: 사용자가 IDE 통합 알림을 보았는지 여부입니다.
- Default: false

`privacy`

privacy.usageStatisticsEnabled (boolean):
- Description: 사용 통계 수집을 활성화합니다.
- Default: true
- Requires restart: 예

`model`

model.name (string):
- Description: 대화에 사용할 Gemini 모델입니다.
- Default: undefined
model.maxSessionTurns (number):
- Description: 세션에 보관할 최대 사용자/모델/도구 턴 수입니다. -1은 무제한을 의미합니다.
- Default: -1
model.summarizeToolOutput (object):
- Description: 도구 출력 요약 활성화/비활성화. 도구별 토큰 예산을 구성합니다 (예: {"run_shell_command": {"tokenBudget": 2000}}). 현재 run_shell_command 도구만 요약을 지원합니다.
- Default: undefined
model.compressionThreshold (number):
- Description: 컨텍스트 압축을 트리거할 컨텍스트 사용량 비율입니다 (예: 0.2, 0.3).
- Default: 0.5
- Requires restart: 예
model.disableLoopDetection (boolean):
- Description: 무한 루프 자동 감지 및 방지를 비활성화합니다.
- Default: false
- Requires restart: 예
model.skipNextSpeakerCheck (boolean):
- Description: 다음 화자 확인을 건너뜁니다.
- Default: true

`modelConfigs`

modelConfigs.aliases (object):

Description: 모델 설정에 대한 명명된 사전 설정입니다. 모델 이름 대신 사용할 수 있으며, extends 속성을 사용하여 다른 별칭을 상속할 수 있습니다.

Default:

{
  "base": {
    "modelConfig": {
      "generateContentConfig": {
        "temperature": 0,
        "topP": 1
      }
    }
  },
  "chat-base": {
    "extends": "base",
    "modelConfig": {
      "generateContentConfig": {
        "thinkingConfig": {
          "includeThoughts": true
        },
        "temperature": 1,
        "topP": 0.95,
        "topK": 64
      }
    }
  },
  "chat-base-2.5": {
    "extends": "chat-base",
    "modelConfig": {
      "generateContentConfig": {
        "thinkingConfig": {
          "thinkingBudget": 8192
        }
      }
    }
  },
  "chat-base-3": {
    "extends": "chat-base",
    "modelConfig": {
      "generateContentConfig": {
        "thinkingConfig": {
          "thinkingLevel": "HIGH"
        }
      }
    }
  },
  "gemini-3-pro-preview": {
    "extends": "chat-base-3",
    "modelConfig": {
      "model": "gemini-3-pro-preview"
    }
  },
  "gemini-3-flash-preview": {
    "extends": "chat-base-3",
    "modelConfig": {
      "model": "gemini-3-flash-preview"
    }
  },
  "gemini-2.5-pro": {
    "extends": "chat-base-2.5",
    "modelConfig": {
      "model": "gemini-2.5-pro"
    }
  },
  "gemini-2.5-flash": {
    "extends": "chat-base-2.5",
    "modelConfig": {
      "model": "gemini-2.5-flash"
    }
  },
  "gemini-2.5-flash-lite": {
    "extends": "chat-base-2.5",
    "modelConfig": {
      "model": "gemini-2.5-flash-lite"
    }
  },
  "gemini-2.5-flash-base": {
    "extends": "base",
    "modelConfig": {
      "model": "gemini-2.5-flash"
    }
  },
  "classifier": {
    "extends": "base",
    "modelConfig": {
      "model": "gemini-2.5-flash-lite",
      "generateContentConfig": {
        "maxOutputTokens": 1024,
        "thinkingConfig": {
          "thinkingBudget": 512
        }
      }
    }
  },
  "prompt-completion": {
    "extends": "base",
    "modelConfig": {
      "model": "gemini-2.5-flash-lite",
      "generateContentConfig": {
        "temperature": 0.3,
        "maxOutputTokens": 16000,
        "thinkingConfig": {
          "thinkingBudget": 0
        }
      }
    }
  },
  "edit-corrector": {
    "extends": "base",
    "modelConfig": {
      "model": "gemini-2.5-flash-lite",
      "generateContentConfig": {
        "thinkingConfig": {
          "thinkingBudget": 0
        }
      }
    }
  },
  "summarizer-default": {
    "extends": "base",
    "modelConfig": {
      "model": "gemini-2.5-flash-lite",
      "generateContentConfig": {
        "maxOutputTokens": 2000
      }
    }
  },
  "summarizer-shell": {
    "extends": "base",
    "modelConfig": {
      "model": "gemini-2.5-flash-lite",
      "generateContentConfig": {
        "maxOutputTokens": 2000
      }
    }
  },
  "web-search": {
    "extends": "gemini-2.5-flash-base",
    "modelConfig": {
      "generateContentConfig": {
        "tools": [
          {
            "googleSearch": {}
          }
        ]
      }
    }
  },
  "web-fetch": {
    "extends": "gemini-2.5-flash-base",
    "modelConfig": {
      "generateContentConfig": {
        "tools": [
          {
            "urlContext": {}
          }
        ]
      }
    }
  },
  "web-fetch-fallback": {
    "extends": "gemini-2.5-flash-base",
    "modelConfig": {}
  },
  "loop-detection": {
    "extends": "gemini-2.5-flash-base",
    "modelConfig": {}
  },
  "loop-detection-double-check": {
    "extends": "base",
    "modelConfig": {
      "model": "gemini-2.5-pro"
    }
  },
  "llm-edit-fixer": {
    "extends": "gemini-2.5-flash-base",
    "modelConfig": {}
  },
  "next-speaker-checker": {
    "extends": "gemini-2.5-flash-base",
    "modelConfig": {}
  },
  "chat-compression-3-pro": {
    "modelConfig": {
      "model": "gemini-3-pro-preview"
    }
  },
  "chat-compression-3-flash": {
    "modelConfig": {
      "model": "gemini-3-flash-preview"
    }
  },
  "chat-compression-2.5-pro": {
    "modelConfig": {
      "model": "gemini-2.5-pro"
    }
  },
  "chat-compression-2.5-flash": {
    "modelConfig": {
      "model": "gemini-2.5-flash"
    }
  },
  "chat-compression-2.5-flash-lite": {
    "modelConfig": {
      "model": "gemini-2.5-flash-lite"
    }
  },
  "chat-compression-default": {
    "modelConfig": {
      "model": "gemini-2.5-pro"
    }
  }
}

modelConfigs.customAliases (object):
- Description: 사용자 정의 모델 설정 프리셋입니다. 내장 별칭과 병합되며(내장 별칭을 덮어씀), 우선 순위가 더 높습니다.
- Default: {}
modelConfigs.customOverrides (array):
- Description: 사용자 정의 모델 설정 재정의입니다. 내장 재정의와 병합됩니다(추가됨).
- Default: []
modelConfigs.overrides (array):
- Description: 모델(또는 별칭) 키를 기준으로 특정 설정 재정의를 적용합니다. 가장 구체적인 일치가 사용됩니다.
- Default: []

`agents`

agents.overrides (object):
- Description: 특정 에이전트에 대한 설정을 재정의합니다. (예: 에이전트 비활성화, 사용자 정의 모델 설정 또는 실행 설정).
- Default: {}
- Requires restart: 예

`context`

context.fileName (string | string[]):
- Description: The name of the context file or files to load into memory. Accepts either a single string or an array of strings.
- Default: undefined
context.importFormat (string):
- Description: The format to use when importing memory.
- Default: undefined
context.discoveryMaxDirs (number):
- Description: Maximum number of directories to search for memory.
- Default: 200
context.includeDirectories (array):
- Description: Additional directories to include in the workspace context. Missing directories will be skipped with a warning.
- Default: []
context.loadMemoryFromIncludeDirectories (boolean):
- Description: Controls how /memory refresh loads GEMINI.md files. When true, include directories are scanned; when false, only the current directory is used.
- Default: false
context.fileFiltering.respectGitIgnore (boolean):
- Description: Respect .gitignore files when searching.
- Default: true
- Requires restart: Yes
context.fileFiltering.respectGeminiIgnore (boolean):
- Description: Respect .geminiignore files when searching.
- Default: true
- Requires restart: Yes
context.fileFiltering.enableRecursiveFileSearch (boolean):
- Description: Enable recursive file search functionality when completing @ references in the prompt.
- Default: true
- Requires restart: Yes
context.fileFiltering.enableFuzzySearch (boolean):
- Description: Enable fuzzy search when searching for files.
- Default: true
- Requires restart: Yes
context.fileFiltering.customIgnoreFilePaths (array):
- Description: Additional ignore file paths to respect. These files take precedence over .geminiignore and .gitignore. Files earlier in the array take precedence over files later in the array, e.g. the first file takes precedence over the second one.
- Default: []
- Requires restart: 예

`tools`

tools.sandbox (boolean | string):
- Description: 샌드박스 실행 환경입니다. 부울 값으로 설정하여 샌드박스를 활성화/비활성화하거나 샌드박스 프로필 경로(문자열)를 제공할 수 있습니다.
- Default: undefined
- Requires restart: 예
tools.shell.enableInteractiveShell (boolean):
- Description: 대화형 쉘 경험을 위해 node-pty를 사용합니다. child_process 폴백은 여전히 적용됩니다.
- Default: true
- Requires restart: 예
tools.shell.pager (string):
- Description: 쉘 출력에 사용할 페이징 명령입니다. 기본값은 cat입니다.
- Default: "cat"
tools.shell.showColor (boolean):
- Description: 쉘 출력에 색상을 표시합니다.
- Default: false
tools.shell.inactivityTimeout (number):
- Description: 쉘 명령에서 출력이 없는 상태로 허용되는 최대 시간(초)입니다. 기본값은 5분입니다.
- Default: 300
tools.shell.enableShellOutputEfficiency (boolean):
- Description: 더 나은 성능을 위해 쉘 출력 효율성 최적화를 활성화합니다.
- Default: true
tools.core (array):
- Description: 허용 목록(allowlist)으로 내장 도구 세트를 제한합니다. 일치 의미 체계는 tools.allowed와 동일합니다. 사용 가능한 이름은 내장 도구 문서를 참조하세요.
- Default: undefined
- Requires restart: Yes
tools.allowed (array):
- Description: 확인 대화상자를 우회할 도구 이름 목록입니다. 신뢰할 수 있는 명령에 유용합니다 (예: ["run_shell_command(git)", "run_shell_command(npm test)"]). 일치 세부 정보는 쉘 도구 명령 제한 사항을 참조하세요.
- Default: undefined
- Requires restart: 예
tools.exclude (array):
- Description: 검색에서 제외할 도구 이름 목록입니다.
- Default: undefined
- Requires restart: 예
tools.discoveryCommand (string):
- Description: 도구 검색을 위해 실행할 명령입니다.
- Default: undefined
- Requires restart: 예
tools.callCommand (string):
- Description: 발견된 도구를 호출하기 위한 사용자 정의 쉘 명령을 정의합니다. 명령은 첫 번째 인자로 도구 이름을 받고, stdin에서 JSON 인자를 읽으며, stdout으로 JSON 결과를 출력해야 합니다.
- Default: undefined
- Requires restart: 예
tools.useRipgrep (boolean):
- Description: 폴백 구현 대신 파일 내용 검색에 ripgrep을 사용합니다. 더 빠른 검색 성능을 제공합니다.
- Default: true
tools.truncateToolOutputThreshold (number):
- Description: 대규모 도구 출력을 자를 때 표시할 최대 문자 수입니다. 0 또는 음수로 설정하면 자르기를 비활성화합니다.
- Default: 40000
- Requires restart: 예
tools.disableLLMCorrection (boolean):
- Description: 편집 도구에 대한 LLM 기반 오류 수정을 비활성화합니다. 활성화된 경우, 정확한 문자열 일치를 찾지 못하면 자체 수정을 시도하는 대신 즉시 실패합니다.
- Default: true
- Requires restart: Yes

`mcp`

mcp.serverCommand (string):
- Description: MCP 서버를 시작할 명령입니다.
- Default: undefined
- Requires restart: 예
mcp.allowed (array):
- Description: 허용할 MCP 서버 목록입니다.
- Default: undefined
- Requires restart: 예
mcp.excluded (array):
- Description: 제외할 MCP 서버 목록입니다.
- Default: undefined
- Requires restart: 예

`useWriteTodos`

useWriteTodos (boolean):
- Description: write_todos 도구를 활성화합니다.
- Default: true

`security`

security.disableYoloMode (boolean):
- Description: YOLO 모드를 비활성화합니다. 플래그로 활성화된 경우에도 적용됩니다.
- Default: false
- Requires restart: 예
security.enablePermanentToolApproval (boolean):
- Description: 도구 확인 대화상자에서 "이 세션의 나머지 기간 동안 허용" 옵션을 활성화합니다.
- Default: false
security.blockGitExtensions (boolean):
- Description: Git에서 확장을 설치하고 로드하는 것을 차단합니다.
- Default: false
- Requires restart: 예
security.allowedExtensions (array):
- Description: 허용된 확장에 대한 정규식 목록입니다. 비어 있지 않으면, 이 목록의 패턴과 일치하는 확장만 허용됩니다. blockGitExtensions 설정을 덮어씁니다.
- Default: []
- Requires restart: 예
security.folderTrust.enabled (boolean):
- Description: 폴더 신뢰가 활성화되어 있는지 추적하는 설정입니다.
- Default: true
- Requires restart: Yes
security.environmentVariableRedaction.allowed (array):
- Description: Environment variables to always allow (bypass redaction).
- Default: []
- Requires restart: Yes
security.environmentVariableRedaction.blocked (array):
- Description: Environment variables to always redact.
- Default: []
- Requires restart: Yes
security.environmentVariableRedaction.enabled (boolean):
- Description: Enable redaction of environment variables that may contain secrets.
- Default: false
- Requires restart: Yes
security.auth.selectedType (string):
- Description: The currently selected authentication type.
- Default: undefined
- Requires restart: Yes
security.auth.enforcedType (string):
- Description: The required auth type. If this does not match the selected auth type, the user will be prompted to re-authenticate.
- Default: undefined
- Requires restart: Yes
security.auth.useExternal (boolean):
- Description: Whether to use an external authentication flow.
- Default: undefined
- Requires restart: Yes

`advanced`

advanced.autoConfigureMemory (boolean):
- Description: Automatically configure Node.js memory limits
- Default: false
- Requires restart: Yes
advanced.dnsResolutionOrder (string):
- Description: The DNS resolution order.
- Default: undefined
- Requires restart: Yes
advanced.excludedEnvVars (array):
- Description: Environment variables to exclude from project context.
- Default:
```
["DEBUG", "DEBUG_MODE"]
```
advanced.bugCommand (object):
- Description: Configuration for the bug report command.
- Default: undefined

`experimental`

experimental.toolOutputMasking.enabled (boolean):
- Description: Enables tool output masking to save tokens.
- Default: true
- Requires restart: Yes
experimental.toolOutputMasking.toolProtectionThreshold (number):
- Description: Minimum number of tokens to protect from masking (most recent tool outputs).
- Default: 50000
- Requires restart: Yes
experimental.toolOutputMasking.minPrunableTokensThreshold (number):
- Description: Minimum prunable tokens required to trigger a masking pass.
- Default: 30000
- Requires restart: Yes
experimental.toolOutputMasking.protectLatestTurn (boolean):
- Description: Ensures the absolute latest turn is never masked, regardless of token count.
- Default: true
- Requires restart: Yes
experimental.enableAgents (boolean):
- Description: Enable local and remote subagents. Warning: Experimental feature, uses YOLO mode for subagents
- Default: false
- Requires restart: Yes
experimental.extensionManagement (boolean):
- Description: Enable extension management features.
- Default: true
- Requires restart: Yes
experimental.extensionConfig (boolean):
- Description: Enable requesting and fetching of extension settings.
- Default: true
- Requires restart: Yes
experimental.extensionRegistry (boolean):
- Description: Enable extension registry explore UI.
- Default: false
- Requires restart: Yes
experimental.extensionReloading (boolean):
- Description: Enables extension loading/unloading within the CLI session.
- Default: false
- Requires restart: Yes
experimental.jitContext (boolean):
- Description: Enable Just-In-Time (JIT) context loading.
- Default: false
- Requires restart: Yes
experimental.useOSC52Paste (boolean):
- Description: Use OSC 52 sequence for pasting instead of clipboardy (useful for remote sessions).
- Default: false
experimental.plan (boolean):
- Description: Enable planning features (Plan Mode and tools).
- Default: false
- Requires restart: Yes

`skills`

skills.enabled (boolean):
- Description: Enable Agent Skills.
- Default: true
- Requires restart: Yes
skills.disabled (array):
- Description: List of disabled skills.
- Default: []
- Requires restart: Yes

`hooksConfig`

hooksConfig.enabled (boolean):
- Description: 훅 시스템을 위한 표준 토글입니다. 비활성화되면 훅이 실행되지 않습니다.
- Default: true
- Requires restart: 예
hooksConfig.disabled (array):
- Description: 비활성화할 훅 이름(명령) 목록입니다. 이 목록에 있는 훅은 구성되어 있어도 실행되지 않습니다.
- Default: []
hooksConfig.notifications (boolean):
- Description: 훅 실행 시 시각적 표시기를 보여줍니다.
- Default: true

`hooks`

hooks.BeforeTool (array):
- Description: 도구 실행 전에 실행되는 훅입니다. 도구 호출을 가로채거나 검증하거나 수정할 수 있습니다.
- Default: []
hooks.AfterTool (array):
- Description: 도구 실행 후에 실행되는 훅입니다. 결과를 처리하거나 출력을 기록하거나 후속 작업을 트리거할 수 있습니다.
- Default: []
hooks.BeforeAgent (array):
- Description: 에이전트 루프가 시작되기 전에 실행되는 훅입니다. 컨텍스트를 설정하거나 리소스를 초기화할 수 있습니다.
- Default: []
hooks.AfterAgent (array):
- Description: 에이전트 루프가 완료된 후 실행되는 훅입니다. 정리 작업을 수행하거나 결과를 요약할 수 있습니다.
- Default: []
hooks.Notification (array):
- Description: Hooks that execute on notification events (errors, warnings, info). Can log or alert on specific conditions.
- Default: []
hooks.SessionStart (array):
- Description: Hooks that execute when a session starts. Can initialize session-specific resources or state.
- Default: []
hooks.SessionEnd (array):
- Description: Hooks that execute when a session ends. Can perform cleanup or persist session data.
- Default: []
hooks.PreCompress (array):
- Description: 채팅 기록 압축 전에 실행되는 훅입니다. 압축 전 대화를 백업하거나 분석할 수 있습니다.
- Default: []
hooks.BeforeModel (array):
- Description: LLM 요청 전에 실행되는 훅입니다. 프롬프트를 수정하거나, 컨텍스트를 주입하거나, 모델 매개변수를 제어할 수 있습니다.
- Default: []
hooks.AfterModel (array):
- Description: LLM 응답 후에 실행되는 훅입니다. 출력을 처리하거나 정보를 추출하거나 상호 작용을 기록할 수 있습니다.
- Default: []
hooks.BeforeToolSelection (array):
- Description: 도구 선택 전에 실행되는 훅입니다. 사용 가능한 도구를 동적으로 필터링하거나 우선순위를 지정할 수 있습니다.
- Default: []

`admin`

admin.secureModeEnabled (boolean):
- Description: true인 경우 yolo 모드 사용을 허용하지 않습니다.
- Default: false
admin.extensions.enabled (boolean):
- Description: false인 경우 확장의 설치 또는 사용을 허용하지 않습니다.
- Default: true
admin.mcp.enabled (boolean):
- Description: false인 경우 MCP 서버 사용을 허용하지 않습니다.
- Default: true
admin.mcp.config (object):
- Description: 관리자가 구성한 MCP 서버입니다.
- Default: {}
admin.skills.enabled (boolean):
- Description: false인 경우 에이전트 스킬 사용을 허용하지 않습니다.
- Default: true

`mcpServers`

사용자 정의 도구를 검색하고 사용하기 위해 하나 이상의 Model-Context Protocol (MCP) 서버에 대한 연결을 구성합니다. Gemini CLI는 구성된 각 MCP 서버에 연결하여 사용 가능한 도구를 검색합니다. 여러 MCP 서버가 동일한 이름의 도구를 노출하는 경우, 충돌을 방지하기 위해 도구 이름 앞에 구성에 정의한 서버 별칭이 접두사로 붙습니다 (예: serverAlias__actualToolName). 호환성을 위해 시스템이 MCP 도구 정의에서 특정 스키마 속성을 제거할 수 있습니다. command, url, 또는 httpUrl 중 하나 이상을 제공해야 합니다. 여러 개가 지정된 경우 우선 순위는 httpUrl, url, command 순입니다.

mcpServers.<SERVER_NAME> (object): 명명된 서버에 대한 서버 매개변수입니다.
- command (string, 선택 사항): 표준 I/O를 통해 MCP 서버를 시작하기 위해 실행할 명령입니다.
- args (array of strings, 선택 사항): 명령에 전달할 인수입니다.
- env (object, 선택 사항): 서버 프로세스에 설정할 환경 변수입니다.
- cwd (string, 선택 사항): 서버를 시작할 작업 디렉토리입니다.
- url (string, 선택 사항): 통신에 Server-Sent Events (SSE)를 사용하는 MCP 서버의 URL입니다.
- httpUrl (string, 선택 사항): 통신에 스트리밍 가능한 HTTP를 사용하는 MCP 서버의 URL입니다.
- headers (object, 선택 사항): url 또는 httpUrl로 요청을 보낼 때 함께 보낼 HTTP 헤더 맵입니다.
- timeout (number, 선택 사항): 이 MCP 서버에 대한 요청의 타임아웃(밀리초)입니다.
- trust (boolean, 선택 사항): 이 서버를 신뢰하고 모든 도구 호출 확인을 우회합니다.
- description (string, 선택 사항): 표시 목적으로 사용할 수 있는 서버에 대한 간략한 설명입니다.
- includeTools (array of strings, 선택 사항): 이 MCP 서버에서 포함할 도구 이름 목록입니다. 지정된 경우 여기에 나열된 도구만 이 서버에서 사용할 수 있습니다(허용 목록 동작). 지정하지 않으면 서버의 모든 도구가 기본적으로 활성화됩니다.
- excludeTools (array of strings, 선택 사항): 이 MCP 서버에서 제외할 도구 이름 목록입니다. 여기에 나열된 도구는 서버에 의해 노출되더라도 모델에서 사용할 수 없습니다. 참고: excludeTools는 includeTools보다 우선합니다. 도구가 두 목록에 모두 있으면 제외됩니다.

`telemetry`

Gemini CLI의 로깅 및 메트릭 수집을 구성합니다. 자세한 내용은 Telemetry를 참조하세요.

Properties:
- enabled (boolean): 텔레메트리 활성화 여부입니다.
- target (string): 수집된 텔레메트리의 대상입니다. 지원되는 값은 local 및 gcp입니다.
- otlpEndpoint (string): OTLP Exporter의 엔드포인트입니다.
- otlpProtocol (string): OTLP Exporter의 프로토콜입니다 (grpc 또는 http).
- logPrompts (boolean): 사용자 프롬프트 내용을 로그에 포함할지 여부입니다.
- outfile (string): target이 local일 때 텔레메트리를 쓸 파일입니다.
- useCollector (boolean): 외부 OTLP 수집기를 사용할지 여부입니다.

`settings.json` 예시

다음은 v0.3.0부터 새로 적용된 중첩 구조를 가진 settings.json 파일의 예입니다.

{
  "general": {
    "vimMode": true,
    "preferredEditor": "code",
    "sessionRetention": {
      "enabled": true,
      "maxAge": "30d",
      "maxCount": 100
    }
  },
  "ui": {
    "theme": "GitHub",
    "hideBanner": true,
    "hideTips": false,
    "customWittyPhrases": [
      "You forget a thousand things every day. Make sure this is one of ’em",
      "Connecting to AGI"
    ]
  },
  "tools": {
    "sandbox": "docker",
    "discoveryCommand": "bin/get_tools",
    "callCommand": "bin/call_tool",
    "exclude": ["write_file"]
  },
  "mcpServers": {
    "mainServer": {
      "command": "bin/mcp_server.py"
    },
    "anotherServer": {
      "command": "node",
      "args": ["mcp_server.js", "--verbose"]
    }
  },
  "telemetry": {
    "enabled": true,
    "target": "local",
    "otlpEndpoint": "http://localhost:4317",
    "logPrompts": true
  },
  "privacy": {
    "usageStatisticsEnabled": true
  },
  "model": {
    "name": "gemini-1.5-pro-latest",
    "maxSessionTurns": 10,
    "summarizeToolOutput": {
      "run_shell_command": {
        "tokenBudget": 100
      }
    }
  },
  "context": {
    "fileName": ["CONTEXT.md", "GEMINI.md"],
    "includeDirectories": ["path/to/dir1", "~/path/to/dir2", "../path/to/dir3"],
    "loadFromIncludeDirectories": true,
    "fileFiltering": {
      "respectGitIgnore": false
    }
  },
  "advanced": {
    "excludedEnvVars": ["DEBUG", "DEBUG_MODE", "NODE_ENV"]
  }
}

쉘 히스토리 (Shell history)

CLI는 실행한 쉘 명령의 기록을 유지합니다. 서로 다른 프로젝트 간의 충돌을 피하기 위해, 이 기록은 사용자 홈 폴더 내의 프로젝트별 디렉토리에 저장됩니다.

위치: ~/.gemini/tmp/<project_hash>/shell_history
- <project_hash>는 프로젝트의 루트 경로에서 생성된 고유 식별자입니다.
- 기록은 shell_history라는 이름의 파일에 저장됩니다.

환경 변수 및 `.env` 파일

환경 변수는 애플리케이션을 구성하는 일반적인 방법이며, 특히 API 키와 같은 민감한 정보나 환경 간에 변경될 수 있는 설정에 유용합니다. 인증 설정에 대해서는 모든 사용 가능한 인증 방법을 다루는 인증 문서를 참조하세요.

CLI는 .env 파일에서 환경 변수를 자동으로 로드합니다. 로드 순서는 다음과 같습니다:

현재 작업 디렉토리의 .env 파일.
찾을 수 없는 경우, .env 파일을 찾거나 프로젝트 루트( .git 폴더로 식별) 또는 홈 디렉토리에 도달할 때까지 상위 디렉토리에서 검색합니다.
그래도 찾을 수 없는 경우, ~/.env (사용자 홈 디렉토리)를 찾습니다.

환경 변수 제외: 일부 환경 변수(DEBUG 및 DEBUG_MODE 등)는 gemini-cli 동작과의 간섭을 방지하기 위해 프로젝트 .env 파일에서 로드되는 것이 자동으로 제외됩니다. .gemini/.env 파일의 변수는 절대 제외되지 않습니다. settings.json 파일의 advanced.excludedEnvVars 설정으로 이 동작을 사용자 정의할 수 있습니다.

GEMINI_API_KEY:
- Your API key for the Gemini API.
- One of several available authentication methods.
- Set this in your shell profile (e.g., ~/.bashrc, ~/.zshrc) or an .env file.
GEMINI_MODEL:
- Specifies the default Gemini model to use.
- Overrides the hardcoded default
- Example: export GEMINI_MODEL="gemini-3-flash-preview"
GEMINI_CLI_HOME:
- Specifies the root directory for Gemini CLI's user-level configuration and storage.
- By default, this is the user's system home directory. The CLI will create a .gemini folder inside this directory.
- Useful for shared compute environments or keeping CLI state isolated.
- Example: export GEMINI_CLI_HOME="/path/to/user/config"
GOOGLE_API_KEY:
- Your Google Cloud API key.
- Required for using Vertex AI in express mode.
- Ensure you have the necessary permissions.
- Example: export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY".
GOOGLE_CLOUD_PROJECT:
- Your Google Cloud Project ID.
- Required for using Code Assist or Vertex AI.
- If using Vertex AI, ensure you have the necessary permissions in this project.
- Cloud Shell note: When running in a Cloud Shell environment, this variable defaults to a special project allocated for Cloud Shell users. If you have GOOGLE_CLOUD_PROJECT set in your global environment in Cloud Shell, it will be overridden by this default. To use a different project in Cloud Shell, you must define GOOGLE_CLOUD_PROJECT in a .env file.
- Example: export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID".
GOOGLE_APPLICATION_CREDENTIALS (string):
- Description: The path to your Google Application Credentials JSON file.
- Example: export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"
GOOGLE_GENAI_API_VERSION:
- Specifies the API version to use for Gemini API requests.
- When set, overrides the default API version used by the SDK.
- Example: export GOOGLE_GENAI_API_VERSION="v1"
OTLP_GOOGLE_CLOUD_PROJECT:
- Your Google Cloud Project ID for Telemetry in Google Cloud
- Example: export OTLP_GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID".
GEMINI_TELEMETRY_ENABLED:
- Set to true or 1 to enable telemetry. Any other value is treated as disabling it.
- Overrides the telemetry.enabled setting.
GEMINI_TELEMETRY_TARGET:
- Sets the telemetry target (local or gcp).
- Overrides the telemetry.target setting.
GEMINI_TELEMETRY_OTLP_ENDPOINT:
- Sets the OTLP endpoint for telemetry.
- Overrides the telemetry.otlpEndpoint setting.
GEMINI_TELEMETRY_OTLP_PROTOCOL:
- Sets the OTLP protocol (grpc or http).
- Overrides the telemetry.otlpProtocol setting.
GEMINI_TELEMETRY_LOG_PROMPTS:
- Set to true or 1 to enable or disable logging of user prompts. Any other value is treated as disabling it.
- Overrides the telemetry.logPrompts setting.
GEMINI_TELEMETRY_OUTFILE:
- Sets the file path to write telemetry to when the target is local.
- Overrides the telemetry.outfile setting.
GEMINI_TELEMETRY_USE_COLLECTOR:
- Set to true or 1 to enable or disable using an external OTLP collector. Any other value is treated as disabling it.
- Overrides the telemetry.useCollector setting.
GOOGLE_CLOUD_LOCATION:
- Your Google Cloud Project Location (e.g., us-central1).
- Required for using Vertex AI in non-express mode.
- Example: export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION".
GEMINI_SANDBOX:
- Alternative to the sandbox setting in settings.json.
- Accepts true, false, docker, podman, or a custom command string.
GEMINI_SYSTEM_MD:
- Replaces the built‑in system prompt with content from a Markdown file.
- true/1: Use project default path ./.gemini/system.md.
- Any other string: Treat as a path (relative/absolute supported, ~ expands).
- false/0 or unset: Use the built‑in prompt. See System Prompt Override.
GEMINI_WRITE_SYSTEM_MD:
- Writes the current built‑in system prompt to a file for review.
- true/1: Write to ./.gemini/system.md. Otherwise treat the value as a path.
- Run the CLI once with this set to generate the file.
SEATBELT_PROFILE (macOS specific):
- Switches the Seatbelt (sandbox-exec) profile on macOS.
- permissive-open: (Default) Restricts writes to the project folder (and a few other folders, see packages/cli/src/utils/sandbox-macos-permissive-open.sb) but allows other operations.
- strict: Uses a strict profile that declines operations by default.
- <profile_name>: Uses a custom profile. To define a custom profile, create a file named sandbox-macos-<profile_name>.sb in your project's .gemini/ directory (e.g., my-project/.gemini/sandbox-macos-custom.sb).
DEBUG or DEBUG_MODE (often used by underlying libraries or the CLI itself):
- Set to true or 1 to enable verbose debug logging, which can be helpful for troubleshooting.
- Note: These variables are automatically excluded from project .env files by default to prevent interference with gemini-cli behavior. Use .gemini/.env files if you need to set these for gemini-cli specifically.
NO_COLOR:
- Set to any value to disable all color output in the CLI.
CLI_TITLE:
- Set to a string to customize the title of the CLI.
CODE_ASSIST_ENDPOINT:
- Specifies the endpoint for the code assist server.
- This is useful for development and testing.

Environment variable redaction

To prevent accidental leakage of sensitive information, Gemini CLI automatically redacts potential secrets from environment variables when executing tools (such as shell commands). This "best effort" redaction applies to variables inherited from the system or loaded from .env files.

Default Redaction Rules:

By Name: Variables are redacted if their names contain sensitive terms like TOKEN, SECRET, PASSWORD, KEY, AUTH, CREDENTIAL, PRIVATE, or CERT.
By Value: Variables are redacted if their values match known secret patterns, such as:
- Private keys (RSA, OpenSSH, PGP, etc.)
- Certificates
- URLs containing credentials
- API keys and tokens (GitHub, Google, AWS, Stripe, Slack, etc.)
Specific Blocklist: Certain variables like CLIENT_ID, DB_URI, DATABASE_URL, and CONNECTION_STRING are always redacted by default.

Allowlist (Never Redacted):

Common system variables (e.g., PATH, HOME, USER, SHELL, TERM, LANG).
Variables starting with GEMINI_CLI_.
GitHub Action specific variables.

Configuration:

You can customize this behavior in your settings.json file:

security.allowedEnvironmentVariables: A list of variable names to never redact, even if they match sensitive patterns.
security.blockedEnvironmentVariables: A list of variable names to always redact, even if they don't match sensitive patterns.

{
  "security": {
    "allowedEnvironmentVariables": ["MY_PUBLIC_KEY", "NOT_A_SECRET_TOKEN"],
    "blockedEnvironmentVariables": ["INTERNAL_IP_ADDRESS"]
  }
}

명령줄 인수 (Command-line arguments)

CLI를 실행할 때 직접 전달된 인수는 해당 세션에 대한 다른 구성을 재정의할 수 있습니다.

--model <model_name> (-m <model_name>):
- 이 세션에 사용할 Gemini 모델을 지정합니다.
- 예: npm start -- --model gemini-3-pro-preview
--prompt <your_prompt> (-p <your_prompt>):
- 명령에 직접 프롬프트를 전달하는 데 사용됩니다. 이것은 비대화형 모드로 Gemini CLI를 호출합니다.
- 스크립팅 예제는 --output-format json 플래그를 사용하여 구조화된 출력을 얻으세요.
--prompt-interactive <your_prompt> (-i <your_prompt>):
- 제공된 프롬프트를 초기 입력으로 사용하여 대화형 세션을 시작합니다.
- 프롬프트는 대화형 세션 내에서 처리되며, 세션 시작 전이 아닙니다.
- stdin에서 입력을 파이핑할 때는 사용할 수 없습니다.
- 예: gemini -i "explain this code"
--output-format <format>:
- Description: 비대화형 모드에 대한 CLI 출력 형식을 지정합니다.
- Values:
  - text: (기본값) 사람이 읽을 수 있는 표준 출력입니다.
  - json: 기계가 읽을 수 있는 JSON 출력입니다.
  - stream-json: 실시간 이벤트를 방출하는 스트리밍 JSON 출력입니다.
- Note: 구조화된 출력 및 스크립팅의 경우 --output-format json 또는 --output-format stream-json 플래그를 사용하세요.
--sandbox (-s):
- 이 세션에 대해 샌드박스 모드를 활성화합니다.
--debug (-d):
- 이 세션에 대해 디버그 모드를 활성화하여 더 자세한 출력을 제공합니다. F12로 디버그 콘솔을 열어 추가 로깅을 확인하세요.
--help (or -h):
- 명령줄 인수에 대한 도움말 정보를 표시합니다.
--yolo:
- 모든 도구 호출을 자동으로 승인하는 YOLO 모드를 활성화합니다.
--approval-mode <mode>:
- 도구 호출에 대한 승인 모드를 설정합니다. 가용 모드:
  - default: 각 도구 호출에 대해 승인 요청 (기본 동작)
  - auto_edit: 편집 도구(replace, write_file)는 자동 승인하고 다른 도구는 요청
  - yolo: 모든 도구 호출 자동 승인 (--yolo와 동일)
  - plan: 도구 호출에 대한 읽기 전용 모드 (실험적 기능인 계획 모드가 활성화되어야 함).
    
    참고: 이 모드는 현재 개발 중이며 완전히 기능하지 않을 수 있습니다.
- --yolo와 함께 사용할 수 없습니다. 새로운 통합 접근 방식인 --yolo 대신 --approval-mode=yolo를 사용하세요.
- 예: gemini --approval-mode auto_edit
--allowed-tools <tool1,tool2,...>:
- 확인 대화상자를 우회할 쉼표로 구분된 도구 이름 목록입니다.
- 예: gemini --allowed-tools "ShellTool(git status)"
--extensions <extension_name ...> (-e <extension_name ...>):
- 세션에 사용할 확장 목록을 지정합니다. 제공되지 않으면 사용 가능한 모든 확장이 사용됩니다.
- 모든 확장을 비활성화하려면 특별한 용어인 gemini -e none을 사용하세요.
- 예: gemini -e my-extension -e my-other-extension
--list-extensions (-l):
- 사용 가능한 모든 확장을 나열하고 종료합니다.
--resume [session_id] (-r [session_id]):
- 이전 채팅 세션을 재개합니다. 가장 최근 세션은 "latest", 세션 인덱스 번호 또는 전체 세션 UUID를 제공하세요.
- session_id가 제공되지 않으면 기본값은 "latest"입니다.
- 예: gemini --resume 5 또는 gemini --resume latest 또는 gemini --resume a1b2c3d4-e5f6-7890-abcd-ef1234567890 또는 gemini --resume
- 더 자세한 내용은 세션 관리를 참조하세요.
--list-sessions:
- 현재 프로젝트의 사용 가능한 모든 채팅 세션을 나열하고 종료합니다.
- 세션 인덱스, 날짜, 메시지 수 및 첫 번째 사용자 메시지의 미리보기를 표시합니다.
- 예: gemini --list-sessions
--delete-session <identifier>:
- 인덱스 번호 또는 전체 세션 UUID로 특정 채팅 세션을 삭제합니다.
- 사용 가능한 세션, 인덱스 및 UUID를 확인하려면 먼저 --list-sessions를 사용하세요.
- 예: gemini --delete-session 3 또는 gemini --delete-session a1b2c3d4-e5f6-7890-abcd-ef1234567890
--include-directories <dir1,dir2,...>:
- 다중 디렉토리 지원을 위해 작업 공간에 추가 디렉토리를 포함합니다.
- 여러 번 지정하거나 쉼표로 구분된 값으로 지정할 수 있습니다.
- 최대 5개의 디렉토리를 추가할 수 있습니다.
- 예: --include-directories /path/to/project1,/path/to/project2 또는 --include-directories /path/to/project1 --include-directories /path/to/project2
--screen-reader:
- 스크린 리더와의 호환성을 높이기 위해 TUI를 조정하는 스크린 리더 모드를 활성화합니다.
--version:
- CLI의 버전을 표시합니다.
--experimental-acp:
- 에이전트를 ACP 모드로 시작합니다.
--allowed-mcp-server-names:
- 허용된 MCP 서버 이름입니다.
--fake-responses:
- 테스트를 위한 가짜 모델 응답이 있는 파일 경로입니다.
--record-responses:
- 테스트를 위해 모델 응답을 기록할 파일 경로입니다.

컨텍스트 파일 (계층적 지시 컨텍스트)

엄밀히 말해 CLI의 동작을 위한 구성은 아니지만, 컨텍스트 파일(기본값 GEMINI.md, context.fileName 설정으로 구성 가능)은 Gemini 모델에 제공되는 지시 컨텍스트("메모리"라고도 함)를 구성하는 데 중요합니다. 이 강력한 기능을 사용하면 프로젝트별 지침, 코딩 스타일 가이드 또는 관련 배경 정보를 AI에 제공하여 응답을 사용자의 필요에 더 맞게 조정하고 정확하게 만들 수 있습니다. CLI에는 로드된 컨텍스트 파일 수를 표시하는 바닥글 표시기와 같은 UI 요소가 포함되어 있어 활성 컨텍스트에 대한 정보를 계속 제공합니다.

목적: 이러한 Markdown 파일에는 상호 작용 중에 Gemini 모델이 인식하기를 원하는 지침, 가이드라인 또는 컨텍스트가 포함되어 있습니다. 시스템은 이 지시 컨텍스트를 계층적으로 관리하도록 설계되었습니다.

컨텍스트 파일 내용 예시 (예: `GEMINI.md`)

다음은 TypeScript 프로젝트의 루트에 있는 컨텍스트 파일에 포함될 수 있는 내용의 개념적 예입니다:

# Project: My Awesome TypeScript Library
 
## General Instructions:
 
- When generating new TypeScript code, please follow the existing coding style.
- Ensure all new functions and classes have JSDoc comments.
- Prefer functional programming paradigms where appropriate.
- All code should be compatible with TypeScript 5.0 and Node.js 20+.
 
## Coding Style:
 
- Use 2 spaces for indentation.
- Interface names should be prefixed with `I` (e.g., `IUserService`).
- Private class members should be prefixed with an underscore (`_`).
- Always use strict equality (`===` and `!==`).
 
## Specific Component: `src/api/client.ts`
 
- This file handles all outbound API requests.
- When adding new API call functions, ensure they include robust error handling
  and logging.
- Use the existing `fetchWithRetry` utility for all GET requests.
 
## Regarding Dependencies:
 
- Avoid introducing new external dependencies unless absolutely necessary.
- If a new dependency is required, please state the reason.

이 예제는 일반적인 프로젝트 컨텍스트, 특정 코딩 규칙, 특정 파일이나 구성 요소에 대한 메모를 제공하는 방법을 보여줍니다. 컨텍스트 파일이 관련성이 높고 정확할수록 AI가 더 잘 지원할 수 있습니다. 규칙과 컨텍스트를 확립하기 위해 프로젝트별 컨텍스트 파일을 적극 권장합니다.

계층적 로딩 및 우선순위: CLI는 여러 위치에서 컨텍스트 파일(예: GEMINI.md)을 로드하여 정교한 계층적 메모리 시스템을 구현합니다. 이 목록에서 더 아래쪽에 있는(더 구체적인) 파일의 내용은 일반적으로 위쪽에 있는(더 일반적인) 파일의 내용을 덮어쓰거나 보완합니다. 정확한 연결 순서와 최종 컨텍스트는 /memory show 명령을 사용하여 검사할 수 있습니다. 일반적인 로딩 순서는 다음과 같습니다:
1. 전역 컨텍스트 파일:
  - 위치: ~/.gemini/<configured-context-filename> (예: 사용자 홈 디렉토리의 ~/.gemini/GEMINI.md).
  - 범위: 모든 프로젝트에 대한 기본 지침을 제공합니다.
2. 프로젝트 루트 및 상위 컨텍스트 파일:
  - 위치: CLI는 현재 작업 디렉토리에서 구성된 컨텍스트 파일을 검색한 후, 프로젝트 루트(.git 폴더로 식별) 또는 홈 디렉토리에 도달할 때까지 각 상위 디렉토리에서 검색합니다.
  - 범위: 전체 프로젝트 또는 상당 부분과 관련된 컨텍스트를 제공합니다.
3. 하위 디렉토리 컨텍스트 파일 (상황별/로컬):
  - 위치: CLI는 또한 현재 작업 디렉토리 아래 하위 디렉토리에서 구성된 컨텍스트 파일을 검색합니다 (node_modules, .git 등과 같은 일반적인 무시 패턴을 존중함). 이 검색 범위는 기본적으로 200개 디렉토리로 제한되지만, settings.json 파일의 context.discoveryMaxDirs 설정으로 구성할 수 있습니다.
  - 범위: 프로젝트의 특정 구성 요소, 모듈 또는 하위 섹션과 관련된 매우 구체적인 지침을 허용합니다.
연결 및 UI 표시: 발견된 모든 컨텍스트 파일의 내용은 연결되어(출처와 경로를 나타내는 구분 기호 포함) Gemini 모델에 대한 시스템 프롬프트의 일부로 제공됩니다. CLI 바닥글에는 로드된 컨텍스트 파일 수가 표시되어 활성 지시 컨텍스트에 대한 빠른 시각적 단서를 제공합니다.
콘텐츠 가져오기: @path/to/file.md 구문을 사용하여 다른 Markdown 파일을 가져와 컨텍스트 파일을 모듈화할 수 있습니다. 자세한 내용은 메모리 가져오기 프로세서 문서를 참조하세요.
메모리 관리 명령:
- /memory refresh를 사용하여 구성된 모든 위치에서 모든 컨텍스트 파일을 강제로 다시 스캔하고 다시 로드합니다. 이렇게 하면 AI의 지시 컨텍스트가 업데이트됩니다.
- /memory show를 사용하여 현재 로드된 결합된 지시 컨텍스트를 표시하여 AI가 사용하는 계층 구조와 내용을 확인할 수 있습니다.
- /memory 명령 및 하위 명령(show 및 refresh)에 대한 자세한 내용은 명령 문서를 참조하세요.

이러한 구성 계층과 컨텍스트 파일의 계층적 특성을 이해하고 활용하면, AI의 메모리를 효과적으로 관리하고 Gemini CLI의 응답을 특정 요구 사항과 프로젝트에 맞게 조정할 수 있습니다.

샌드박스 (Sandboxing)

Gemini CLI는 시스템을 보호하기 위해 샌드박스 환경 내에서 잠재적으로 안전하지 않은 작업(쉘 명령 및 파일 수정 등)을 실행할 수 있습니다.

샌드박스는 기본적으로 비활성화되어 있지만 몇 가지 방법으로 활성화할 수 있습니다.

--sandbox 또는 -s 플래그 사용.
GEMINI_SANDBOX 환경 변수 설정.
--yolo 또는 --approval-mode=yolo를 사용하면 샌드박스가 기본적으로 활성화됩니다.

기본적으로 미리 빌드된 gemini-cli-sandbox Docker 이미지를 사용합니다.

프로젝트별 샌드박스 요구 사항의 경우 프로젝트 루트 디렉토리에 .gemini/sandbox.Dockerfile에 사용자 정의 Dockerfile을 만들 수 있습니다. 이 Dockerfile은 기본 샌드박스 이미지를 기반으로 할 수 있습니다.

FROM gemini-cli-sandbox
 
# Add your custom dependencies or configurations here
# For example:
# RUN apt-get update && apt-get install -y some-package
# COPY ./my-config /app/my-config

.gemini/sandbox.Dockerfile이 존재하면 Gemini CLI를 실행할 때 BUILD_SANDBOX 환경 변수를 사용하여 사용자 정의 샌드박스 이미지를 자동으로 빌드할 수 있습니다.

BUILD_SANDBOX=1 gemini -s

사용 통계 (Usage statistics)

Gemini CLI를 개선하는 데 도움이 되도록 익명화된 사용 통계를 수집합니다. 이 데이터는 CLI 사용 방식을 이해하고 일반적인 문제를 식별하며 새로운 기능의 우선순위를 정하는 데 도움이 됩니다.

수집하는 정보:

도구 호출: 호출된 도구의 이름, 성공 또는 실패 여부, 실행에 걸린 시간을 기록합니다. 도구에 전달된 인수나 도구에서 반환된 데이터는 수집하지 않습니다.
API 요청: 각 요청에 사용된 Gemini 모델, 요청 기간, 성공 여부를 기록합니다. 프롬프트 또는 응답의 내용은 수집하지 않습니다.
세션 정보: 활성화된 도구 및 승인 모드와 같은 CLI 구성에 대한 정보를 수집합니다.

수집하지 않는 정보:

개인 식별 정보 (PII): 이름, 이메일 주소, API 키와 같은 개인 정보는 수집하지 않습니다.
프롬프트 및 응답 내용: 사용자의 프롬프트 내용이나 Gemini 모델의 응답은 기록하지 않습니다.
파일 내용: CLI가 읽거나 쓰는 파일의 내용은 기록하지 않습니다.

수집 거부 방법:

settings.json 파일의 privacy 카테고리에서 usageStatisticsEnabled 속성을 false로 설정하여 언제든지 사용 통계 수집을 거부할 수 있습니다:

{
  "privacy": {
    "usageStatisticsEnabled": false
  }
}

명령어 참조 키보드 단축키

Gemini CLI 구성 (Gemini CLI configuration)

구성 계층 (Configuration layers)

설정 파일 (Settings files)

프로젝트의 .gemini 디렉터리

Available settings in settings.json

general

output

ui

ide

privacy

model

modelConfigs

agents

context

tools

mcp

useWriteTodos

security

advanced

experimental

skills

hooksConfig

hooks

admin

mcpServers

telemetry

settings.json 예시