Antigravity CLI 설치, 명령어, 설정 및 업데이트 가이드

Antigravity CLI란?

Antigravity CLI는 터미널에서 Antigravity 에이전트를 사용하는 명령줄 인터페이스입니다. 키보드 중심 작업, 저장소 안에서 에이전트 시작, 전체 IDE를 열지 않고 결과 확인에 적합합니다. CLI와 데스크톱 제품은 관련되어 있지만 설치 대상과 버전 표기는 서로 다릅니다.

명령어, 터미널, agy, settings.json, 셸 권한 또는 VS Code 통합 터미널이 질문에 포함되어 있다면 이 가이드를 사용하세요. 편집기 패널과 데스크톱 요구사항은 IDE 가이드, MCP 서버는 MCP 가이드, 이전 Agent Manager 화면은 Agent Manager 가이드에서 다룹니다.

CLI 동작은 정적 문서보다 빠르게 바뀔 수 있습니다. 현재 설치 방법과 명령어는 공식 문서를 기준으로 확인하세요. 아래 예시는 워크플로와 안전 점검을 설명하며 모든 빌드에서 실험적 옵션이 같다고 보장하지 않습니다.

Antigravity CLI 설치 방법

서드파티 미러가 아닌 공식 CLI 설치 페이지에서 시작하세요. 공식 페이지에는 macOS/Linux 셸 경로, Windows PowerShell 경로, 사용 가능한 경우 패키지 관리자 안내가 있습니다. 설치 프로그램은 agy 명령을 사용할 셸의 PATH에도 등록해야 합니다.

설치 후 터미널을 닫고 다시 여세요. PATH 변경은 기존 터미널이나 설치 전에 실행한 VS Code에 보이지 않을 수 있습니다. VS Code에서도 새 통합 터미널을 열어야 합니다.

아래 표는 공식 명령어의 형태를 기록한 것입니다. 스크립트 URL, 패키지 이름 또는 지원 플랫폼이 변경되면 오래된 예제를 복사하지 말고 현재 공식 페이지의 명령어를 사용하세요.

1. 1. 공식 설치 프로그램 열기플랫폼 요구사항을 읽고 공식 CLI 문서의 현재 명령어를 실행합니다.
2. 2. 터미널 다시 열기PATH와 셸 정책을 새로 읽도록 새 셸을 시작합니다. VS Code 통합 터미널도 새로 엽니다.
3. 3. 인증 전에 확인agy --version과 agy --help를 실행합니다. agy를 찾지 못하면 에이전트 문제보다 PATH를 먼저 고칩니다.
4. 4. 작은 테스트작은 버전 관리 폴더에서 먼저 실행하여 설치 문제와 저장소 또는 권한 문제를 구분합니다.

공식 출처 안내: 이 사이트는 CLI의 안정적인 직접 바이너리 URL, 파일 크기 또는 보안 검사 결과를 주장하지 않습니다. 기본 CTA는 공식 Google CLI 문서를 엽니다.

Antigravity CLI 첫 명령어

첫 명령은 파괴적인 작업이 아니라 도움말이 가장 안전합니다. 세션 밖에서는 agy --help, 활성 세션 안에서는 /help를 사용하세요. 슬래시 명령은 세션을 제어하고 CLI 플래그는 시작 옵션을 제어합니다. 대화형 명령을 PowerShell이나 Bash에 붙여 넣는 것과 시작 옵션을 주는 것은 다릅니다.

/status 또는 /usage로 세션을 확인하고, 여러 에이전트가 있으면 /agents, 변경을 수락하기 전에는 /diff를 사용하세요. 새 대화나 모델을 선택할 때는 오래된 플래그 대신 현재 공식 명령어 레퍼런스를 확인합니다.

Antigravity CLI 설정과 settings.json

설정은 CLI를 예측 가능하게 만들지만 의도보다 넓은 권한을 줄 수도 있습니다. 공식 설정 문서는 .gemini 아래 사용자 설정과 프로젝트의 .gemini/settings.json을 설명합니다. 여러 저장소에 공통인 선호는 사용자 파일에, 특정 저장소의 규칙은 검토 가능한 프로젝트 파일에 둡니다.

범위를 익힐 때는 /settings 또는 /config를 우선 사용하세요. 어떤 파일이 로드되는지 확인한 뒤 JSON을 수정하고, 권한·샌드박스·워크스페이스 외부 접근을 바꾸기 전에는 백업을 남깁니다. 올바른 JSON도 위치가 틀리면 로드되지 않습니다.

다음 예시는 보수적인 형태일 뿐 모든 릴리스의 기본값을 보장하지 않습니다. 셸 실행이나 파일 접근을 제어하는 키와 값은 공식 설정 레퍼런스에서 확인하세요.

{"toolPermission":{"shell":"ask","fileWrite":"ask"},"enableTerminalSandbox":true,"allowNonWorkspaceAccess":false}

• 범위부터 — 사용자 파일인지 프로젝트 .gemini/settings.json인지 확인한 뒤 수정합니다.
• 권한은 다음 — 흐름을 이해할 때까지 shell과 fileWrite를 ask 또는 검토 상태로 둡니다.
• 샌드박스는 의도적으로 — 위험을 줄일 수 있지만 도구가 보고 실행하는 범위를 바꿀 수 있습니다.
• 한 필드씩 되돌리기 — 문제가 생기면 전체 설정을 삭제하지 말고 가장 작은 변경을 되돌립니다.

터미널 또는 VS Code에서 Antigravity CLI 시작

CLI는 원하는 환경을 그대로 나타내는 셸에서 실행할 때 가장 잘 작동합니다. 저장소, Node.js 또는 Python, 패키지 관리자, 인증 정보, 프록시와 셸 정책이 여기에 포함됩니다. 데스크톱 바로 가기와 통합 터미널은 다른 PATH를 상속할 수 있으므로 agy를 실행하는 정확한 터미널에서 도구 버전을 확인하세요.

VS Code에서는 저장소 루트에서 통합 터미널을 열고 일반 터미널과 같은 버전 확인을 실행합니다. CLI는 VS Code 확장 기능이 아니라 VS Code 옆에서 쓰는 터미널 워크플로입니다. 편집기 패널이나 전체 데스크톱 경험이 필요하면 IDE를 사용하세요.

첫 실행은 작은 파일 설명, diff 검토 또는 짧은 함수 이해처럼 읽기 중심으로 시작합니다. 넓은 워크스페이스 권한이나 확인하지 않은 설치 스크립트부터 실행하지 마세요.

CLI 버전 확인, 업데이트와 롤백 주의사항

공식 Antigravity 다운로드 페이지는 CLI v1.1.9를 데스크톱 Antigravity 2.0 및 Antigravity IDE와 별도로 표시합니다. 데스크톱 버전만으로 CLI가 최신이라고 판단하지 말고 agy --version, 확인 날짜와 공식 출처를 기록하세요.

업데이트하려면 공식 CLI 설치 또는 다운로드 문서로 돌아가 플랫폼에 맞는 현재 절차를 사용합니다. 새 터미널에서 agy --version을 다시 실행하고, 바뀌지 않으면 PATH에 있는 두 번째 바이너리, 오래된 셸 또는 조직 관리 설치를 확인합니다.

이 사이트의 오래된 데스크톱 버전 페이지는 기록용 아카이브입니다. v2.2.1을 현재 버전이라고 말하지 않습니다. 최신 데스크톱 파일은 공식 Google 페이지, CLI는 공식 CLI 문서에서 확인하세요.

보안 및 권한 확인

CLI 에이전트는 저장소를 읽고 로컬 도구를 호출하며 변경을 제안하거나 실행할 수 있습니다. 검토 가능한 권한을 유지하고 버전 관리된 작은 테스트 폴더에서 시작하며 실행 전 셸 명령의 의미를 이해하세요. 포럼에서 복사한 명령이라고 안전한 것은 아닙니다.

워크스페이스 외부 접근, 광범위한 셸 실행 또는 자동 승인을 사용한다면 이유와 해제 시점을 기록하세요. 승인 정책은 이 사이트의 Auto Accept 보안 가이드도 참고할 수 있습니다.

• 첫 실행을 이해할 때까지 shell과 fileWrite를 ask/review로 유지합니다.
• 토큰, 개인 키, 브라우저 쿠키, 운영 자격 증명을 프롬프트에 붙여 넣지 않습니다.
• /diff 또는 생성된 결과를 검토한 뒤 변경을 수락합니다.
• 깨끗한 테스트 폴더로 계정·서비스 오류와 프로젝트 설정을 구분합니다.
• 스크립트가 관리자 권한을 요구하면 멈추고 출처와 정확한 영향을 확인합니다.

Antigravity CLI 문제 해결

실패한 계층에 맞춰 수정하세요. 실제 원인이 PATH, 설정 범위, 계정 상태 또는 셸 정책이라면 재설치가 첫 답은 아닙니다.

agy를 찾을 수 없음

새 터미널을 열고 셸이 해석하는 실행 파일을 확인합니다. Windows에서는 PowerShell과 VS Code PATH를 비교하고 macOS/Linux에서는 설치 프로그램이 수정한 셸 프로필을 확인합니다. 확인되지 않은 미러 경로를 추가하지 마세요.

CLI는 시작하지만 도구를 사용할 수 없음

작은 워크스페이스에서 읽기 작업을 실행하고 권한 및 같은 환경의 도구 설치를 확인합니다. MCP 서버 문제라면 MCP 가이드로 이동합니다.

settings.json이 반영되지 않음

활성 범위와 JSON 문법을 확인합니다. 예상한 .gemini 밖의 파일은 로드되지 않을 수 있습니다. 한 필드를 바꾸고 세션을 재시작한 뒤 /config 또는 /settings로 확인합니다.

일반 터미널에서는 되지만 VS Code에서는 안 됨

작업 폴더, PATH, 셸, Node.js, 프록시, 환경 변수를 비교하고 설치 후 VS Code를 완전히 다시 시작합니다.

업데이트 후에도 이전 버전 표시

새 셸에서 agy --version을 실행하고 해석된 실행 파일을 확인합니다. 오래된 터미널, 중복 설치 또는 PATH 순서가 원인일 수 있습니다.