Gemini CLI, 지금도 쓸 수 있나, 무료 사용자 종료와 API 키로 계속 쓰는 법

예전에 본 “Gemini CLI 무료로 쓰기” 글을 따라 설치하고 구글 계정으로 로그인했는데 요청이 제대로 돌아오지 않는다면, 설치를 다시 하거나 캐시를 지우기 전에 확인할 것이 있습니다. 그 글들이 쓰인 뒤에 Google이 개인 계정의 Gemini CLI 요청 처리를 끝냈기 때문입니다. 반대로 같은 도구를 API 키나 회사 라이선스로 쓰던 사람은 아무 일도 겪지 않았고, 괜히 옮겼다가 설정만 어지럽힐 수 있습니다. 같은 이름의 도구인데 로그인 방식에 따라 운명이 갈렸으니, 이 글은 증상 대신 “어떤 방식으로 로그인했나”를 출발점으로 삼아 갈래마다 해야 할 일을 적었습니다. 수치와 버전은 2026-10-27 UTC 기준으로 다시 확인한 값입니다.

로그인 방식 하나로 다섯 갈래가 갈린다

Google이 2026년 5월 19일 개발자 블로그에 올린 공지의 골자는 단순합니다. Gemini CLI와 Gemini Code Assist IDE 확장이 6월 18일부터 개인 무료 사용자와 Google AI Pro·Ultra 구독자의 요청을 처리하지 않고, 그 자리를 Antigravity CLI가 이어받는다는 것입니다. 유료 Gemini API 키와 Gemini Enterprise Agent Platform API 키로는 Gemini CLI를 계속 쓸 수 있고, Gemini Code Assist Standard·Enterprise 라이선스를 쓰는 조직의 접근도 그대로라고 공지에 적혀 있습니다. 저장소 README 맨 위의 안내도 무료 등급과 Google One 사용자는 Antigravity CLI로 대체되었다고 같은 내용을 말합니다.

아래 그림은 이 공지를 로그인 방식 기준으로 다시 그린 것입니다. 왼쪽 질문에서 출발해 내 방식이 붉은 영역과 초록 영역 중 어디에 있는지만 보면 됩니다.

그림 1. 개인 무료·구독 로그인은 agy로, 유료 키와 회사 라이선스는 gemini 그대로

붉은 영역에는 브라우저로 구글 계정에 로그인하는 두 방식(무료, 개인 AI Pro·Ultra)이 들어가고, 나머지 셋은 초록 영역입니다. 이름이 같은 구독이라도 개인으로 샀는지 회사 라이선스인지에 따라 쪽이 갈린다는 점이 헷갈리는 지점입니다. 공식 문서 곳곳에는 개인 계정으로 구글 로그인을 하라는 옛 설명이 남아 있지만, 문서 맨 위 안내와 공지가 우선합니다.

내가 어느 쪽인지 모르겠다면 터미널에서 아래 세 줄부터 실행하면 됩니다. 값을 화면에 찍지 않는 읽기 전용 명령입니다.

gemini --version
[ -n "$GEMINI_API_KEY" ] && echo "GEMINI_API_KEY: set" || echo "GEMINI_API_KEY: unset"
npm view @google/gemini-cli dist-tags

첫 줄은 설치된 버전, 둘째 줄은 키 환경 변수의 설정 여부만, 셋째 줄은 npm의 채널별 최신 버전(latest, preview, nightly)을 보여 줍니다. 키가 unset인데 브라우저 로그인으로 쓰고 있었다면 붉은 영역일 가능성이 높습니다. 키가 set이어도 그 키가 무료 등급인지 유료인지는 따로 확인해야 하는데, 공지가 접근 유지를 명시한 것은 유료 키입니다.

개인 계정에서 6월 18일에 끝난 것

공지가 나간 5월 19일에 Antigravity CLI는 모두에게 열렸고, 한 달 뒤인 6월 18일에 개인 쪽 Gemini CLI와 Code Assist IDE 확장의 요청 처리가 멈췄습니다. 같은 날 GitHub용 Gemini Code Assist는 조직에 새로 설치할 수 없게 되었고, 기존 요청도 이어지는 몇 주 안에 순차적으로 멈추는 것으로 공지되었습니다. 다만 Google Cloud를 통해 GitHub용 Code Assist를 쓰는 조직은 접근이 그대로입니다.

그림 2. 두 도구의 날짜. 붉은 점이 개인 요청이 멈춘 날

저장소 쪽 숫자는 도구가 문을 닫지 않았음을 보여 줍니다. google-gemini/gemini-cli는 별 108,405개, 포크 14,839개에 Apache-2.0 라이선스를 유지하고, 마지막 푸시는 10월 26일 00:37 UTC입니다. npm 안정판은 10월 20일에 0.65.0이 올라갔고, 같은 날 미리보기판 0.66.0-preview.0도 나왔으며, nightly는 매일 갱신되어 0.67.0 계열입니다. 최근 집계 구간(10월 16~22일)의 일주일 다운로드는 231,316건입니다. 다만 다운로드 수는 설치 횟수일 뿐 요청이 처리되는 계정의 수가 아닙니다. 설치돼 있다는 사실이 지금 쓸 수 있다는 뜻은 아니므로, 앞의 로그인 방식 확인이 먼저입니다.

반대편의 Antigravity CLI는 속도가 빠릅니다. 공식 저장소의 변경 기록에 따르면 10월 18일의 1.4.2부터 10월 24일의 1.4.7까지 일주일에 여섯 번 릴리스가 나왔습니다. 같은 기간에 Gemini CLI 안정판은 한 번이었습니다.

옮기는 쪽의 순서: agy 설치부터 설정 이전까지

붉은 영역이라면 공식 이전 문서가 설정의 상당 부분을 자동으로 가져옵니다. 설치는 macOS·Linux에서 curl -fsSL https://antigravity.google/cli/install.sh | bash, Windows PowerShell에서 irm https://antigravity.google/cli/install.ps1 | iex이고, 실행 명령은 agy입니다. 내려받는 즉시 실행하는 방식이 마음에 걸린다면 스크립트를 먼저 파일로 받아 읽어 본 뒤 실행해도 됩니다. 인증은 운영체제 키링을 먼저 보고, 세션이 없으면 구글 로그인으로 넘어갑니다. 로컬에서는 브라우저가 열리고 SSH 세션에서는 인증 주소가 출력됩니다.

옮기는 작업은 다음 순서로 진행합니다.

1. agy를 처음 실행한다. 기존 Gemini CLI 설정을 찾아 무엇을 변환할지 체크리스트로 묻고, 로그인 토큰은 운영체제 키링으로 옮겨진다.
2. GEMINI.md와 AGENTS.md는 손대지 않는다. 작업 폴더의 두 파일과 전역 ~/.gemini/GEMINI.md를 그대로 읽는다.
3. 확장은 agy plugin import gemini로 가져온다. 스킬·에이전트·명령·MCP 서버가 새 플러그인 구조로 바뀌고, 사용자 정의 명령은 스킬로 변환된다.
4. 스킬 폴더는 직접 옮긴다. 전역은 ~/.gemini/skills/에서 ~/.gemini/antigravity-cli/skills/로, 작업 폴더는 .gemini/skills/에서 .agents/skills/로 옮겨야 슬래시 명령으로 인식된다.
5. MCP 설정은 settings.json 안에서 꺼내 별도 mcp_config.json에 둔다(전역은 ~/.gemini/config/, 작업 폴더는 .agents/). 원격 서버의 url·httpUrl 키는 serverUrl로 바꾼다.

가져오기를 실행하면 확장 하나마다 변환 결과가 한 줄씩 나옵니다. 공식 문서가 보여 주는 출력의 일부는 이렇습니다.

[ok]   google-workspace
       ✔ skills     : 5 skills processed
       ✔ commands   : 2 legacy commands converted to skills
       ✔ mcpServers : 1 server definition migrated to mcp_config.json

옮기고 나면 손에 익은 명령이 달라집니다. 이전 문서와 CLI 레퍼런스에서 자주 쓰는 것만 추리면 다음과 같습니다.

하고 싶은 일	Gemini CLI	Antigravity CLI
한 번만 묻고 끝내기	gemini -p "..."	agy -p "..."
이전 대화 이어가기	gemini --resume	agy -c, 대화 중 /resume
계획만 세우게 하기	플랜 모드(실험적)	/plan, --mode plan
이전 시점으로 되돌리기	리와인드, 체크포인트 /restore	/rewind(별칭 /undo)
사용량 확인	/stats model	/usage, /credits
자주 쓰는 지시 재사용	TOML 사용자 정의 명령	스킬(/skills), 기존 명령은 스킬로 변환

일부 사용자 정의 터미널 테마와 실험적 화면 효과는 지원되지 않을 수 있고, 두 도구의 기능이 1:1로 같지 않다는 점은 Google이 처음부터 밝혔습니다. 스크립트에서 쓰던 옵션 이름도 달라질 수 있으니 별도 브랜치에서 먼저 돌려 보는 편이 안전합니다. 모든 도구 승인을 건너뛰는 --dangerously-skip-permissions 플래그는 이름 그대로 격리된 환경이 아니면 쓰지 않는 쪽이 맞습니다.

남는 쪽의 설정: 유료 키와 릴리스 채널

초록 영역이고 키를 쓴다면 README의 방식 그대로입니다. 키는 Google AI Studio에서 발급받아 환경 변수로 넘깁니다.

npm install -g @google/gemini-cli
export GEMINI_API_KEY="YOUR_API_KEY"
gemini

설치는 npm 외에 Homebrew(brew install gemini-cli), MacPorts, 설치 없이 실행하는 npx @google/gemini-cli, 제한된 환경을 위한 Anaconda 경유도 README에 있습니다. 인증 방식은 구글 계정 로그인, Gemini API 키, Vertex AI 셋입니다. 그중 개인 로그인은 이제 붉은 영역에 걸리므로, 남는 쪽의 실질적인 선택지는 API 키(프로젝트 설정 없이 사용량만큼 과금)와 Vertex AI(gcloud 인증, 서비스 계정 JSON 키, Google Cloud API 키 중 하나에 프로젝트 ID와 리전을 함께 지정)입니다.

키를 환경에 남기는 방법은 두 가지이고, 각각 함정이 있습니다. 셸 설정 파일(~/.zshrc 등)에 넣으면 그 셸에서 뜨는 모든 프로세스가 값을 읽을 수 있습니다. .gemini/.env 파일을 쓰면 현재 폴더에서 위로 올라가며 처음 만나는 파일 한 개만 읽고 여러 파일을 합치지 않으므로, 프로젝트 폴더에 만든 .env가 홈의 ~/.gemini/.env를 가려 키가 안 읽히는 일이 생길 수 있습니다.

릴리스 채널은 세 가지입니다. 매주 화요일 UTC 20:00에 안정판(latest 태그), 같은 날 UTC 23:59에 미리보기판(preview 태그), 매일 UTC 00:00에 nightly가 나옵니다. 안정판은 전주 미리보기판을 검증해 승격한 것이라, 특별한 이유가 없다면 안정판이 무난합니다.

README에는 한 가지가 더 붙어 있습니다. Gemini CLI가 최신 Gemini 모델에 최적화되어 있지 않고, Gemini 4 Argon을 쓰려면 Antigravity를 쓰라는 안내입니다. 키로 계속 쓰는 쪽은 최신 모델의 혜택이 Antigravity 쪽에 먼저 간다는 점까지 안고 가는 선택입니다.

회사 라이선스가 “그대로”인 범위

Code Assist Standard·Enterprise 라이선스로 쓰는 조직은 공지에서 접근이 그대로라고 한 대상입니다. 이 문장이 닿는 범위는 세 가지로 읽으면 됩니다. Gemini CLI와 IDE 확장의 접근이 유지되고, Google Cloud를 통해 쓰는 GitHub용 Code Assist도 유지되며, Gemini CLI 저장소는 기업 고객을 위한 최신 모델 업데이트와 버그·보안 수정을 계속 받는다는 제품 책임자의 발언이 The Register 보도에 인용되었습니다. 급히 옮길 이유가 없다는 뜻이고, 옮길 의향이 있을 때도 같은 조직 계정으로 갈 길이 열려 있습니다.

조직이 Antigravity CLI로 넘어가려는 경우를 위해 변경 기록에 남은 사실이 있습니다. README는 기업 사용자가 온보딩에서 GCP 프로젝트를 연결해야 한다고 안내하고, 1.4.1 기록에는 Google Cloud 프로젝트와 Application Default Credentials(AGY_ADC_AUTH)로 로그인하는 Business 계정은 프롬프트·콘텐츠·모델 응답이 수집되지 않아 /config의 텔레메트리 항목이 꺼짐으로 표시된다고 적혀 있습니다. 같은 방식으로 로그인하면 스킬·규칙·플러그인·훅이 로드되지 않던 문제는 1.4.7에서 고쳐졌습니다. 개인 계정과 달리 회사 계정에서는 데이터 동의 구조가 다르다는 점이 이전 검토의 첫 항목입니다.

한도가 돌아오는 간격이 도구마다 다르다

“하루에 몇 번”보다 “언제 다시 채워지나”가 체감을 좌우합니다. Gemini CLI의 공식 할당량 문서(최종 업데이트 6월 18일)는 인증 방식별 사용자당 하루 요청 수를 표로 두고, Antigravity는 요금제마다 갱신 주기를 시간 단위로 둡니다.

인증 방식	하루 요청(문서 표)	6월 18일 이후
개인 구글 계정(Code Assist Individual)	1,000	중단
Google AI Pro	1,500	중단
Google AI Ultra	2,000	중단
Code Assist Standard	1,500	계속
Code Assist Enterprise	2,000	계속
Workspace AI Ultra	2,000	표에 남아 있음
Gemini API 키, 무료 등급	250	표에 남아 있음
Gemini API 키 유료, Vertex AI	가변	계속

종량제 키와 Vertex AI는 요금 등급·모델·토큰 사용량에 따라 달라져 표에 “가변”으로 적혀 있습니다. 공지가 접근 유지를 직접 명시한 것은 유료 키이고, 무료 등급 키 줄은 문서 표에 있는 값 그대로 적었습니다.

이제 갱신 간격을 막대로 놓습니다. 아래 그림은 Antigravity 요금제 문서와 Gemini CLI 할당량 문서에 적힌 주기를 시간으로 환산한 것입니다.

그림 3. 한도가 다시 채워지는 간격. 5시간·24시간·168시간(주 1회)은 문서의 주기를 시간으로 옮긴 편집부 계산

Ultra와 Pro는 5시간마다 채워지지만, Pro는 주간 한도에 닿으면 갱신을 기다려야 하고 Ultra는 주간 한도가 가장 높다는 점이 다릅니다. 구독이 없는 개인 계정은 주 단위로 한 번 채워지는 한도라서, 하루에 몰아 쓰면 남은 엿새를 기다려야 하는 구조입니다. 에이전트의 작업량에 따라 소모량이 달라지고 한도는 바뀔 수 있다고 문서는 적습니다. The Register는 일부 사용자가 몇 번의 요청만으로 주간 한도에 닿았다고 보고했다고 전했는데, 개인 경험담이므로 모두에게 같은 일이 생긴다는 근거로 읽으면 안 됩니다.

Pro·Ultra는 한도를 다 쓰면 AI 크레딧으로 이어서 쓸 수 있습니다. 설정의 AI Credit Overages 값이 Never이면 크레딧을 자동으로 쓰지 않고 한도가 갱신될 때까지 기다리며, Always이면 기본 한도가 떨어졌을 때 크레딧을 쓰다가 갱신되면 기본 한도로 돌아옵니다. 개발 도중 응답이 멈췄다면 CLI 안에서 /usage(별칭 /quota)로 모델별 사용량을, /credits로 남은 크레딧을 확인하는 것이 첫 점검입니다.

소스 공개와 데이터 동의가 갈라 놓는 선택

한도 다음으로 선택을 가르는 조건은 소스와 데이터입니다. The Register는 Gemini CLI가 Apache-2.0 오픈소스로 남는 반면 Antigravity CLI의 GitHub 저장소에는 변경 기록과 README, 데모 이미지만 있고 소스 코드는 공개되지 않았다고 전했습니다. 저장소 정보에서도 Antigravity CLI는 별 2,637개, 포크 254개에 GitHub가 라이선스를 표시하지 않습니다. 개발자 커뮤니티에서는 강제 이전, 사용 한도, 폐쇄 소스 전환에 불만이 나왔습니다.

항목	Gemini CLI	Antigravity CLI
실행 명령	gemini	agy
구현 언어	TypeScript	Go
소스	GitHub에 전체 공개, Apache-2.0	변경 기록·README·데모 이미지만 공개
GitHub 별	108,405	2,637
최근 릴리스	안정판 0.65.0(10월 20일)	1.4.7(10월 24일), 일주일에 6회
비대화형 실행	-p, JSON·stream-json 출력	-p, JSON·stream-json 출력, 스키마 지정
확장 단위	확장(Extensions)	플러그인(Plugins)
사용 기록	세션 기록을 로컬(~/.gemini/tmp)에 저장	상호작용 데이터 수집에 동의하는 구조, 설정에서 거부 가능

마지막 줄이 보안 면에서 읽어 둘 대목입니다. Antigravity CLI의 README는 상호작용 데이터를 수집하는 데 동의하는 구조이며 설정에서 언제든 거부할 수 있다고 적고, AI 에이전트의 자율 코드 실행·데이터 유출·프롬프트 인젝션(문서나 웹 페이지에 숨긴 지시로 에이전트를 속이는 공격) 위험을 경고하면서 에이전트의 모든 작업을 지켜보고 검증하라고 권합니다. 회사 코드를 개인 계정으로 다룬다면 첫 실행 때 이 동의 항목부터 확인해야 합니다.

변경 기록에는 방어 쪽 개선도 보입니다. 1.4.6부터는 샌드박스 안의 명령이 ~/.docker, ~/.kube, ~/_netrc를 읽거나 바꿀 수 없는 것이 기본값이어서, 이 자격 증명을 쓰는 명령은 명시적으로 허용해 줘야 합니다. 1.4.7은 Auto 모드가 임시 파일 정리나 포매터 실행 같은 일상 명령에는 승인을 덜 묻도록 바뀌었습니다. 속도를 얻는 대신 승인 화면이 줄어드는 쪽이므로, 어떤 명령이 자동으로 지나가는지 처음 며칠은 지켜볼 만합니다.

키로 도는 CI는 종료 코드부터 본다

캐시된 로그인이 없는 CI에서는 환경 변수의 키로 인증해야 하므로, 개인 로그인으로 돌리던 야간 작업이 가장 먼저 깨지는 곳입니다. 비대화형 실행에서는 프롬프트를 -p로 주고 출력 형식을 정합니다. 아래 화면은 문서가 정한 출력 키와 종료 코드를 한 장에 모은 것으로, 실제로 돌린 로그가 아니라 문서의 형식입니다.

그림 4. 헤드리스 실행의 출력 모양과 종료 코드(문서 기준)

--output-format json은 답변(response), 토큰 사용량과 지연 시간(stats), 실패 시 오류 정보(error)가 담긴 JSON 한 덩어리를 돌려줍니다. stream-json은 줄 단위 이벤트를 흘려 긴 작업을 지켜보기에 좋고, 이벤트는 init, message, tool_use, tool_result, error, result 여섯 가지입니다. 스크립트가 성공 여부를 가릴 때는 출력 내용이 아니라 종료 코드를 봅니다. 42는 프롬프트나 인자가 잘못된 경우, 53은 턴 한도를 넘긴 경우여서 같은 실패라도 고칠 곳이 다릅니다.

export GEMINI_API_KEY="YOUR_API_KEY"
out=$(gemini -p "Summarize today's git log" --output-format json)
code=$?
if [ "$code" -eq 0 ]; then printf '%s' "$out" | jq -r '.response'; else echo "failed: $code" >&2; fi

Antigravity CLI로 옮긴 CI라면 -p(또는 --print)에 --output-format으로 text·json·stream-json을 고르고, 출력 구조를 강제하는 --json-schema와 시간 제한 --print-timeout을 쓸 수 있습니다. 1.4.7에서는 헤드리스 -p 실행이 대화 검색 색인과 화면용 출력, 사용자 정의 상태 줄 명령을 만들지 않게 되어 CPU 사용이 크게 줄었으므로, 저사양 러너에서는 이 점이 체감될 수 있습니다.

낯선 저장소를 열기 전에 켜 둘 설정 셋

에이전트는 파일을 고치고 셸 명령을 실행합니다. 낯선 저장소의 설정 파일이나 문서가 에이전트의 행동에 영향을 줄 수 있어서, 처음 여는 폴더가 가장 위험합니다. Gemini CLI에는 방어 장치가 세 가지 있고 모두 기본값이 꺼짐이라 직접 켜야 합니다.

1. 체크포인팅. settings.json에 "general": { "checkpointing": { "enabled": true } }를 넣으면 파일 수정을 승인하기 직전의 상태가 홈 디렉터리의 별도 git 저장소(~/.gemini/history/ 아래 프로젝트별 폴더)에 저장됩니다. 프로젝트의 git은 건드리지 않고, 인자 없이 /restore를 실행하면 저장 목록이 나옵니다.
2. Trusted Folders. "security": { "folderTrust": { "enabled": true } }를 켜면 신뢰하지 않은 폴더에서 프로젝트의 .gemini/settings.json, 프로젝트의 .env, MCP 서버 연결, 확장 설치, 도구 자동 승인이 막힙니다. 신뢰 결정은 ~/.gemini/trustedFolders.json에 남습니다. 안정판 0.65.0의 릴리스 노트에도 신뢰하지 않는 폴더에서 워크스페이스 설정을 읽기 전용으로 강제하는 수정이 들어 있습니다.
3. 샌드박스. gemini -s(또는 GEMINI_SANDBOX 환경 변수)로 도구 실행을 격리합니다. macOS에서는 기본 프로파일이 쓰기만 제한하고 네트워크를 허용하는 permissive-open이므로, 엄격하게 쓰려면 strict-proxied 같은 프로파일을 고릅니다.

CI처럼 대화창을 띄울 수 없는 환경에서 Trusted Folders가 걸리면 --skip-trust 플래그나 GEMINI_CLI_TRUST_WORKSPACE=true로 신뢰 확인을 건너뛸 수 있습니다. 편리하지만 신뢰하지 않는 입력이 들어오는 파이프라인에는 쓰지 않는 편이 맞습니다.

두 도구가 한 저장소를 읽을 때

팀 안에서 누군가는 키로 gemini를, 누군가는 agy를 쓰는 상황이 흔합니다. 이때 지침 파일을 두 벌로 나누면 곧 어긋나므로 AGENTS.md 한 벌로 맞추는 방법이 있습니다. Antigravity CLI는 GEMINI.md와 AGENTS.md를 함께 읽습니다. Gemini CLI는 기본으로는 GEMINI.md를 읽지만, 설정으로 읽을 파일 이름을 바꿀 수 있습니다.

{ "context": { "fileName": ["AGENTS.md", "GEMINI.md"] } }

Gemini CLI의 GEMINI.md는 전역(~/.gemini/GEMINI.md), 작업 폴더, 파일에 접근할 때 불러오는 하위 폴더 순으로 합쳐 매 프롬프트에 전달되고, /memory show로 실제로 전달되는 내용을 확인할 수 있습니다. 두 도구가 같은 파일을 다르게 해석하는지 의심스러울 때는 양쪽에서 같은 질문을 던져 보면 가장 빨리 드러납니다.

대화 기록은 공유되지 않습니다. 다만 CLI에서 시작한 대화를 Antigravity 2.0 데스크톱 앱으로 가져올 수 있고, 앱에서는 @conversation 목록으로 불러옵니다.

바꾼 뒤 일주일 안에 확인할 네 가지

옮긴 쪽과 남은 쪽이 각각 일주일 안에 점검할 항목은 다음과 같습니다.

• agy로 옮긴 경우 /usage와 /credits로 모델별 사용량과 크레딧을 확인하고, 내 요금제의 갱신 간격(5시간 또는 주 1회)에 맞게 큰 작업을 나눠 맡긴다
• agy plugin import gemini 출력에서 변환된 항목과 건너뛴 항목을 읽고, 스킬·MCP 설정 경로를 직접 옮겼는지 확인한다
• 첫 실행 때 동의한 상호작용 데이터 수집 항목을 설정에서 다시 열어 회사 코드를 다루는 계정인지에 맞게 정한다
• 키로 gemini를 계속 쓰는 경우 API 키의 사용 한도와 알림을 걸고, CI 스크립트가 종료 코드로 실패를 가르는지 확인한다