한 줄 요약: Antigravity 공식 문서 "CLI troubleshooting". Antigravity CLI에서 자주 나는 네 가지 문제(agy: command not found 경로 문제, 키링 잠김으로 토큰을 못 읽는 문제, SSH에서 이미지 붙여넣기 실패, 자동 업데이트 잠금)의 증상·원인·해결 명령을 운영체제별로 적는다.
원본 정보#
- 제목: CLI troubleshooting
- 발행: Antigravity 공식 문서(antigravity.google). 원문 .md와 HTML 페이지 모두 발행일·갱신일 표기가 없다(원본 날짜 미상).
- URL: https://antigravity.google/docs/cli/troubleshooting (새 창) (받은 주소는 원문 마크다운
https://antigravity.google/docs/cli/troubleshooting.md) - 수집(fetch)일: 2026-10-29. 경로, 명령, 환경 변수 이름은 이 날짜 기준이다.
핵심 주장#
agy: command not found는 설치 폴더가 PATH에 없어서다. 설치 도구는 실행 파일을~/.local/bin(Windows는C:\Users\<username>\AppData\Local\agy\bin)에 내려받는데, 셸의$PATH가 이 폴더를 보지 않으면 이 오류가 난다. macOS·Linux는 셸 설정 파일(~/.bashrc또는~/.zshrc) 끝에export PATH="~/.local/bin:$PATH"를 확인하거나 넣고source ~/.zshrc로 다시 읽는다. Windows는 관리자 PowerShell에서 사용자 Path에 폴더를 더하는 명령을 돌리고 터미널을 다시 연다. → Antigravity CLI 설정 바꾸기·확인·문제 해결- 키링이 잠기면 CLI가 토큰을 읽지 못한다. CLI는 세션 토큰을 암호화해 두는 데 운영체제 보안 저장소(Apple Keychain, D-Bus를 통한 Linux secret-service, Windows Credential Manager)를 쓴다. 백그라운드 서비스가 잠겨 있거나 화면 없는(headless) 환경이면 자격 증명을 읽지 못해, 시작할 때 멈추거나 D-Bus 경고를 내거나
Error: failed to retrieve token: secret keyring is locked를 낸다. macOS는 Keychain Access 앱에서Antigravity CLI항목의 접근 제어 목록에agy가 있는지 확인하고, SSH 세션에서는 자동 잠금 시간을 정한 뒤 키체인을 직접 열고 끝나면 다시 잠글 수 있다. Linux는 GNOME Keyring·KWallet 같은 키링이 열려 있는지 확인하고, 화면 없는 환경이나 SSH에서는 D-Bus 세션과 키링 데몬이 돌고 있는지 확인한다(export $(dbus-launch)). → Antigravity CLI, Antigravity CLI 설정 바꾸기·확인·문제 해결 - SSH에서는 이미지 붙여넣기가 기본으로 안 된다. 표준 SSH는 그래픽 클립보드를 넘기지 않아
Ctrl+V로 스크린숏을 붙이면Error: local pasteboard is empty or unreachable over SSH connection이 난다. iTerm2나 Ghostty를 쓰고, iTerm2는 Applications in terminal may access clipboard(OSC 52)를 켜고,tmux안이면set -s set-clipboard on을 둔다. → Antigravity CLI 설정 바꾸기·확인·문제 해결 - CLI는 백그라운드에서 스스로 업데이트하고, 잠금 파일이 남으면 막힌다. 내장 자동 업데이트는
~/.gemini/antigravity-cli/updater/안의 15분 확인 간격 표시(last_check.timestamp)와 잠금 파일(update.lock)로 동시 실행을 막는다. 업데이트 프로세스가 멈추거나 잠금을 풀지 못하고 죽거나, 설치 폴더에 쓰기 권한이 없으면 다음 업데이트가 막혀Warning: another background updater process is already active (update.lock)가 나온다. 해결은 잠금 파일 지우기(rm -f ~/.gemini/antigravity-cli/updater/update.lock), 자동 업데이트 끄기(export AGY_CLI_DISABLE_AUTO_UPDATE=true를 셸 설정에), 설치 폴더 쓰기 권한 확인 중 하나다. → Antigravity CLI, Antigravity CLI 설정 바꾸기·확인·문제 해결
원본 안의 불일치 (원본 그대로 둠)#
같은 문서 안에서 경로·문구가 서로 다르다. 어느 쪽이 맞는지 원본은 말하지 않는다.
- Windows 설치 폴더: "Cause"는
C:\Users\<username>\AppData\Local\agy\bin, 업데이트 절은%LOCALAPPDATA%\agy\bin(같은 곳을 가리키는 표기로 보인다)인데, PATH를 더하는 PowerShell 명령은C:\Program Files\Google\antigravity-cli를 더한다. - 키링 증상 이름: 빠른 참조 표는
keyring: secure lock out, 본문 오류 예시는Error: failed to retrieve token: secret keyring is locked다.
원본에 없는 것#
- 해결 뒤 됐는지 확인하는 단계. 원본은 해결 명령만 적는다.
- 자동 업데이트를 끈 뒤 직접 업데이트하는 방법. 이 문서의 Next steps는 Installation 문서를 링크하지 않는다. CLI commands 문서(Antigravity CLI 명령 레퍼런스)의 Next steps가 Installation and auth 문서를 "Update your CLI installation"으로 링크하는데, 이 위키에는 이 사이트에서 아직 다루지 않는다.
- macOS 키체인을 SSH에서 열어 둘 때의 보안 영향. 원본은 "끝나면 선택적으로 다시 잠근다"는 명령만 준다.
- 인증 자체가 실패할 때(로그인 화면, 계정 종류) 대처. 이 문서는 키링 접근 문제만 다룬다.