코딩 에이전트에 Gemini 붙이기: gemini-api CLI 실전 가이드

이미 Claude Code나 Codex를 쓰고 있다면 Gemini CLI로 갈아탈 이유는 크지 않습니다. 2026년 10월 19일 공개된 gemini-api는 대화형 에이전트가 아니라, 기존 에이전트의 셸에서 Gemini API를 호출하는 상태 없는 단일 바이너리입니다. 이미지·음성·영상 생성과 PDF·유튜브 분석을 기존 워크플로에 붙입니다.

이 글은 2026년 10월 23일 기준 v0.4.3으로 설치·도움말·드라이런을 확인하고, 공식 README 명령을 정리했습니다. 실제 생성 호출은 API 키와 과금이 필요하므로 결제 전 확인 항목도 짚습니다.

Gemini CLI와 Gemini API CLI는 이름만 비슷합니다

gemini-cli는 터미널에서 대화하며 코드를 고치는 에이전트이고, gemini-api는 그 에이전트가 셸에서 호출하는 API 실행 도구입니다.

gemini-api는 Gemini CLI의 후속이 아니라 기존 에이전트에 Gemini를 붙이는 어댑터입니다. 셸 접근이 가능한 Claude Code, Codex, Antigravity에서 같은 방식으로 쓸 수 있습니다.

설치: 단일 바이너리, Windows는 PATH를 먼저 확인합니다

Go로 만든 단일 바이너리라 Node.js나 Python 런타임이 필요 없습니다.

# macOS·Linux
curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | bash

# Windows PowerShell
iwr -useb https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.ps1 | iex

Windows는 PATH 추가 후 터미널을 다시 열어야 인식됩니다.

$ gemini-api version
gemini-api 0.4.3
Built: 2026-10-19T18:56:28Z

인증: 키를 코드에 넣지 않는 세 가지 방법

키는 환경 변수, 키체인, 설정 파일 중 하나로 관리합니다.

export GEMINI_API_KEY="YOUR_API_KEY"
gemini-api generate "Hello from my agent" --dry-run
gemini-api configure --api-key "YOUR_API_KEY"
gemini-api whoami

configure는 macOS Keychain, Linux Secret Service, Windows Credential Manager를 사용합니다. 키체인이 없으면 --no-keyring으로 설정 파일에 저장할 수 있고, whoami는 현재 키와 설정 파일 위치를 마스킹해 보여줍니다.

결제 전에는 --dry-run으로 요청 본문을 확인합니다. 네트워크 호출과 키체인 읽기 없이 실제 요청을 보여줍니다. 아래 출력은 일부 필드를 줄인 것입니다.

$ gemini-api generate "Hello from my agent" --dry-run --output-format json
{"dry_run":true,"request":{"method":"POST","url":".../v1beta/interactions","body":{"model":"gemini-3.8-flash","stream":true}}}

첫 4개 명령: 텍스트·분석·이미지·에이전트

--help는 전체 명령을, models는 모델 카탈로그를 보여줍니다.

# 텍스트
gemini-api generate "Explain concurrency in one sentence" --stream=false --output-format json

# 파일·이미지·PDF·유튜브 분석
gemini-api analyze -i report.pdf "Summarize the key findings"

# 이미지 생성·편집
gemini-api image "a lighthouse at sunset" --aspect-ratio 16:9 --image-size 2K --out shots/hero.jpg

# 백그라운드 에이전트
ID=$(gemini-api agent run "Research battery recycling approaches" \
  --agent deep-research-preview-04-2026 --background --stream=false --jq '.id')
gemini-api agent status "$ID" --stream=false --output-format json

실전 워크플로: 스크린샷을 디자인 리뷰 JSON으로

gemini-api analyze -i screenshot.png \
  "List spacing, contrast, and hierarchy issues. Return JSON with severity and fix." \
  --stream=false --output-format json > review.json

응답 JSON의 텍스트 필드를 이슈 템플릿에 붙이면 리뷰 형식을 매번 같게 유지할 수 있습니다. 필드 이름은 --schema와 실제 응답으로 확인합니다.

기존 코딩 에이전트에 붙이기: AGENTS.md에 넣는 지시문

AGENTS.md, CLAUDE.md, .cursorrules에 짧은 규칙을 넣으면 에이전트가 gemini-api를 스스로 호출합니다.

셸에서 gemini-api를 사용할 수 있다.
Gemini 모델 호출, 미디어 생성·편집, 파일 분석, 관리형 에이전트 실행에 사용한다.
호출 전에 --dry-run으로 요청을 확인하고, JSON은 --stream=false --output-format json으로 받는다.
반환된 파일 경로와 interaction ID를 저장해 다음 단계에 사용한다.

이 지시문이 있으면 "히어로 이미지를 만들어 줘" 같은 요청에 gemini-api image를 선택하고, 반환된 경로를 다음 작업에 씁니다. --agent-mode는 오류를 JSON으로, --output-format toon은 토큰을 줄입니다. 종료 코드는 성공 0, 런타임 1, 사용법 2, 인증 3입니다.

한계와 주의점: beta, 비용, 보안

• beta입니다. v0.4.3 기준이며 breaking change 가능성이 있습니다. CI에서는 릴리스 버전을 고정하고, 모델명은 gemini-api models로 확인하십시오.
• 과금과 한도를 확인하십시오. 모델·티어별 가격이 다르고 이미지·영상은 텍스트보다 비쌉니다.
• 파일 보관 기간이 있습니다. Files API 업로드는 48시간 보관됩니다. 큰 파일은 files upload --wait로 올리고 files/<id>를 재사용합니다.
• 설치 스크립트를 그대로 믿지 마십시오. curl | bash와 iwr | iex 대신 Releases의 바이너리를 직접 받는 편이 안전합니다.

도입 전 확인할 5가지

• gemini-api version으로 버전을 확인하고 CI·문서에 기준 버전을 적었는가?
• API 키를 코드·깃에 넣지 않고 환경 변수나 키체인으로 관리하는가?
• 첫 호출을 --dry-run으로 확인해 요청 본문과 모델을 검증했는가?
• gemini-api models와 --schema로 모델·필드를 확인했는가?
• 생성 파일의 저장 위치와 48시간 보관 정책을 정리했는가?

자주 묻는 질문

Q1. Gemini CLI와 Gemini API CLI는 무엇이 다른가요?

gemini-cli는 대화하며 코드를 수정하는 에이전트이고, gemini-api는 기존 에이전트나 스크립트가 Gemini API를 호출하도록 돕는 실행 도구입니다.

Q2. 무료로 쓸 수 있나요?

티어와 모델에 따라 무료 한도와 과금이 다릅니다. 이미지·영상 생성은 별도 비용이 발생할 수 있으므로 공식 가격표와 rate limit을 확인해야 합니다.

Q3. 기존 코딩 에이전트에 어떻게 붙이나요?

gemini-api를 PATH에 두고 키를 환경 변수나 키체인에 설정한 뒤, AGENTS.md·CLAUDE.md에 셸 사용 지시를 추가합니다. JSON이 필요하면 --stream=false --output-format json을 사용합니다.

참고 자료

• Google AI Studio, 『Introducing the Gemini API CLI』 (Philipp Schmid, 2026-10-19)
• Google, 『gemini-api-cli README』 (코드 Apache 2.0, 문서 CC BY 4.0)
• Google AI for Developers, 『Using Gemini API keys』
• Google AI for Developers, 『Gemini Developer API pricing』

---

🔮 관련 인사이트 & 추천 가이드

• Gemini 3.8 Flash 에이전트와 구글 워크스페이스 실시간 자동화
• 2026 3대 플래그십 삼국지 비교: Gemini 3.7 Flash vs GPT-5.6 Sol vs Claude Opus 4.8
• MCP 생태계 완전 정복 - 2026년, AI 코딩의 핵심 인프라