Antigravity CLI 설정 문서

한 줄 요약: Antigravity 공식 문서 "Settings"의 CLI 절. Antigravity CLI의 설정 파일 ~/.gemini/antigravity-cli/settings.json이 어떻게 읽히고 저장되는지, /config 설정 패널, 실행 플래그로 한 세션만 바꾸기, 화면 모드, 설정 키(권한·샌드박스·표시·편집기·대화·크레딧), 단축키 파일 keybindings.json, 그리고 훅·MCP·플러그인이 각자 다른 파일에 있다는 점을 적는다.

원본 정보#

제목: Settings ("Available on: Antigravity App, Antigravity CLI, Antigravity IDE")
발행: Antigravity 공식 문서(antigravity.google). 원문 .md와 HTML 페이지 모두 발행일·갱신일 표기가 없다(원본 날짜 미상).
URL: https://antigravity.google/docs/settings?tab=cli (새 창) (이전 문서가 링크한 /docs/cli/settings는 이 주소로 리디렉트된다. 받은 주소는 원문 마크다운 https://antigravity.google/docs/settings.md)
수집(fetch)일: 2026-10-29. 경로, 키 이름, 기본값, 버전 조건은 이 날짜 기준이다.
범위: 원문 .md는 App·CLI·IDE 세 탭을 한 파일에 담는다. 이 위키는 CLI 절(## Antigravity CLI)을 중심으로 정리하고, App·IDE 절은 아래 "CLI 밖의 절"에 짧게만 적는다.

핵심 주장#

설정은 JSON 파일 하나에, 기본값과 다른 값만 저장한다. 설정 파일은 ~/.gemini/antigravity-cli/settings.json이다. CLI는 "sparse persistence"(기본값과 다른 값만 디스크에 쓰기)를 쓴다. /config, /model, /effort, /statusline, /title, /permissions로 바꾸거나 권한 확인 창에서 항상 허용·거부를 고르면 기본값과 다른 키만 저장하고, 기본값으로 되돌리면 그 키를 지운다. 파일은 한 번에 바꿔 쓰고 내 사용자만 읽을 수 있게(0600) 한다. 시작할 때 올바른 파일은 CLI 형식으로 다시 쓰며 기본값인 키를 지운다. 모르는 키(예: $schema, 더 새 버전의 설정)는 무시하되 지우지 않는다. → Antigravity CLI 명령·설정 레퍼런스, Antigravity CLI 설정 바꾸기·확인·문제 해결
설정 파일에 문제가 있으면 세션 전에 알려 준다. 키의 타입이 틀리거나 모르는 값이거나 올바른 JSON이 아니면 Settings Error 화면이 파일과 문제를 알려 주고, 사용자가 고를 때까지 파일을 바꾸지 않는다. 선택지는 셋이다: 종료하고 직접 고치기, 이번 세션만 기본값으로 계속하기(값이 틀린 경우 그 키만 기본값을 쓰고 다음 저장 때 틀린 값을 버린다. JSON이 깨진 경우 모두 기본값을 쓰고 고칠 때까지 설정 변경을 저장하지 않는다), 기본값으로 덮어쓰기(확인 뒤 settings.json.corrupted.<timestamp>로 사본을 남기고 파일 안의 권한 규칙까지 모두 기본값으로 되돌린다). → Antigravity CLI 설정 바꾸기·확인·문제 해결
훅·MCP·플러그인·단축키는 settings.json이 아니라 각자 파일에 둔다. 단축키는 ~/.gemini/antigravity-cli/keybindings.json(/keybindings로 편집기에서 연다). 훅은 전역 ~/.gemini/config/hooks.json이나 워크스페이스 <workspace>/.agents/hooks.json이고, /hooks가 훅을 추가·편집·켜고 끄며 새 훅은 전역 파일에 저장한다. 원본은 "Hooks don't go in settings.json: the CLI keeps a hooks key there but never loads it."라고 쓴다. MCP 서버는 전역 ~/.gemini/config/mcp_config.json(/mcp로 관리)이나 워크스페이스 <workspace>/.agents/mcp_config.json이고, 두 파일에 같은 이름이 있으면 이미 실행 중인 서버가 그 이름을 유지하므로 전역 서버와 다른 이름을 쓰라고 한다. 플러그인은 ~/.gemini/config/plugins/<plugin>/ 또는 워크스페이스 <workspace>/.agents/plugins/<plugin>/에 설치되고, 각 플러그인은 plugin.json 매니페스트를 가질 수 있다. → Antigravity CLI, 훅, MCP, 플러그인
권한·샌드박스 설정에는 조건이 붙는다. agentMode(default·accept-edits·auto·plan)와 toolPermission(request-review·proceed-in-sandbox·strict·always-proceed)이 에이전트가 묻지 않고 할 수 있는 일을 정한다. permissions의 deny 규칙은 모든 모드에서 동작을 막는다. auto는 Preview이고 macOS·Linux v1.3.5+, Windows v1.4.4+에서 되며 business·enterprise 계정은 쓸 수 없고, 쓸 수 없는 곳에서 auto로 설정하면 default로 시작한다. v1.4.4부터 기기에서 샌드박스를 쓸 수 없으면(예: Windows 10, 이전 Windows 11 빌드, 권한 없는 사용자 네임스페이스를 막는 Linux 호스트·일부 컨테이너) Sandbox Mode는 효과가 없고, 저장된 proceed-in-sandbox는 request-review처럼 동작한다. → 권한 모드, 샌드박스
실행 플래그는 그 세션에만 적용된다. 예: agy --sandbox --model="Gemini 3.8 Flash"(모델 이름은 원본 당시 예시). 플래그가 설정을 덮으면 /config가 값 뒤에 덮은 플래그를 적고(예: Sandbox Mode on (overridden by --sandbox)), 플래그 값은 settings.json에 저장되지 않는다. → Antigravity CLI 설정 바꾸기·확인·문제 해결

CLI 절의 그 밖의 내용 (2026-10-29 기준)#

편집기 자동 완성: 파일 맨 위에 "$schema": "https://antigravity.google/schemas/v1/settings.json"을 넣으면 VS Code·JetBrains 같은 편집기가 자동 완성·설명·검증을 해 준다. CLI는 $schema를 무시하고 저장할 때도 남긴다.
/config 패널: /config(별칭 /settings)를 입력하면 프롬프트 아래에 Settings 패널이 열린다. ↑/↓로 이동하거나 입력해 Search로 거르고, ←/→로 값을 바꾸거나 Enter로 선택지를 열어 고른다. 바꾼 값은 바로 저장된다. Esc로 닫는다(검색어가 있으면 첫 Esc는 검색어를 지운다).
화면 모드(altScreenMode): default(대화는 터미널 스크롤백에 인라인으로, diff 보기·아티팩트 보기·/help 같은 전체 화면은 대체 화면에서), always(TUI 전체를 대체 화면에서, 자체 스크롤·마우스 휠·스크롤바. iTerm2·Ghostty·WezTerm 같은 고급 터미널의 로컬 작업에 권장), never(settings.json에서만, 대체 화면을 쓰지 않음. 원격 SSH, tmux·screen, 저대역 원격 세션에 권장). 터미널이 대체 화면을 지원하지 않으면 항상 인라인이다.
테마(colorScheme): terminal(기본), light, solarized light, colorblind-friendly light, dark, solarized dark, colorblind-friendly dark, tokyo night.
settings.json에서만 바꾸는 키: clearScrollbackOnResize, disableSlashCommands, historySize, model, modelProvider("gemini"면 GEMINI_API_KEY로 Gemini API에 직접 요청), trustedWorkspaces(CLI가 물었을 때 신뢰한 폴더, CLI가 직접 추가), useTerminalCursor.
객체 키: permissions(allow·ask·deny 규칙, action(target) 형식, deny가 ask보다, ask가 allow보다 앞섬, 파싱 못 한 규칙은 무시, /permissions의 Global 범위이고 Project·Shared 범위 규칙과 합쳐짐), statusLine·title(내 스크립트로 상태 줄·창 제목 그리기, true/false로 쓰면 스크립트가 돌지 않음), sandboxProxy(샌드박스 안 명령의 네트워크를 내 HTTP 프록시로, 샌드박스가 켜져 있을 때만, 그때는 프록시가 read_url 규칙을 강제해야 함, 짝이 빠지면 무시), customModelsConfig(Gemini API 키를 쓸 때 /model에 모델 추가), gcp("Use a Google Cloud project" 로그인 옵션이 저장하는 프로젝트 ID와 위치 global·us·eu).
단축키: keybindings.json은 TUI 동작 하나를 키 배열에 대응시킨다(예: "cli.clear_screen": ["ctrl+l"]). 빈 배열 []이면 기본 단축키를 끈다. 형식이 잘못된 동작은 기본값으로 돌아가고 나머지 올바른 대응은 읽는다. cli.exit(Ctrl+D·Ctrl+C)와 cli.enter(Enter)는 보호돼 끌 수 없다. 모두 기본값으로 되돌리려면 rm ~/.gemini/antigravity-cli/keybindings.json.
텔레메트리: /config의 Enable Telemetry는 settings.json이 아니라 계정에 저장되고, business 계정은 항상 꺼져 있다. useG1Credits(플랜 할당량을 다 쓴 뒤 AI 크레딧 사용, 기본 꺼짐)는 business 계정에 보이지 않는다.

CLI 밖의 절 (위키 범위 밖, 짧게)#

App: Cmd + , 로 설정을 열고, 전역·프로젝트·독립 대화·기타 네 범위로 나눈다. 권한 프리셋은 Request Review, Default, Auto(Preview, v2.23.0+), Turbo다. business·enterprise 계정(Gemini Enterprise의 Antigravity 포함)은 프리셋 대신 이전 권한 설정을 쓴다.
IDE: 터미널 자동 실행(Request Review·Always Proceed), 워크스페이스 밖 파일 접근, strict 모드(브라우저 URL 허용·거부 목록, .gitignore 존중, 워크스페이스 격리), 터미널 샌드박스(지금은 기본 꺼짐, macOS·Linux 지원, macOS는 Seatbelt sandbox-exec, Linux는 커널 네임스페이스)를 다룬다. strict 모드를 켜면 샌드박스가 네트워크 거부 상태로 자동으로 켜진다고 적는다.

원본에 없는 것#

이 문서는 Hooks 문서(Antigravity 훅 문서)가 적은 "~/.gemini/antigravity-cli/settings.json 안의 훅"과 반대로 말한다. 두 문서가 어느 시점·버전 기준인지는 둘 다 날짜 표기가 없어 알 수 없다. 두 주장은 Antigravity CLI의 "설정 파일" 절에 나란히 두었고, 위키는 이 문서 기준으로 정리했다(정리됨 콜아웃).
플러그인 설치 경로(~/.gemini/config/plugins/<plugin>/)는 Rules 문서(Antigravity 규칙 문서)의 ~/.gemini/antigravity-cli/plugins/<plugin_name>/rules/와 다르다. 같은 절에 나란히 두었다.
--dangerously-skip-permissions 같은 권한 우회 플래그와 deny 규칙의 관계는 이 문서에 없다(플래그 목록은 CLI reference 문서).
설정 파일 우선순위(전역·프로젝트 설정 파일이 따로 있는지)는 말하지 않는다. 권한 규칙만 Global·Project·Shared 범위를 합친다고 적는다.