제미나이 CLI 설치와 첫 파일 만들기: 인증 조건과 이전 방법
제미나이 CLI는 2026년 6월 18일부터 개인 구글 계정 요청을 처리하지 않고 API 키와 기업 라이선스로만 씁니다. 설치, API 키 인증, 작업 폴더에서 첫 파일 만들기, 오류 해결과 안티그래비티 CLI 이전을 순서대로 안내합니다.

세 줄로 먼저 읽기
- 구글은 2026년 6월 18일부터 개인 구글 계정과 구글 AI 프로, 울트라의 Gemini CLI 요청 처리를 중단했고, API 키와 Code Assist 기업 라이선스는 그대로 쓸 수 있습니다.
- Node.js 20 이상에서 npm으로 설치하고 작업 폴더에서 gemini를 실행한 뒤 Use Gemini API key를 고르면 인증이 끝납니다.
- 개인 계정 사용자가 옮겨 갈 곳은 명령어가 agy인 안티그래비티 CLI이며 첫 실행에서 가져올 설정을 직접 고릅니다.
제미나이 CLI(Gemini CLI)는 구글이 만든 오픈소스 터미널 AI 코딩 에이전트입니다. 터미널에 gemini라고 치면 대화창이 열리고, 그 안에서 파일을 읽고 고치고 명령을 실행하는 일까지 맡깁니다. CLI는 명령줄 인터페이스의 약자로, 버튼 대신 터미널에 명령을 입력해 쓰는 방식입니다. 라이선스는 Apache 2.0입니다.
터미널에서 AI에게 일을 시키는 도구로는 앤트로픽의 클로드 코드, OpenAI의 코덱스 CLI, 그리고 구글의 제미나이 CLI가 있습니다. 구글 쪽은 2026년 6월부터 안티그래비티 CLI가 그 역할을 이어받았습니다.
구글 공식 저장소의 소개 화면입니다. 하단의 Using: 2 GEMINI.md files | 2 MCP servers는 프로젝트 설정 파일 두 개와 연결된 도구 두 개를 읽고 있다는 표시입니다. 설명은 2026년 10월 4일 공식 문서 기준입니다. npm 설치 명령은 맥과 윈도우가 같지만 API 키 입력과 폴더 이동 방법은 다릅니다.
2026년 6월 18일에 끊긴 것과 남은 것
구글은 2026년 6월 18일 공식 저장소에 제미나이 CLI 팀 명의로 공지를 올렸습니다. 그날부터 제미나이 CLI가 구글 AI 프로와 울트라, 무료 개인 계정의 요청을 처리하지 않는다는 내용입니다. 이 글도 처음에는 개인 구글 계정으로 하루 1,000회를 무료로 쓰는 방법을 다뤘는데, 그 경로가 이날 닫혔습니다.
인증 방식별 제미나이 CLI 사용 가능 여부
| 인증 방식 | ||
|---|---|---|
| 개인 구글 계정 로그인 | 제공 | 제공하지 않음 |
| 구글 AI 프로, 울트라 | 제공 | 제공하지 않음 |
| Gemini API 키 | 제공 | 제공 |
| Code Assist 스탠다드, 엔터프라이즈 | 제공 | 제공 |
| Vertex AI | 제공 | 제공 |
구글의 별도 지원 문서도 같은 날짜에 제미나이 코드 어시스트 개인 등급과 구글 AI 프로, 울트라에서 제미나이 CLI와 구글 계정 로그인이 중단됐고 스탠다드와 엔터프라이즈 구독은 그대로라고 안내합니다. 끊긴 것은 개인 계정과 구독으로 들어오던 요청의 처리이고, 프로그램 자체는 그대로 있습니다. 저장소는 지금도 열려 있고 릴리스도 계속 올라옵니다.
내 상황에 맞는 인증 방식 고르기
설치하기 전에 어떤 계정으로 쓸지부터 정합니다. API는 프로그램에서 모델을 호출하는 연결 방식이고, API 키는 그 요청을 인증하는 비밀값입니다.
상황별로 쓸 경로
| 내 상황 | |||
|---|---|---|---|
| 개인 구글 계정만 있음 | – | – | 제공 |
| 프로그램에서 직접 모델을 부르고 싶음 | 제공 | – | – |
| 회사에서 스탠다드나 엔터프라이즈를 배정받음 | – | 제공 | – |
API 키는 Google AI Studio에서 쓸 프로젝트를 고르고 만듭니다. 키를 만든 프로젝트에 결제가 연결되지 않았으면 무료 등급, 연결됐으면 유료 등급으로 청구되므로, AI Studio에서 그 프로젝트의 요금 등급과 쓸 수 있는 모델, 남은 한도를 먼저 봅니다. Google AI Pro 구독료와 API 사용료는 따로 냅니다.
API 한도는 키 하나가 아니라 프로젝트에 걸립니다. 키를 더 만들어도 같은 프로젝트라면 한도가 늘지 않습니다. 현재 한도는 Gemini API 한도 문서와 AI Studio의 프로젝트 화면에 나옵니다.
설치에서 첫 파일까지 다섯 단계
아래 다섯 단계를 차례로 진행합니다. 단계마다 무엇이 보이면 다음으로 넘어가는지 적어 두었습니다.
제미나이 CLI 설치에서 첫 파일까지
1. Node.js 확인node -v에서
v20 이상
2. CLI 설치gemini --version에서
버전 숫자
3. 작업 폴더 이동pwd 끝이
내 작업 폴더
4. API 키 인증입력창이 열리고
요청을 받음
5. 첫 파일 만들기폴더에서 파일을
직접 열어 봄
1. Node.js와 터미널 준비
Node.js는 제미나이 CLI를 실행하는 프로그램이고, npm은 Node.js용 패키지를 설치하는 도구입니다. 공식 설치 문서는 Node.js 20 이상과 인터넷 연결, 지원 지역을 요구하고 macOS 15 이상, Windows 11 24H2 이상을 권장 환경으로 안내합니다.
맥은 Spotlight에서 터미널을 검색해 열고, 윈도우는 시작 메뉴에서 PowerShell을 검색해 엽니다. 아래 명령을 한 줄씩 입력하고 Enter를 누릅니다.
node -v
npm -v결과에 따라 다음 할 일이 정해집니다.
node -v 결과로 다음 할 일 정하기
| 화면에 나온 결과 | ||
|---|---|---|
| v20.0.0 이상 버전 숫자 | 제공 | – |
| v20보다 낮은 버전 숫자 | – | 제공 |
| command not found | – | 제공 |
command not found는 Node.js가 설치되지 않았거나 터미널이 실행 경로를 찾지 못한다는 뜻입니다.
설치는 Node.js 공식 다운로드에서 운영체제에 맞는 LTS 설치 프로그램을 받습니다. LTS는 오래 지원하는 안정판입니다. 설치 뒤 터미널을 닫았다가 다시 열고 두 명령을 다시 실행합니다. 맥에서 Homebrew를 쓰고 있다면 brew install node, 윈도우에서 winget을 쓰고 있다면 winget install OpenJS.NodeJS.LTS로도 설치할 수 있습니다.
2. 제미나이 CLI 설치
npm 전역 설치로 진행합니다. 전역 설치는 현재 폴더뿐 아니라 어느 폴더에서나 gemini 명령을 쓸 수 있게 설치하는 방식입니다.
npm install -g @google/gemini-cli@latest
gemini --version버전 숫자가 나오면 설치는 끝났고, 인증은 4단계에서 합니다. PowerShell이 npm.ps1 실행을 막으면 첫 줄의 npm 대신 npm.cmd를, gemini.ps1을 막으면 gemini 대신 gemini.cmd를 입력합니다.
설치 방법은 npm 전역 설치 말고도 두 가지가 더 있습니다. 처음에는 하나만 고르고, 여러 방법을 섞어 설치하지 않습니다.
설치 방법 세 가지
| 항목 | |||
|---|---|---|---|
| 어느 폴더에서나 gemini 명령 | 제공 | 제공하지 않음 | 제공 |
| 매번 npx 명령으로 실행 | 제공하지 않음 | 제공 | 제공하지 않음 |
| 윈도우 PowerShell | 제공 | 제공 | 제공하지 않음 |
릴리스 채널은 기본 안정판 latest, 검증 중인 preview, 매일 바뀌는 nightly 세 가지가 있습니다. 이 글은 안정판 기준입니다.
3. 작업할 폴더로 이동
제미나이 CLI는 설치한 폴더가 아니라 실행한 폴더 안에서 파일을 읽고 만듭니다. 처음에는 Finder나 파일 탐색기의 문서 폴더 안에 gemini-work 같은 새 폴더를 만들고, 맡길 업무 파일의 복사본을 넣습니다. 요청이 잘못돼도 원본은 그대로 남습니다.
터미널에 cd 를 끝의 공백까지 입력합니다. 맥에서는 폴더를 터미널 창에 끌어 놓고 Enter를 누르며, 이때 입력된 경로에 따옴표를 덧붙이지 않습니다. 윈도우에서는 탐색기 주소 표시줄의 전체 경로를 복사해 cd 'C:\Users\사용자이름\Documents\gemini-work'처럼 작은따옴표로 감싸 붙입니다. 이어서 pwd로 현재 위치를 봅니다.
cd는 작업 폴더를 옮기고 pwd는 현재 위치를 보여 줍니다. 경로 끝이 다른 폴더라면 cd부터 다시 입력합니다.
4. API 키로 인증하기
이 단계는 API 키를 쓰는 경우입니다. 기업 라이선스나 Vertex AI 사용자는 조직에서 안내한 인증 방식을 따릅니다. Vertex AI는 구글 클라우드 프로젝트에서 AI 모델을 쓰는 서비스입니다.
API 키로 인증하는 순서
1. 키 만들기AI Studio에서
프로젝트 고르고 복사
2. 숨겨서 입력화면에 안 보이게
현재 터미널에만 저장
3. gemini 실행작업 폴더에서
gemini 입력
4. 인증 방식 선택Use Gemini API key
고르기
5. 폴더 신뢰표시된 경로가
작업 폴더인지 보고 승인
아래 명령은 키를 화면에 표시하지 않고 받아 현재 터미널에만 환경 변수로 설정합니다. 환경 변수는 프로그램에 설정값을 넘기는 이름과 값의 쌍입니다. 운영체제에 맞는 블록 하나만 씁니다.
맥 기본 터미널 zsh: 첫 줄을 실행하면 입력한 내용이 보이지 않는 상태로 기다립니다. API 키를 붙여 넣고 Enter를 누른 다음 나머지 줄을 실행합니다.
read -rs 'GEMINI_API_KEY?API 키를 붙여 넣고 Enter: '
print
export GEMINI_API_KEY
gemini윈도우 PowerShell: 첫 줄의 입력창에 키를 붙여 넣고 Enter를 누른 다음 나머지 줄을 실행합니다.
$geminiPracticeSecret = Read-Host 'API 키를 붙여 넣고 Enter' -AsSecureString
$env:GEMINI_API_KEY = [System.Net.NetworkCredential]::new('', $geminiPracticeSecret).Password
Remove-Variable geminiPracticeSecret
gemini인증 선택 화면에서 Use Gemini API key를 고릅니다. 다른 방식으로 이미 실행했다면 대화창에서 /auth를 입력해 인증 방식을 바꿉니다. 키는 대화창에 입력하거나 화면 캡처에 넣지 않습니다.
폴더 신뢰나 파일 접근 확인 창이 뜨면 표시된 경로가 작업 폴더인지 보고 승인합니다. 다른 폴더 접근이나 외부 도구 연결은 이 단계에서 허용하지 않습니다. 이 환경 변수는 현재 터미널 창에만 있어서, 새 터미널을 열면 같은 과정을 다시 진행합니다.
5. 첫 요청으로 파일 만들기
대화창에서 먼저 /model을 입력해 모델 설정을 봅니다. 하위 명령 안내가 나오면 /model manage로 설정 화면을 열고, /model set MODEL_ID로 모델을 지정합니다. MODEL_ID는 내 인증 방식에서 쓸 수 있는 실제 모델 식별자로 바꿔 넣습니다. API 무료 등급이라면 AI Studio에 무료로 표시된 모델을 고릅니다. 프로그램을 시작할 때 gemini -m MODEL_ID로 지정해도 됩니다.
첫 요청은 작업 폴더에 넣어 둔 파일 하나를 읽고 새 파일 하나를 만드는 일이 좋습니다. 예를 들어 회의 메모를 텍스트 파일로 넣어 두었다면 아래처럼 요청합니다.

파일 쓰기 승인을 물으면 경로와 내용을 보고 그 파일을 만드는 작업만 승인합니다. 답변에 "만들었다"고 나와도 Finder나 파일 탐색기에서 작업 폴더의 todo.md를 직접 열어 봅니다. 맥은 텍스트 편집기, 윈도우는 메모장으로 열립니다.
메모에 없던 담당자나 기한, 연락처가 들어 있으면 그 부분을 지우고 "원본 메모에 있는 내용만 쓰세요"라고 다시 요청합니다. 파일이 없으면 승인 창에서 취소하지 않았는지, 실행한 폴더가 작업 폴더였는지를 봅니다.
마치면 /stats로 이번 세션의 요청 수와 토큰을 보고 /quit로 끝냅니다. API 비용과 남은 한도는 AI Studio에서 봅니다. 현재 터미널의 임시 키는 맥에서 unset GEMINI_API_KEY, PowerShell에서 Remove-Item Env:GEMINI_API_KEY로 지웁니다. 이 명령은 터미널의 값만 지우고 AI Studio의 키를 폐기하지는 않습니다.
처음에 익혀 둘 명령 여섯 개
대화창 안에서는 /로 시작하는 명령을 씁니다. 전체 목록은 /help에 있고, 처음에는 아래 여섯 개면 충분합니다.
명령을 쓰는 때
| 명령 | |||
|---|---|---|---|
| /model 모델 설정 | 제공 | – | – |
| /stats 세션 사용량 | 제공 | – | – |
| /init GEMINI.md 만들기 | – | 제공 | – |
| /memory 기억할 내용 관리 | – | 제공 | – |
| /mcp 연결된 도구 확인 | – | 제공 | – |
| /compress 대화 요약 | – | – | 제공 |
/init은 현재 프로젝트를 훑어 GEMINI.md 설정 파일을 만듭니다. 프로젝트 구조와 규칙을 이 파일에 적어 두면 대화마다 다시 설명하지 않아도 됩니다. /mcp는 연결된 MCP 서버를 보여 주고, /compress는 대화를 요약해 이후 요청에 들어가는 분량을 줄입니다.
안티그래비티 CLI로 옮기는 방법
구글이 안내한 이전 대상은 안티그래비티 CLI이고, 명령어는 agy입니다. 설치 명령은 운영체제별로 하나씩입니다.
# macOS, Linux
curl -fsSL https://antigravity.google/cli/install.sh | bash
# Windows PowerShell
irm https://antigravity.google/cli/install.ps1 | iex이 명령은 인터넷에서 설치 스크립트를 받아 바로 실행합니다. 내 운영체제의 명령 하나만 실행하고, 이전은 아래 순서로 진행합니다.
제미나이 CLI 설정을 안티그래비티 CLI로 옮기는 순서
1. 기존 설정 복사설정 폴더와 GEMINI.md를
다른 곳에 복사
2. agy 설치터미널을 다시 열고
agy --version
3. 가져올 항목 선택첫 agy 실행에서
목록을 보고 고름
4. 스킬 폴더 옮기기.gemini/skills/를
.agents/skills/로
5. 같은 요청 실행규칙 파일과 MCP 연결이
그대로인지 봄
현재 이전 문서는 첫 agy 실행에서 가져올 항목을 직접 고르게 합니다. 스킬은 반복 작업 지침, MCP 서버는 외부 도구 연결, 에이전트 설정은 작업 역할과 동작 설정입니다. 고른 항목만 옮겨지므로, 완료 뒤 프로젝트 규칙 파일을 읽는지와 필요한 스킬, MCP 연결이 있는지 봅니다.
.agents/skills/에 이미 파일이 있으면 덮어쓰지 말고 두 폴더의 내용을 비교해 합칩니다. MCP 설정 형식은 공식 이전 문서에 맞춰 바꿉니다. 이전한 도구가 다시 로그인을 요구하면 해당 서비스의 로그인 절차를 진행합니다. 마지막으로 앞에서 했던 요청을 새 파일 이름으로 실행해 결과 파일을 엽니다. 요금제별 한도는 안티그래비티 계정 화면에 따로 나오고, Gemini API 무료 한도와 합쳐 계산하지 않습니다.
다른 코딩 도구와 함께 쓸 때
클로드 코드와 코덱스 CLI도 터미널에서 파일 작업을 맡는 도구이고, 도구마다 프로젝트 지침 파일 이름이 다릅니다.
터미널 코딩 도구별 지침 파일
| 항목 | |||
|---|---|---|---|
| 프로젝트 지침 파일 | GEMINI.md | CLAUDE.md | AGENTS.md |
| 실행 명령 | gemini | claude | codex |
지침 파일은 작업 규칙을 적어 두는 문서입니다. 한 폴더에서 여러 도구를 쓰면 지침 파일도 여러 개가 되므로, 규칙이 서로 어긋나지 않게 같은 내용으로 맞춰 둡니다. 같은 파일을 여러 도구에 동시에 고치게 하지 말고 한 도구의 결과를 본 뒤 다음 작업으로 넘어갑니다.
쓸 수 있는 모델은 CLI 버전이 아니라 인증 방식에 따라 정해지고, /model 목록에 나옵니다. 모델 발표는 Gemini 4 발표 확인 글에서 따로 다룹니다.
자주 발생하는 문제
오류 문구를 먼저 읽고 아래에서 해당하는 경우를 찾습니다. 키와 토큰은 빼고 오류 문구와 버전을 적어 두면 원인을 좁히기 쉽습니다.
오류 문구별로 원인을 찾을 곳
| 오류 문구 | |||
|---|---|---|---|
| command not found: gemini | 제공 | – | – |
| Failed to sign in | – | 제공 | 제공 |
| named user on your organization | – | – | 제공 |
| 401, 403 | – | 제공 | – |
| 429 | – | 제공 | – |
| unable to get local issuer certificate | – | – | 제공 |
gemini 명령을 찾지 못하는 경우
command not found: gemini는 설치가 안 됐거나 터미널이 실행 경로를 못 찾는 경우입니다. npm list -g --depth=0의 결과에 @google/gemini-cli가 있는지 봅니다. 없으면 2단계의 설치 명령을 다시 실행하고, 있으면 터미널을 다시 엽니다. 그래도 같으면 npm prefix -g로 설치 위치를 보고 공식 문제 해결 문서의 PATH 안내를 따릅니다. PATH는 터미널이 명령 실행 파일을 찾는 폴더 목록입니다. npx로만 실행했다면 전역 gemini 명령이 없는 것이 정상입니다.
회사 구글 계정으로 로그인이 안 되는 경우
Failed to sign in. Message: Request contains an invalid argument는 개인 로그인 종료 때문일 수도 있고, 기업 라이선스 배정이나 프로젝트 설정 문제일 수도 있습니다. 회사 계정이라면 관리자에게 라이선스와 프로젝트 배정을 물어보고, 개인 API 키를 쓰려면 /auth에서 Use Gemini API key를 골랐는지 봅니다.
조직 구독이 필요하다는 메시지가 뜨는 경우
You must be a named user on your organization's Gemini Code Assist Standard edition subscription은 조직 라이선스를 확인하는 단계에서 나오는 메시지입니다. GOOGLE_CLOUD_PROJECT나 GOOGLE_CLOUD_PROJECT_ID 설정 때문에 뜨기도 하고, 실제로 라이선스가 없어서 뜨기도 합니다. 회사 설정 파일의 변수를 함부로 지우지 말고 관리자에게 배정 상태를 물어봅니다. 개인 작업은 별도 폴더에서 API 키 인증으로 진행합니다.
API 키나 사용량 오류가 나는 경우
401이나 403 오류는 키가 다른 프로젝트의 것이거나, 고른 모델을 그 프로젝트에서 쓸 수 없을 때 납니다. 키를 터미널에 출력하지 말고 AI Studio의 발급 화면에서 상태를 봅니다. 429 오류는 요청 수나 토큰 한도에 걸렸다는 뜻이므로 AI Studio의 한도와 안내된 재시도 시간을 봅니다. 같은 요청을 반복하거나 키를 새로 발급해도 프로젝트 한도는 늘지 않습니다.
회사 네트워크에서 인증서 오류가 나는 경우
UNABLE_TO_GET_ISSUER_CERT_LOCALLY나 unable to get local issuer certificate는 사내 방화벽이 인증서를 바꿔 끼우는 환경에서 자주 납니다. 관리자에게 승인된 인증서와 Node.js 버전을 물어본 뒤, 시스템 인증서를 지원하는 Node.js 버전이면 아래 설정을 씁니다.
# 맥, 리눅스
export NODE_USE_SYSTEM_CA=1
# 윈도우 파워셸
$env:NODE_USE_SYSTEM_CA=1그래도 같으면 사내 루트 인증서 파일의 절대 경로를 NODE_EXTRA_CA_CERTS에 지정합니다.
지역이 지원되지 않는다는 메시지가 뜨는 경우
not currently available in your location은 접속 지역이 지원 목록에 없을 때 나옵니다. 지원 지역 목록은 구글이 별도 문서로 관리합니다.
자주 묻는 질문
제미나이 CLI는 지금도 무료인가요?
개인 구글 계정 로그인으로 쓰던 무료 사용은 종료됐습니다. Gemini API 키의 무료 등급은 따로 남아 있어서, 결제가 연결되지 않은 프로젝트에서 무료로 표시된 모델을 쓰면 한도 안에서 무료입니다. 설치 자체는 무료지만 모델 호출 비용은 인증 방식에 따라 정해집니다.
설치는 지금도 되나요?
됩니다. 저장소가 열려 있고 릴리스도 계속 올라옵니다. npm install -g @google/gemini-cli로 설치하고 인증을 API 키나 기업 라이선스로 하면 동작합니다.
윈도우에서도 되나요?
됩니다. 설치 명령은 맥과 같고, API 키를 입력하는 명령과 폴더 경로 입력 방식만 다릅니다.
클로드 코드를 쓰고 있는데 같이 깔아도 되나요?
함께 설치할 수 있습니다. 같은 파일을 두 도구가 동시에 고치지 않게 작업을 나누고, 프로젝트 설정 파일은 GEMINI.md와 CLAUDE.md로 따로 관리합니다.
한국어로 써도 되나요?
됩니다. 프롬프트를 한국어로 넣으면 한국어로 답합니다. 코드 주석이나 커밋 메시지의 언어와 형식을 정해 두려면 GEMINI.md에 규칙으로 적어 둡니다.
Sources
- Gemini CLI 공식 저장소
- Gemini CLI 설치 문서
- Gemini CLI 인증 문서
- Gemini CLI 할당량과 요금 문서
- Gemini CLI 명령어 레퍼런스
- Gemini CLI 문제 해결 문서
- Google for Developers, Gemini CLI
- Gemini CLI 팀 공지: 개인 계정 요청 처리 중단 (2026-06-18)
- Google 공식 지원 문서: 개인용 Gemini Code Assist 지원 종료
- Google 개발자 블로그: 제미나이 CLI에서 안티그래비티 CLI로 전환
- Gemini API 현재 한도
- 안티그래비티 CLI 현재 이전 문서
3줄 요약
-
구글은 2026년 6월 18일부터 개인 구글 계정과 구글 AI 프로, 울트라의 Gemini CLI 요청 처리를 중단했고, API 키와 Code Assist 기업 라이선스는 그대로 쓸 수 있습니다.
-
Node.js 20 이상에서 npm으로 설치하고 작업 폴더에서 gemini를 실행한 뒤 Use Gemini API key를 고르면 인증이 끝납니다.
-
개인 계정 사용자가 옮겨 갈 곳은 명령어가 agy인 안티그래비티 CLI이며 첫 실행에서 가져올 설정을 직접 고릅니다.

제대로 이해했는지 한 문제로 확인해 볼까요?
답을 고르면 바로 풀이가 나와요.
제미나이 CLI의 개인 구글 계정 지원 종료 후에도 남아 있는 사용 경로는 무엇인가요?

새 글과 AI 소식을 메일로 받아 보세요
AI가 바꾸는 일과 도구, 측정 실무 이야기를 매주 한 번 보내 드려요.
이 글이 도움이 되었나요?
코딩 에이전트가 무엇이고 도구마다 무엇이 다른지, 비개발자 눈높이로 고르는 기준까지
코스 전체 보기 →