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

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

프로그램을 설치할 수 있는 것과 그 계정으로 AI 요청을 처리할 수 있는 것은 다릅니다. gemini --version이 정상이어도 로그인 계정의 이용 자격이나 한도 때문에 요청이 실패할 수 있습니다.

개인 사용자는 설치보다 이용 조건을 먼저 확인합니다. Google은 2026년 6월 18일부터 개인 무료 계정과 Google AI Pro 및 Ultra의 Gemini CLI 요청 처리를 종료한다고 공지했습니다. 일반 인증 문서에는 개인 로그인 설명이 남아 있지만, 이것만으로 서비스 이용이 가능하다고 판단하지 않습니다. 종료 공지와 계정 유형, 실제 오류를 함께 확인합니다.

🔑 제미나이 CLI의 정의

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

CLI는 터미널에서 글자로 명령을 입력해 프로그램을 쓰는 방식입니다. 설치된 버전은 gemini --version, 사용할 수 있는 옵션은 gemini --help로 확인합니다. 두 명령은 AI에게 과제를 요청하지 않고 프로그램 정보를 보여 줍니다.

파일 읽기와 수정 및 명령 실행을 요청한다는 점은 클로드 코드나 코덱스 CLI와 비슷합니다. 터미널에 gemini를 입력하면 대화창이 열리고, 요청을 받으면 폴더의 파일을 읽고 고치고 명령을 실행하며, 연결된 검색 도구를 이용해 자료를 찾기도 합니다. 검색했다는 사실만으로 결과가 정확한 것은 아니므로 출처와 날짜를 확인합니다. 프로젝트 지침은 GEMINI.md 파일에 적습니다. 코딩 에이전트라는 말 자체가 낯설다면 코딩 에이전트 뜻을 먼저 보면 이어지는 설명이 쉬워집니다.

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

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

종료 공지가 명시한 대상은 개인용 Gemini Code Assist와 Google AI Pro 및 Ultra입니다. 조직용 Standard 및 Enterprise와 유료 API 경로는 계속 제공한다고 구분합니다.

✅ 계정별로 구분할 이용 조건

2026년 10월 3일 확인한 종료 공지는 조직용 Standard 및 Enterprise와 유료 API 경로의 계속 이용을 안내합니다. 아래 숫자는 쿼터 문서의 표기이며 실제 계정의 적용 한도도 확인합니다.

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

무료 API 키의 현재 이용을 보장하지는 않습니다. 쿼터 문서에는 무료 API 항목이 있지만 전환 공지는 계속 제공하는 경로로 유료 API를 명시합니다. 무료 API 이용 가능 여부와 적용 모델 및 한도는 실제 API 계정에서 확인하고, 유료 결제가 필요한 상황을 무료 이용으로 안내하지 않습니다. 개인 구글 로그인과 API 키 인증도 서로 다른 경로입니다.

🛠️ 설치와 로그인 개요

이미 설치했다면 gemini --version부터 확인합니다. 새로 설치할 때는 공식 설치 안내와 회사의 기기 사용 기준에 맞는 방법 하나를 고릅니다.

• 실행 환경: 공식 안내는 Node.js 20 이상을 제시하고 운영체제 권장 사양도 별도로 안내합니다. Node.js는 이 CLI를 실행하는 프로그램 환경입니다.
• 설치 방법: Node.js가 준비됐다면 npm install -g @google/gemini-cli를 사용합니다. npm은 Node.js 프로그램 패키지를 설치하는 도구입니다. 다른 설치 방식은 공식 안내를 따릅니다.
• 설치 확인: 터미널을 새로 열고 gemini --version을 입력합니다. 명령을 찾지 못하면 설치 오류와 프로그램 경로를 확인합니다.
• 계정 확인: 조직 라이선스나 API 등 실제 이용 가능한 인증 경로와 결제 조건을 확인합니다. 프로그램을 다시 설치해도 계정의 서비스 종료 조건이 바뀌지는 않습니다.

API 키는 서비스 사용 권한을 가진 비밀값입니다. 코드나 대화에 붙여 넣지 말고 공식 인증 안내의 저장 방법을 따릅니다. 환경 변수를 사용해도 값을 출력하거나 공유하면 노출될 수 있습니다. 조직용 설정은 관리자가 제공한 프로젝트와 계정 안내를 사용합니다.

🔒 승인 모드와 샌드박스

승인 모드는 어떤 도구 행동을 자동으로 허용할지 정합니다. default는 승인 절차를 사용하는 기본 모드, auto_edit는 편집 도구를 자동 승인하는 모드, plan은 계획을 위한 읽기 중심 모드, yolo는 도구 자동 승인 모드입니다. 정책과 도구에 따라 동작이 달라지므로 default를 모든 행동마다 반드시 묻는 모드로 생각하지 않습니다.

샌드박스는 명령이 접근할 수 있는 파일이나 네트워크를 제한하는 별도 장치입니다. --sandbox 옵션이 있어도 사용하는 운영체제와 실행 방식에 따라 제한 범위가 다릅니다. 승인 모드를 바꾸면 파일과 네트워크가 모두 격리된다고 생각하지 않습니다. 자세한 차이는 코딩 에이전트 권한과 안전에서 확인합니다.

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

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

• 그대로 읽는 것: 프로젝트의 GEMINI.md와 AGENTS.md
• 스킬 경로: 반복 작업의 지침을 모은 스킬은 프로젝트 폴더와 사용자 공통 폴더의 위치가 다릅니다. 프로젝트용 .gemini/skills/는 .agents/skills/로 옮기는 안내를 확인합니다
• 변환 명령이 있는 것: 확장 기능은 agy plugin import gemini로 플러그인으로 바꿉니다
• 외부 도구 연결: MCP는 AI와 외부 도구를 연결하는 방식입니다. 연결 설정은 mcp_config.json의 새 위치와 형식을 확인합니다. 원격 서버의 주소 항목 변환 등은 공식 이전 안내를 따릅니다

첫 실행에서 일부 설정을 선택해 자동 변환하는 절차도 있습니다. 원본 설정을 보존하고 자동으로 옮겨진 항목부터 확인한 뒤 빠진 항목만 처리합니다. 목록에 보이는 것과 실제 작동하는 것은 다르므로 작은 요청으로 확인합니다. 연결 비밀값은 보고서나 대화에 복사하지 않습니다.

설정 종류별로 확인하는 예시입니다. 모든 항목이 자동 이전되거나 목록에 보이면 작동한다는 뜻은 아닙니다.

⚠️ 자주 하는 실수

• 로그인 설명을 이용 보장으로 읽습니다: 일반 인증 안내에 개인 로그인 항목이 있어도 별도 서비스 종료 공지와 계정의 실제 조건을 확인합니다.
• Pro를 새로 결제하면 해결된다고 생각합니다: 개인 AI Pro와 Ultra도 종료 공지의 대상입니다.
• 환경 변수면 키가 절대 노출되지 않는다고 생각합니다: 출력과 공유를 피하고 접근 가능한 프로그램 범위를 확인합니다.
• 이전 명령을 실행하면 끝났다고 생각합니다: 지침, 스킬과 외부 도구 연결이 실제 작동하는지 각각 확인합니다.

❓ 자주 묻는 질문

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

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

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

구글의 전환 공지는 안티그래비티 CLI를 안내합니다. 이전하기 전에 해당 계정의 제공 모델과 이용 한도, 설정을 옮길 범위를 확인합니다. Gemini CLI의 과거 한도가 그대로 이전된다고 생각하지 않습니다.

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

쿼터 문서의 무료 API 항목과 전환 공지의 유료 API 안내가 다르므로 무료 이용을 보장하지 않습니다. 실제 API 계정의 제공 모델, 한도와 결제 상태를 먼저 확인합니다. 개인 구글 계정의 종료와 API 키의 조건을 같은 것으로 보지 않습니다.

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

버리지 않아도 됩니다. 안티그래비티 CLI도 GEMINI.md와 AGENTS.md를 읽습니다. 공용 지침으로 옮길 때도 도구마다 읽는 파일 이름과 위치, 우선순위를 확인합니다.

설치 없이 이용 조건부터 판단하기

다음은 가상 상황입니다. “개인 Google AI Pro 계정이고, gemini --version은 나오지만 요청 처리는 실패한다”고 적혀 있습니다.

1. 확인된 것은 프로그램이 실행된다는 사실입니다.
2. 아직 확인하지 않은 것은 계정의 이용 자격과 실패 오류입니다.
3. 개인 Pro는 종료 공지의 대상이므로 재설치를 반복하거나 자동 승인 모드를 켜는 것으로 해결하지 않습니다.

조건을 “회사에서 Gemini Code Assist Standard 라이선스를 배정받았다”로 바꾸면 판단도 달라집니다. 이 경로는 종료 공지의 개인 계정 대상과 구분되므로 실제 라이선스 배정, 로그인 계정과 프로젝트 설정 및 오류를 확인합니다. 회사 이메일 주소만 있다고 라이선스가 생기는 것은 아닙니다.

이용 가능한 환경이나 이전할 도구가 준비됐다면 새 연습 폴더를 작업 폴더로 선택합니다. 그 안에 연습용 GEMINI.md를 만들고 “답변은 한국어로, 원본 파일은 수정하지 않기”를 적습니다. “읽은 지침의 경로와 두 규칙을 설명해 줘. 파일은 수정하지 마”라고 요청합니다. 두 규칙이 답에 나오고 로드된 지침 목록이나 파일 읽기 기록에 해당 경로가 있는지 확인합니다. 누락되면 작업 폴더와 파일 위치를 대조합니다.

다시 할 때는 연습 지침에 “날짜를 추정하지 않기”를 한 줄 추가하고 새 세션에서 확인합니다. 세 규칙을 확인하고 원본 설정을 보존했다면 지침 파일을 인식하는지 확인한 것입니다. 스킬이나 외부 연결은 이 결과만으로 검증됐다고 보지 않습니다.

📋 3줄 요약

1. 제미나이 CLI는 터미널에서 파일 작업을 요청하는 도구이며 설치 성공과 서비스 이용 자격은 별개입니다.

2. 개인 계정 종료 공지와 조직 라이선스 및 API 조건을 구분해 로그인 오류를 확인합니다.

3. 다른 도구로 옮길 때는 원본 설정을 보존하고 지침과 스킬 및 외부 연결이 실제 작동하는지 확인합니다.

참고 자료

• Google의 서비스 종료 일정
• Gemini CLI 전환 공지
• 설치와 실행 안내
• 인증 방식 안내
• 쿼터와 비용 안내
• Antigravity CLI 이전 안내

공식 안내 확인: 2026년 10월 3일. 종료 공지와 일반 인증 및 쿼터 설명이 일치하지 않는 부분은 이용 보장으로 해석하지 않았습니다.