Google의 오픈 소스 Gemini CLI—Gemini를 쉘로 가져오는 터미널 기반 AI 에이전트—는 출시 이후 빠르게 성숙하여 이제 풍부한 구성, 프로젝트 컨텍스트 파일 (GEMINI.md / .gemini), 사용자 지정 슬래시 명령, 워크스페이스 디렉터리 제어를 지원합니다. 이 프로젝트는 GitHub(공식 리포지토리)에서 활발히 발전 중이며, 관대한 할당량으로 퍼블릭 프리뷰에 들어갔고, 다른 개발자 도구(에디터 통합 및 CI/Actions)와도 통합되고 있습니다. 하지만 팀이 확장되거나 드라이브 간 또는 제한적인 환경(컨테이너, 회사 관리 노트북, Cloud Shell, Windows 시스템)에서 작업할 때, 곧 실용적인 질문에 부딪히게 됩니다: Gemini는 파일을 어디에 저장하며, Gemini가 읽고 쓰는 디렉터리를 어떻게 변경할 수 있을까요?
What is Gemini CLI?
Gemini CLI는 Gemini 모델의 성능을 터미널로 직접 가져오는 Google의 오픈 소스 커맨드 라인 AI 에이전트입니다. 코딩 지원, 파일 및 프로젝트 검사, 셸 명령 실행(보호장치 포함), Google Search, Model Context Protocol(MCP) 확장, Gemini에 포함된 미디어 생성 도구 등의 통합을 위한 대화형 에이전트 기능을 제공합니다. CLI는 경량, 스크립트화 가능, 확장 가능하도록 설계되었으며, 공식 리포지토리에서 제공되고 손쉬운 설치를 위해 패키징되어 있습니다.
Why the directory matters
Gemini CLI는 .gemini 디렉터리 내에 구성(예: settings.json), 시스템 프롬프트 또는 컨텍스트(GEMINI.md), 캐시된 자격 증명, 텔레메트리 식별자 및 기타 지속 상태를 저장합니다. 해당 디렉터리의 위치는 다음을 좌우합니다:
- CLI가 로드하는 설정(전역 vs. 프로젝트별),
- 에이전트가 읽을 “메모리” 파일,
- 자격 증명이 캐시되는 위치(로그인 동작에 영향),
- 사용자 지정 구성 리포를 제공하려는 경우의 머신 간 또는 CI 재현성.
디렉터리를 이해하고(필요하다면) 변경하는 것은 다중 프로젝트 워크플로, CI, 컨테이너화된 배포, 중앙 집중식 구성 저장소를 사용하는 팀에서 유용합니다.
Where does Gemini CLI store configuration by default?
기본적으로 CLI는 .gemini 디렉터리를 사용합니다. 대부분의 사용자 설치에서는 ~/.gemini(홈 디렉터리의 .gemini 폴더)로 해석됩니다. CLI는 또한 프로젝트 루트의 프로젝트 수준 .gemini 파일(예: .gemini/settings.json)을 지원하며, 해당 프로젝트 폴더에서 작업할 때 사용자 설정을 재정의합니다. 시스템 수준 설정은 적용 가능한 경우 OS별 위치(예: Linux의 /etc/ 또는 Windows의 %PROGRAMDATA%)에서 읽습니다. 일반적인 경로:
- Linux / macOS:
~/.gemini/(예:/home/alice/.gemini또는/Users/alice/.gemini). - Windows:
%USERPROFILE%\.gemini(예:C:\Users\Alice\.gemini).
.gemini내부에는 일반적으로settings.json,GEMINI.md,commands/, 로컬 캐시가 있습니다. CLI는 프로젝트 수준 설정을 위해 프로젝트 루트의.gemini/폴더도 읽습니다.
이 기본값은 중요합니다: 역사적으로 구성 디렉터리는 홈 디렉터리의 .gemini로 하드코딩되어 왔습니다.
How can I change or redirect Gemini CLI’s configuration directory?
가장 단순한 방법(원하는 폴더에서 작업)부터 보다 견고한 방법(환경 변수 또는 파일시스템 리디렉션)까지 여러 실용적인 방법이 있습니다. 런타임 환경(로컬 개발 머신 vs. CI)을 제어하는지, 사용하는 OS, 일시적 변경을 원하는지 영구적 변경을 원하는지에 따라 접근 방식을 선택하세요.
1) Use a project-level .gemini (recommended for per-project settings)
프로젝트별 설정을 원한다면, 프로젝트 루트에 .gemini 하위 디렉터리를 만들고 그 안에 settings.json, GEMINI.md 및 기타 프로젝트 파일을 배치하세요. 프로젝트 디렉터리에서 실행하면 Gemini CLI는 프로젝트 설정을 우선합니다:
your-project/├─ .gemini/│ ├─ settings.json│ └─ GEMINI.md└─ src/
셸이 your-project/에 있을 때 gemini를 시작하면 CLI는 해당 트리에서 .gemini 파일을 가져옵니다(프로젝트 컨텍스트를 찾기 위해 상위로 검색). 이는 프로젝트별 구성에 가장 안전하고 명시적인 방법입니다.
2) Use documented environment variables (when supported)
Gemini CLI 코드베이스와 문서는 동작을 변경하는 데 사용되는 여러 환경 변수를 참조합니다. 일부는 시스템 설정 또는 특수 파일 재정의를 위한 것입니다:
GEMINI_API_KEY,GEMINI_MODEL등은 인증 및 모델 선택에 일반적으로 사용됩니다.- 코드베이스와 문서에는
GEMINI_CLI_SYSTEM_SETTINGS_PATH(시스템 설정 경로 재정의에 사용) 같은 변수와 코드에서 사용되는 기본.gemini이름을 나타내는 상수GEMINI_CONFIG_DIR에 대한 참조가 있습니다. 커뮤니티 요청과 PR에서는 전체 구성 디렉터리를 재배치할 수 있도록GEMINI_CONFIG_DIR환경 변수를 추가하거나 존중하자는 제안이 있습니다.
Example (bash / macOS / Linux):
# Temporary for this shell sessionexport GEMINI_CONFIG_DIR="$HOME/custom_gemini_dir"# Or override system settings path if your install supports it:export GEMINI_CLI_SYSTEM_SETTINGS_PATH="/etc/my-gemini/system.settings.json"# Then rungemini
PowerShell (Windows):
$env:GEMINI_CONFIG_DIR = 'C:\Users\you\CustomGemini'gemini
중요한 주의 사항: 최신 커뮤니티 논의와 이슈에 따르면
GEMINI_CONFIG_DIR는 여러 곳에서 요청되고 코드에 참조되었지만—플랫폼별 버그와 일관되지 않은 동작(특히 Windows)이 보고되었습니다. 즉, 환경 변수 기반 리디렉션이 모든 플랫폼이나 릴리스에서 일괄적으로 신뢰할 수 있는 것은 아닙니다. 여기에 의존한다면 설치된 버전의 Gemini CLI 릴리스 노트와 리포지토리 이슈를 확인하세요.
3) Add directories to Gemini’s workspace inside a session
다른 디렉터리를 Gemini가 인지하도록 하고 싶다면(컨텍스트로 파일을 읽을 수 있게), 대화형 /directory 명령 세트를 사용할 수 있습니다. 예를 들어:
/directory add path/to/another/project/directory list
이는 구성 디렉터리를 이동하지는 않지만, 에이전트가 워크스페이스 컨텍스트에 다른 디렉터리의 파일을 포함하도록 허용합니다. 글로벌 구성을 변경하지 않고 다른 리포지토리를 참조하게 하고 싶을 때 유용합니다.
4) Create a symlink or filesystem bind (practical workaround)
CLI가 환경 재정의를 수용하지 않거나 교차 프로세스에서 확실한 해결책이 필요하다면, 파일시스템 리디렉션을 사용하세요:
On Unix/macOS:
# move the original config foldermv ~/.gemini ~/gemini_backup# create a symlink to your desired locationln -s /path/to/central/gemini-config ~/.gemini
On Windows (PowerShell administrative prompt):
# Move the original directoryMove-Item -Path $env:USERPROFILE\.gemini -Destination C:\GeminiConfigBackup# Create a junction (administrator)New-Item -ItemType Junction -Path $env:USERPROFILE\.gemini -Target C:\CentralGeminiConfig
이 방법은 CLI가 네이티브 지원 없이도 원하는 위치에서 읽도록 강제합니다. 참고: 심볼릭 링크/정션은 적절한 파일시스템 권한이 필요하며, 컨테이너나 Windows 환경에서는 동작이 다를 수 있습니다. 주의해서 사용하세요(아래 “Windows-specific notes” 참조).
5) Change the effective home directory for the process (container/CI trick)
CI, 컨테이너, 일시적 환경에서 실행할 때 gemini 프로세스의 $HOME(Unix) 또는 %USERPROFILE%(Windows) 환경 변수를 변경하여 기본 ~/.gemini가 제어 가능한 경로로 해석되게 할 수 있습니다:
# Run gemini with a custom HOME (bash)HOME=/ci/workspace/you gemini --some-command# Or in a container DockerfileENV HOME=/app/userRUN mkdir -p /app/user/.geminiCOPY config /app/user/.gemini
이는 CI 재현성에 유용하지만 유의하세요: HOME을 변경하면 다른 도구와 인증 흐름(예: Google OAuth 캐시)에 영향을 줄 수 있으므로, 이 기법은 격리된 컨테이너나 프로세스 수준 래퍼로 제한하세요.
How can I install and use Gemini CLI via CometAPI?
간단한 답변: 실용적인 경로는 두 가지입니다 — (A) CometAPI를 통해 Gemini 모델을 직접 호출(권장 및 가장 간단)하거나, (B) 사용자 지정 베이스 URL을 지원하는 Gemini CLI 릴리스를 사용(일부 릴리스/PR에서 추가)하거나 Gemini CLI 요청을 CometAPI/OpenAI 스타일 호출로 변환하는 작은 로컬 프록시를 실행하여 공식 Gemini CLI가 CometAPI와 통신하도록 만드는 것입니다.
What is CometAPI?
CometAPI는 OpenAI 스타일 HTTP API 뒤에서 수백 개의 서드파티 모델(일부는 Google의 Gemini 패밀리 포함)을 제공하는 API 집계/게이트웨이입니다. 가입하고 베어러 API 키를 받은 다음 https://api.cometapi.com/v1/chat/completions 같은 엔드포인트를 호출합니다. CometAPI는 Authorization 헤더의 표준 베어러 토큰을 사용합니다.
CometAPI를 사용하는 이유? 통합을 촉진하기 위해 공식 API보다 낮은 가격을 제공합니다. Gemini CLI Installation and Usage Guide:
How can I call Gemini models directly via CometAPI? (Recommended)
목표가 단순히 Gemini 모델을 사용하는 것이고 Gemini CLI 기능이 꼭 필요하지 않다면, CometAPI를 직접 호출하는 방식이 간단하고 신뢰할 수 있습니다.
export COMET_KEY="sk-xxxx"curl -s -X POST "https://api.cometapi.com/v1/chat/completions" \ -H "Authorization: Bearer $COMET_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-2.5-pro", "messages": [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Summarize the 3 key benefits of unit tests."} ], "max_tokens": 300 }' | jq .
이러한 직접 호출은 Gemini CLI에 의존하지 않고도 스크립트, 앱 또는 CI에 CometAPI를 통합할 수 있게 해줍니다.
Can I make Gemini CLI use CometAPI?
일부 Gemini CLI 버전/PR은 Gemini API 베이스 URL을 재정의하는 환경 변수를 추가합니다. 설치된 gemini가 사용자 지정 Gemini 베이스 URL 구성 + CometAPI 키 사용을 지원한다면, 이를 CometAPI로 지정하고 CometAPI 키를 GEMINI_API_KEY로 설정할 수 있습니다(CLI는 Gemini API 키 인증을 위한 변수 이름으로 GEMINI_API_KEY를 기대합니다).
Example:
# example env — *check your gemini-cli docs for exact var names*export GEMINI_API_KEY="sk-xxxxx" # CometAPI keyexport GOOGLE_GEMINI_BASE_URL="https://api.cometapi.com/v1" # if supportedgemini # run the CLI; it will use the configured base URL
Troubleshooting: common problems and fixes
Problem: Gemini can’t see files in another repo
- 시작할 때
gemini --include-directories /path/to/repo를 시도하세요. 또는 세션 중:/directory add /path/to/repo. - 리포가 네트워크 마운트에 있다면, 권한을 확인하고 CLI 프로세스 사용자에게 파일 읽기 권한이 있는지 확인하세요.
.gemini를 이동하기 위해 심볼릭 링크를 사용했다면, CLI가GEMINI.md와settings.json에 대해 심볼릭 링크를 따라가는지 확인하세요(일부 버전은 보안상의 이유로 특정 심볼릭 링크를 따라가지 않습니다).
Problem: gemini fails to create ~/.gemini on Windows (EPERM)
이는 일반적으로 프로세스에 %USERPROFILE%에 쓸 권한이 없음을 의미합니다. 해결 방법:
- 터미널을 관리자 권한으로 실행하거나 폴더 권한을 조정하세요.
- 심볼릭 링크를 통해 사용자 지정 구성 위치를 설정하거나, 지원되는 경우 환경 변수로 설정하세요(향후
GEMINI_CONFIG_DIR지원을 주시하세요).
Problem: cd doesn’t change working dir inside shell mode
일부 플랫폼에서 인정된 이슈입니다. 권장 사항: Gemini CLI 프로세스 외부에서 셸 명령을 실행하거나 /directory add로 디렉터리를 추가하세요.
Problem: CometAPI model names don’t match what I expect
/v1/models 엔드포인트를 호출해 JSON을 확인하세요. 모델 ID에는 종종 정확한 변형 문자열(예: gemini-2.5-flash-preview-04-17)이 포함됩니다. 요청에 해당 문자열을 그대로 사용하세요.
Conclusion
Gemini CLI의 기본 설계는 합리적이고 발견 가능한 동작을 지향합니다: 사용자 수준 기본값을 위한 전역 ~/.gemini와 리포별 재정의를 위한 프로젝트 .gemini. 커뮤니티는 다중 사용자, 컨테이너화, 엔터프라이즈 환경에 더 친화적이도록 네이티브 구성 가능성(명시적 환경 변수나 플래그)을 촉구해 왔습니다.
How to change the Gemini CLI directory:
Overview: Gemini CLI는 사용자 범위의 구성 및 컨텍스트 파일을 .gemini 디렉터리(일반적으로 ~/.gemini)에 저장합니다. CLI가 사용하는 디렉터리에 영향을 주는 방법은 (1) 현재 작업 디렉터리의 프로젝트 수준 .gemini에 의존, (2) 지원되는 경우 환경 변수나 CLI 옵션 사용, (3) 대화형 세션 내에서 워크스페이스 디렉터리 추가, (4) 네이티브 옵션이 없을 때 파일시스템 기법(심볼릭 링크, 바인드 마운트, 홈/프로필 변수 변경) 사용이 있습니다.
시작하려면 Playground에서 Gemini 3 Pro 같은 Gemini 모델의 기능을 탐색하고 자세한 지침은 API guide를 참고하세요. 액세스 전에 CometAPI에 로그인하고 API 키를 발급받았는지 확인하세요. CometAPI는 통합을 돕기 위해 공식 가격보다 훨씬 낮은 가격을 제공합니다.
Ready to Go?→ Free trial of gemini models !
