명령어 이름의 혼동에서 공식 바이너리 설치까지

초록

이 글은 2026년 8월 27일 Linux EC2 환경에서 Google Antigravity CLI(이하 agy)를 설치한 과정을 분석한 사례 연구다. 표면적으로는 단일 명령어를 설치하는 작업이지만, 실제 난점은 패키지 검색·브랜드명·실행 파일명·공식 배포 경로가 서로 다른 층위에 존재한다는 데 있었다.

1. 문제 정의

요청은 “Antigravity CLI를 설치해 달라”는 것이었지만, 원하는 실행 명령은 agy였다. 이 둘은 동일한 문자열이 아니며, npm의 패키지 이름 antigravity, antigravity-cli, antigravity-agent도 서로 다른 프로젝트를 가리킬 수 있다. 따라서 “이름이 비슷한 패키지를 설치한다”는 전략은 기능적 요구사항을 만족한다는 보장이 없다.

2. 관찰된 설치 과정

2.1 첫 번째 오해: 브랜드명과 명령명의 동일시

초기 npm 조회에서 antigravity-cli는 kirox라는 실행 파일을 제공하는 placeholder 패키지였다. antigravity 역시 오래된 placeholder였다. 검색 결과 중 antigravity-agent는 antigravity, gravity, 9agent, ag9 명령을 제공했기 때문에 실용적인 후보처럼 보였고 설치되었다. 그러나 이는 9router 기반의 별도 에이전트이며 Google 공식 agy CLI가 아니었다.

이 단계의 핵심 실패는 패키지 설명과 실행 파일이 존재하는 것만 확인하고, 사용자가 요구한 명령명과 공급자·배포 출처를 함께 대조하지 않은 점이다.

2.2 두 번째 장애: 전역 npm 권한

서드파티 패키지를 전역 설치하려 할 때 npm은 /usr/lib/node_modules에 디렉터리를 만들려 했고 다음 오류로 중단되었다.

EACCES: permission denied, mkdir '/usr/lib/node_modules/antigravity-agent'

이는 패키지 결함이 아니라 일반 사용자 계정이 시스템 전역 디렉터리를 수정할 수 없기 때문에 발생한 운영체제 권한 문제다. sudo를 무조건 사용하는 대신 npm install --global --prefix ~/.local ... 방식으로 사용자 전용 설치 경로를 선택했다. 해당 환경의 PATH에는 이미 ~/.local/bin이 포함되어 있어 별도 시스템 변경 없이 명령을 사용할 수 있었다.

2.3 요구사항 재정의: agy

사용자가 실제로 원한 명령이 agy임을 확인한 뒤 npm 검색 결과를 다시 검토했다. Termux용 래퍼 패키지는 Linux x64 서버에 적합하지 않았고, 서드파티 패키지를 공식 구현으로 간주해서도 안 됐다. 공식 릴리스 저장소 google-antigravity/antigravity-cli의 최신 릴리스에서 Linux x64 아카이브와 다운로드 URL을 확인했다.

아카이브에는 antigravity라는 ELF 실행 파일이 들어 있었으며, 실행 시 버전은 1.1.22였다. 파일 형식이 현재 호스트의 x86-64 Linux와 일치하는 것을 확인한 후, 사용자 전용 bin 디렉터리에 설치하고 이름을 agy로 지정했다. 최종 검증 결과는 다음과 같다.

agy --version → 1.1.22

3. 어려움의 원인 분석

첫째, 명명 체계의 다층성이다. 제품명, 저장소명, npm 패키지명, 압축 파일명, 바이너리명, 사용자가 입력하는 명령명이 모두 다를 수 있다.

둘째, 공식성과 기능성의 혼동이다. npm에서 설치 가능하고 help 화면이 나온다는 사실은 공식 배포물이라는 증거가 아니다. 특히 AI 도구 생태계에서는 유사한 이름의 래퍼·플러그인·브리지·인증 도구가 다수 존재한다.

셋째, 플랫폼과 아키텍처 판단의 필요성이다. Termux/Android ARM64용 패키지는 Linux x64 EC2에서 그대로 사용할 수 없다. 호스트 OS와 CPU 아키텍처를 릴리스 자산과 맞춰야 한다.

넷째, 권한 모델의 불일치다. npm의 기본 전역 prefix는 시스템 디렉터리를 가리킬 수 있지만, 일반 사용자 운영 환경에서는 사용자 prefix가 더 안전하고 재현 가능하다.

다섯째, 검증 시점의 문제다. 설치 성공 메시지만으로는 충분하지 않다. 명령이 PATH에서 발견되는지, 올바른 공급자의 바이너리인지, 버전 출력이 기대값과 일치하는지를 순서대로 확인해야 한다.

4. 개선된 설치 프로토콜

1. 사용자가 실행하려는 정확한 명령명을 먼저 확정한다: 이 사례에서는 agy.
2. 패키지 레지스트리와 공식 문서·공식 릴리스 저장소를 분리해 조사한다.
3. 후보의 bin 선언, 게시자, 저장소, 플랫폼 지원을 확인한다.
4. 호스트의 OS와 아키텍처에 맞는 공식 자산을 선택한다.
5. 일반 사용자는 사용자 전용 설치 경로를 우선 사용한다.
6. command -v agy와 agy --version으로 PATH와 바이너리를 검증한다.
7. 인증·네트워크·서비스 연결은 바이너리 설치와 별도 단계로 다룬다.

5. 결론

이번 설치가 어려웠던 이유는 다운로드 자체가 아니라 식별과 검증의 연쇄가 필요했기 때문이다. 첫 시도는 이름이 비슷한 서드파티 CLI를 설치했고, 권한 오류는 설치 방식의 문제를 드러냈으며, 최종 해결은 공식 릴리스와 호스트 아키텍처를 대조한 뒤 사용자 전용 경로에 agy로 설치하는 방식으로 이루어졌다. “설치한다”는 작업은 패키지를 내려받는 행위가 아니라, 올바른 실행 파일을 올바른 출처에서 올바른 권한과 플랫폼으로 배치하고 검증하는 전체 과정으로 정의되어야 한다.

키워드

Antigravity CLI, agy, 설치 재현성, npm 권한, Linux EC2, 공급망 검증, CLI 식별