muaco Tech Note

Geminigithub.com

Gemini CLI 기본 사용법설치, API 키 연결, 2026년 무료 범위

Gemini CLI를 설치하고 API 키로 연결해 첫 질문의 답을 받습니다. 2026년 6월 18일 이후 무료로 쓸 수 있는 범위도 함께 짚습니다.

안녕하세요, muaco입니다.

이 글로 할 수 있는 일

이 글을 끝까지 따라 하면 내 컴퓨터 터미널에서 Gemini CLI를 설치하고, API 키로 연결해 첫 질문의 답을 받게 됩니다. 터미널은 마우스 대신 글자로 컴퓨터에 일을 시키는 창입니다. CLI(터미널에 명령을 쳐서 쓰는 방식)라는 이름도 여기서 왔습니다.

시작하기 전에 꼭 아셔야 할 변화가 있습니다. 공식 문서에 따르면 무료 사용자와 Google One 사용자는 2026년 6월 18일부로 Gemini CLI에서 Antigravity CLI로 옮겨졌습니다. "구글 계정으로 로그인만 하면 무료"라는 예전 설명은 이제 개인 무료 사용자에게 맞지 않습니다.

미리 갖춰야 할 준비물

여기서 걸리면 아래 단계를 다 읽어도 소용없습니다. 설치 문서가 밝힌 조건은 이렇습니다.

  • 운영체제: macOS 15 이상, Windows 11 24H2 이상, Ubuntu 20.04 이상
  • Node.js 20.0.0 이상
  • 메모리: 짧은 작업은 4GB 이상, 큰 프로젝트를 오래 다루려면 16GB 이상
  • 셸: Bash, Zsh, PowerShell 중 하나와 인터넷 연결

Node.js는 무대에 비유할 수 있습니다. 배우가 무대 위에서만 공연하듯, Gemini CLI는 Node.js 위에서만 돌아갑니다. 그래서 무대를 먼저 세웁니다.

무료로 쓸 수 있는 범위 (2026년 10월 확인)

누가 계속 쓸 수 있는지는 계정 종류에 따라 갈립니다. 공식 공지와 요금 문서를 함께 보면 아래와 같습니다.

연결 방식6월 18일 이후문서에 적힌 한도
Google 로그인 (무료, Google One)Antigravity CLI로 전환해당 없음
Google 로그인 (AI Pro, Ultra)Gemini CLI 요청 처리 중단해당 없음
회사 Code Assist Standard, Enterprise계속 지원하루 1,500회, 2,000회
유료 Gemini API 키계속 사용 가능쓴 만큼 토큰·호출 단위로 과금
무료 Gemini API 키공지에 언급 없음요금 문서상 하루 250회, Flash 모델만

마지막 줄이 애매합니다. 요금 문서에는 무료 API 키 한도가 남아 있지만, 전환 공지는 유료 키만 계속 쓸 수 있다고 적었습니다. 무료 키로 시도해 보고, 막히면 Google AI Studio에서 결제를 등록하는 순서를 권합니다.

결제를 등록하면 그때부터 쓴 만큼 요금이 붙습니다. 요금 문서는 API 키 방식이 토큰·호출 단위로 과금되고, 금액은 요금 등급과 모델에 따라 달라진다고 설명합니다. 등록 전에 Gemini API 요금표부터 확인하세요.

이 글은 개인이 지금 바로 해 볼 수 있는 API 키 방식으로 진행합니다.

따라 하기: 설치부터 첫 질문까지

설치하기

따라 하기
  1. Node.js 공식 사이트에서 20 이상 버전을 받아 설치하세요.
  2. 터미널을 엽니다. Windows는 시작 메뉴에서 PowerShell을, macOS는 응용 프로그램의 터미널을 찾으면 됩니다.
  3. node -v를 입력해 v20 이상의 버전 번호가 나오는지 보세요. 숫자가 그보다 낮거나 명령을 찾지 못하면 1번으로 돌아갑니다.
  4. 아래 명령을 입력하고 Enter를 누르세요. 끝에 붙은 -g는 어느 폴더에서든 쓸 수 있게 컴퓨터 전체에 설치한다는 뜻입니다.
    npm install -g @google/gemini-cli
  5. macOS나 Linux에서 Homebrew를 쓰신다면 brew install gemini-cli로 대신 설치해도 됩니다.
  6. gemini --version을 입력하세요. 버전 번호가 출력되면 설치가 끝난 상태입니다.

키 연결하기

따라 하기
  1. Google AI Studio의 API 키 페이지(aistudio.google.com/app/apikey)에서 키를 만드세요. API 키는 내 계정으로 들어가는 출입증입니다. 인증 문서도 키를 민감한 자격 증명으로 다루라고 당부합니다.
  2. 남이 함께 쓰는 컴퓨터라면 키를 화면 공유나 메신저에 붙여 넣지 마세요. 키가 새면 내 계정 한도와 요금이 남에게 쓰입니다.
  3. 터미널에 키를 알려 줍니다. macOS·Linux는 export GEMINI_API_KEY="YOUR_GEMINI_API_KEY", PowerShell은 $env:GEMINI_API_KEY="YOUR_GEMINI_API_KEY"를 입력하세요. 따옴표 안에는 방금 만든 키를 넣습니다.
  4. gemini를 입력해 실행하세요. 연결 방식을 묻는 화면에서 "Use Gemini API key"를 고르면 됩니다.
  5. 질문을 입력할 수 있는 칸이 뜨면 연결 완료입니다. 매번 키를 치기 번거롭다면 .env 파일에 GEMINI_API_KEY="YOUR_GEMINI_API_KEY" 한 줄을 적어 두세요. 위치는 macOS·Linux가 ~/.gemini/.env, Windows가 %USERPROFILE%\.gemini\.env입니다.

첫 질문 던지기

따라 하기
  1. 입력칸에 "이 폴더에 있는 파일을 설명해 줘"처럼 평소 말로 물어보세요. 답이 돌아오면 성공입니다.
  2. /help를 입력해 쓸 수 있는 명령 목록을 확인하세요. 빗금(/)으로 시작하는 말은 질문이 아니라 프로그램에 내리는 지시입니다.
  3. /stats로 이번 세션의 사용 통계를 봅니다. 한도가 있는 키를 쓴다면 가끔 열어 보세요.
  4. /quit를 입력해 종료합니다. 원래 터미널 입력 줄로 돌아오면 됩니다.
  5. 대화창 없이 한 번만 묻고 싶다면 gemini -p "질문 내용"을 쓰세요. 답만 출력하고 바로 끝납니다.

막히기 쉬운 네 곳

"command not found"가 뜹니다

gemini를 쳤는데 그런 명령이 없다고 나옵니다. 문서는 설치가 덜 됐거나, npm이 프로그램을 넣는 폴더가 PATH(터미널이 명령을 찾아보는 폴더 목록)에 없을 때라고 설명합니다. 그 폴더가 PATH에 들어 있는지 확인한 뒤 npm install -g @google/gemini-cli@latest로 다시 설치해 보세요.

"named user on your organization" 오류

"You must be a named user on your organization's..."로 시작하는 문구가 보입니다. GOOGLE_CLOUD_PROJECT나 GOOGLE_CLOUD_PROJECT_ID 변수가 설정돼 있으면 조직 구독 확인을 강제하기 때문입니다. 개인이라면 셸 설정과 .env 파일에서 이 두 변수를 지우세요.

회사 망에서 인증서 오류

"UNABLE_TO_GET_ISSUER_CERT_LOCALLY"가 뜨는 경우입니다. 회사 방화벽이 암호화된 통신을 중간에서 검사하면 이렇게 됩니다. 먼저 NODE_USE_SYSTEM_CA=1을 설정해 보고, 그래도 안 되면 NODE_EXTRA_CA_CERTS에 회사 루트 인증서 경로를 넣으세요.

Google 로그인을 골랐는데 쓸 수 없습니다

무료 계정이나 Google One 계정이라면 6월 18일 이후 Gemini CLI 대상이 아닙니다. 이때 화면에 어떤 문구가 뜨는지는 문서에 나와 있지 않습니다. /auth로 연결 방식을 API 키로 바꾸거나 Antigravity CLI로 옮기세요.

여기서 더 나아가려면

작업 폴더에서 /init을 실행하면 폴더를 살펴보고 GEMINI.md라는 안내 파일을 만들어 줍니다. 질문에 @파일이름을 붙이면 그 파일 내용을 함께 읽힙니다. 무료로 계속 쓰고 싶다면 Antigravity CLI 전환 안내서도 읽어 보세요. 실행 명령은 agy이고, 기존 GEMINI.md는 고칠 필요가 없다고 합니다.

이상으로 글 마치겠습니다.

출처

#Gemini CLI#구글#터미널#무료#API 키#Google AI Studio#Antigravity CLI#설치 가이드

같은 분류의 글