제미나이 CLI (Gemini CLI) 이해하기

🤔 설치 글대로 따라 했는데 로그인 뒤 쓸 수 없을 때

제미나이 CLI를 검색하면 "개인 구글 계정으로 하루 1,000회 무료"라는 설명이 아직 많이 나옵니다. 그 글대로 설치하고 구글 계정으로 로그인하면, 이제는 요청이 처리되지 않거나 안티그래비티 CLI로 옮기라는 안내를 만나게 됩니다. 프로그램이 고장 난 것이 아니라 2026년 6월에 쓸 수 있는 조건이 바뀌었기 때문입니다.

지금부터 제미나이 CLI가 무엇인지, 무엇이 언제 끝났는지, 지금은 어떤 조건으로 쓰는지, 개인 사용자라면 어디로 옮기는지를 정리합니다. 조건과 한도는 2026년 9월 28일 구글 공식 문서 기준입니다.

🔑 제미나이 CLI의 정의

제미나이 CLI는 구글이 만든 오픈소스 코딩 에이전트로, 터미널에서 제미나이 모델에게 파일을 읽고 고치고 명령을 실행하게 합니다.

구글은 2025년 6월 25일 제미나이 CLI를 공개하면서 공식 저장소에 "제미나이의 능력을 터미널로 바로 가져오는 오픈소스 AI 에이전트"라고 소개했습니다. 라이선스는 Apache 2.0이라 누구나 코드를 보고 고쳐 쓸 수 있고, 2026년 9월 28일 npm 기준 최신 안정 버전은 0.61.0입니다. 저장소는 지금도 매주 새 버전을 내고 있습니다.

일하는 방식은 클로드 코드나 코덱스 CLI와 같습니다. 터미널에 gemini를 입력하면 대화창이 열리고, 요청을 받으면 폴더의 파일을 읽고 고치고 명령을 실행하며, 구글 검색으로 최신 정보를 찾아 답에 반영하기도 합니다. 프로젝트 지침은 GEMINI.md 파일에 적습니다. 코딩 에이전트라는 말 자체가 낯설다면 코딩 에이전트 뜻을 먼저 보면 이어지는 설명이 쉬워집니다.

📅 개인 무료 사용이 끝나기까지

제미나이 CLI가 개인 사용자에게 널리 쓰인 이유는 넉넉한 무료 조건이었습니다. 그 조건이 어떻게 바뀌었는지 날짜순으로 정리하면 다음과 같습니다.

중단 대상은 구글 계정으로 로그인해 쓰던 개인 경로 전부입니다. 유료인 구글 AI 프로와 울트라 구독도 포함되었다는 점이 자주 놓치는 부분인데, 공식 문서는 두 구독 사용자에게도 안티그래비티 CLI로 옮기라고 안내합니다. 쿼터 문서 기준으로 구글 AI 플러스도 지원 대상에 들어 있지 않습니다.

✅ 2026년 9월 현재 쓸 수 있는 조건

2026년 9월 28일 공식 문서를 기준으로 경로별 상태를 정리하면 다음과 같습니다.

Gemini Code Assist Standard와 Enterprise는 회사나 조직이 구글 클라우드에서 구매하는 코딩 도구 라이선스입니다. 한도는 에이전트 모드와 제미나이 CLI 요청을 합산하고, 프롬프트 하나가 여러 번의 모델 요청으로 이어질 수 있다고 공식 쿼터 문서가 적고 있습니다.

무료 API 키는 공식 문서끼리 설명이 어긋납니다. 개발자 블로그는 유료 API 키로 계속 쓸 수 있다고 적었고, 제미나이 CLI 쿼터 문서 표에는 무료 API 키 하루 250회(Flash 모델만)가 남아 있으며, 저장소 소개 글에는 하루 1,000회가 적혀 있습니다. 어느 쪽이 지금 맞는지 확인하지 못했으므로, 무료 API 키로 쓸 계획이라면 작은 요청으로 직접 시험해 보는 것이 가장 정확합니다. 세션 안에서 /stats model을 입력하면 지금까지 쓴 양이 보입니다.

🛠️ 설치와 로그인 개요

설치 요구 사항과 명령은 공식 설치 문서 기준입니다.

• 필요한 것: Node.js 20 이상. 운영체제는 macOS 15 이상, 윈도우 11 24H2 이상, 우분투 20.04 이상이 공식 요구 사항입니다
• 설치: npm install -g @google/gemini-cli, 맥은 brew install gemini-cli로도 설치합니다. 설치 없이 한 번 써 보려면 npx @google/gemini-cli를 씁니다
• 실행: 작업할 폴더에서 gemini를 입력합니다

로그인 방법은 구글 로그인, Gemini API 키, 구글 클라우드의 Vertex AI 세 가지가 문서에 남아 있습니다. API 키를 쓸 때는 GEMINI_API_KEY라는 환경 변수에 키를 넣고, 조직 라이선스를 쓸 때는 GOOGLE_CLOUD_PROJECT에 프로젝트 ID를 넣습니다. 앞에서 본 것처럼 개인 계정의 구글 로그인은 이제 요청이 처리되지 않습니다.

화면 순서와 오류 대처는 준이아빠블로그의 제미나이 CLI 개인 무료 종료와 안티그래비티 CLI 이전에 정리되어 있습니다.

🔒 승인 모드와 샌드박스

제미나이 CLI는 --approval-mode로 어디까지 묻지 않고 할지 정합니다. 값은 default(매번 확인), auto_edit(파일 수정은 자동), plan(계획만 세움), yolo(모든 행동 자동 승인) 네 가지입니다. 예전에 쓰던 --yolo 플래그는 지금 공식 문서에서 사용 중단 예정으로 표시되어 있고 --approval-mode=yolo를 권합니다.

샌드박스(에이전트가 쓸 수 있는 파일과 네트워크를 운영체제 수준에서 막는 장치)는 기본으로 꺼져 있다가, YOLO 모드를 켜면 기본으로 함께 켜집니다. 모든 행동을 자동으로 허락하는 만큼 작업 폴더 바깥을 건드리지 못하게 막으려는 설계로 보입니다. 도구마다 다른 권한 설정을 한곳에 비교한 설명은 코딩 에이전트 권한과 안전에 있습니다.

🔀 안티그래비티 CLI로 옮길 때 챙길 것

개인 사용자에게 구글이 안내하는 다음 도구는 안티그래비티 CLI입니다. 명령어는 agy이고, 안티그래비티 데스크톱 앱과 같은 에이전트 구조를 씁니다. 공식 이전 문서 기준으로 옮겨지는 것과 직접 옮겨야 하는 것이 나뉩니다.

• 그대로 읽는 것: 프로젝트의 GEMINI.md와 AGENTS.md
• 직접 옮길 것: 워크스페이스 스킬 폴더(.gemini/skills/에서 .agents/skills/로), 전역 스킬 폴더
• 변환 명령이 있는 것: 확장 기능은 agy plugin import gemini로 플러그인으로 바꿉니다
• 이름을 바꿀 것: MCP 설정은 mcp_config.json으로 옮기고 주소 항목 이름을 serverUrl로 고칩니다

"설치하면 설정이 전부 넘어간다"고 적힌 글도 있지만, 공식 이전 문서는 위처럼 손으로 옮길 항목을 따로 적고 있습니다. 옮긴 뒤 스킬과 MCP 서버가 목록에 보이는지 한 번 확인하는 편이 안전합니다.

⚠️ 자주 하는 실수

• 저장소 소개 글의 무료 한도를 그대로 믿습니다: 2026년 9월 28일에도 저장소 소개 글에는 개인 계정 하루 1,000회 문구가 남아 있지만, 같은 사이트의 문서 상단 안내와 구글 지원 문서는 중단을 밝히고 있습니다
• 구글 AI 프로를 구독하면 된다고 생각합니다: 프로와 울트라 구독도 6월 18일 중단 대상에 들어갔습니다
• API 키를 코드 파일에 직접 적습니다: 키가 파일에 남으면 Git 기록이나 공유 폴더로 퍼집니다. 환경 변수에 둡니다
• 2025년 글의 모델과 한도를 지금 조건으로 옮깁니다: 공개 당시 조건과 지금 조건은 다릅니다

❓ 자주 묻는 질문

제미나이 CLI가 없어진 건가요?

없어지지 않았습니다. 저장소와 새 버전 배포는 계속되고 있고, 조직 라이선스와 유료 API 키 사용자는 그대로 씁니다. 바뀐 것은 개인이 구글 계정으로 쓰던 경로입니다.

구글 AI 프로 구독 중인데 터미널에서 제미나이를 쓰려면 어떻게 하나요?

구글은 안티그래비티 CLI를 안내합니다. 안티그래비티 요금 페이지는 구글 AI 프로와 울트라 구독에 더 넉넉한 사용 한도가 붙는다고 적고 있고, 무료 개인 등급도 주간 한도 안에서 쓸 수 있습니다.

무료 API 키로는 아직 쓸 수 있나요?

공식 문서끼리 설명이 달라 확인하지 못했습니다. 쿼터 문서 표에는 하루 250회가 남아 있지만 개발자 블로그는 유료 API 키로 계속 쓴다고 적었습니다. 작은 요청으로 직접 시험해 보고, 정해진 한도에 기대는 작업에는 쓰지 않는 편이 안전합니다.

제미나이 CLI에서 쓰던 GEMINI.md는 버려야 하나요?

버리지 않아도 됩니다. 안티그래비티 CLI도 GEMINI.md와 AGENTS.md를 읽습니다. 다른 코딩 에이전트와 함께 쓸 계획이라면 여러 도구가 읽는 AGENTS.md로 내용을 모아 두는 방법도 있습니다.

📋 3줄 요약

1. 제미나이 CLI는 구글이 2025년 6월 25일 공개한 오픈소스(Apache 2.0) 코딩 에이전트로, 터미널에서 제미나이 모델에게 파일을 읽고 고치고 명령을 실행하게 합니다.

2. 2026년 6월 18일부터 개인 무료 계정과 구글 AI 프로, 울트라 구독의 요청 처리가 멈췄고 Gemini Code Assist Standard는 하루 1,500회, Enterprise는 하루 2,000회로 계속 씁니다.

3. 개인 사용자가 옮겨 갈 안티그래비티 CLI는 GEMINI.md를 그대로 읽지만 워크스페이스 스킬과 MCP 설정은 공식 이전 문서에 따라 직접 옮겨야 합니다.