Gemini API CLI (gemini-api)
Release
License: Apache 2.0
이미 사용하고 있는 에이전트를 위한 Gemini 모델 및 관리형 에이전트.
Codex, Claude Code, Antigravity, OpenClaw, Hermes 또는 다른 모든 에이전트에 셸 접근(shell access)을 통해 Gemini API를 사용할 수 있는 기능을 부여하세요. API 키를 구성하고, gemini-api를 PATH에 추가하면, 사용자의 에이전트가 모델을 선택하거나, 자산을 생성하거나, 파일을 분석하거나, 작업을 처리할 관리형 에이전트를 실행하도록 할 수 있습니다.
사용자 에이전트가 작업 계획을 세우고, Gemini는 모델과 관리형 에이전트를 제공합니다. 이 상태 비저장(stateless) CLI는 표준 셸 명령어를 통해 이들을 연결합니다:
gemini-api image "A friendly robot mascot for a developer tool" --out ./assets/
프롬프트가 입력되면, 이미지 파일이 프로젝트에 생성됩니다. 사용자의 에이전트는 해당 파일 경로를 받아 계속해서 작업을 진행합니다. 이 동일한 바이너리는 분석 결과, 음성 녹음(voiceover), 스크립트, 또는 백그라운드 관리형 에이전트 실행의 상호작용 ID 등을 반환할 수 있습니다.
설치 · 빠른 시작 · 명령어 개요 · 에이전트 검색 및 머신 인터페이스 · 작업 흐름 · Gemini API 문서
이 CLI를 사용하는 이유 (Why this CLI)
앱을 구축하는 코딩 에이전트는 히어로 이미지, 음성 녹음, 디자인에 대한 두 번째 의견, 또는 PDF 내부의 답변 등이 필요할 수 있습니다. 비서(assistant)는 녹음을 캡션으로 변환하거나 다단계 리서치를 위임해야 할 수도 있습니다. 해당 에이전트에게 gemini-api와 API 키를 제공하면, 작업이 요구하는 순간에 이러한 기능을 직접 호출할 수 있게 됩니다.
- 모델, 미디어 및 관리형 에이전트를 위한 단일 바이너리: 명령줄에서 텍스트 및 추론 모델, 멀티모달 파일 분석, 이미지/오디오/음악/비디오 생성 기능, 그리고 관리형 에이전트에 접근할 수 있습니다.
- 장기 실행 작업 위임(Delegate long-running work): Gemini 관리형 에이전트를 백그라운드에서 시작하고, 반환된 상호작용 ID를 유지한 다음 필요할 때 결과를 검색할 수 있습니다.
- 자기 설명적 인터페이스: 명령어, 플래그, 요청 스키마(
--schema), 그리고 기계가 읽을 수 있는 사용법(--usage)이 바이너리에 내장되어 있어 에이전트가 필요한 내용을 실시간으로 검사할 수 있습니다.
- 안전한 건식 실행(Safe dry-run validation):
--dry-run은 네트워크 호출이나 OS 키체인 읽기 없이 입력값을 유효성 검사하고, 자격 증명이 제거된 해결된 HTTP 요청을 출력합니다.
- 스크립트 및 에이전트에 친화적인 출력: 텍스트를 스트리밍하거나 미디어를 디스크에 직접 작성할 수 있으며, 구조화된 JSON(
--output-format json) 또는 압축된 TOON(--output-format toon)을 방출하거나 --jq로 필드를 인라인 필터링할 수 있습니다.
- 상태 비저장 실행(Stateless execution): 각 호출은 독립적으로 실행됩니다. 에이전트가 컨텍스트를 제공하고, 모델을 선택하며, 다음 단계를 제어합니다.
코딩 에이전트 및 어시스턴트 도구의 헤드리스 사용에 최적화되었으며, 셸 스크립트와 CI 작업에도 동일한 인터페이스를 사용할 수 있습니다. macOS, Linux, Windows에서 작동하는 단일 Go 바이너리입니다.
설치 (Installation)
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
Go 설치
Go를 사용하여 최신 릴리스를 설치합니다:
go install github.com/google-gemini/gemini-api-cli/cmd/gemini-api@latest
현재 개발 버전을 빌드하려면 @latest 대신 @main을 사용하십시오. 현재 main은 Go 1.26.10 이상이 필요합니다 (Go의 자동 도구 체인 선택 기능이 필요한 경우 해당 버전을 다운로드합니다).
사전 구축된 바이너리 (Prebuilt binaries)
macOS, Linux 및 Windows용 사전 빌드 아카이브를 GitHub Releases에서 다운로드하고 gemini-api를 PATH에 배치하세요.
빠른 시작 (Quick start)
Google AI Studio에서 API 키를 생성하고( [Gemini API key docs] 참조) 이를 셸 또는 에이전트의 서브프로세스 환경에서 사용할 수 있도록 만드세요:
export GEMINI_API_KEY="YOUR_API_KEY"
워크스테이션 팁: 키를 OS 키체인(macOS Keychain, Linux Secret Service 또는 Windows Credential Manager)이나 ~/.config/gemini-api/config.yaml에 영구 저장하려면 gemini-api configure --api-key "YOUR_API_KEY"를 실행하거나 gemini-api configure --interactive로 대화형 양식을 열어주세요. 활성 구성 및 자격 증명 소스는 언제든지 gemini-api whoami로 확인할 수 있습니다.
로컬에서 --dry-run(네트워크 호출 없음)으로 설정을 확인한 다음, API를 호출하려면 --dry-run을 제거하세요:
gemini-api generate "Hello from my agent" --dry-run
gemini-api generate "Hello from my agent"
2. 에이전트에게 지침 주기 (Give your agent instructions)
다음 블록을 에이전트의 지침(AGENTS.md, CLAUDE.md, .cursorrules 또는 도구 구성)에 추가하세요:
You have access to gemini-api through the shell.
Use it to call Gemini models, generate or edit media, analyze files, or launch managed agents.
1. Inspect --help or --usage to choose a command, and --schema when building a --body JSON payload.
...
3. 에이전트 작동시키기 (Put your agent to work)
호스트 에이전트에 평소처럼 프롬프트를 입력하세요:
Build a landing page for this app. Use Gemini to create a mascot image and a welcome voiceover, and launch a managed research agent to investigate competing products. Incorporate the assets and findings into the page.
에이전트는 명령을 선택하고 셸에서 실행하며, 반환된 파일 경로와 상호 작용 ID를 자체 워크플로우에 사용합니다.
명령어 개요 (Command overview)
모든 최상위 명령어는 gemini-api --help를 실행하여 확인하거나, 특정 명령어의 플래그 및 예시는 gemini-api <명령어> --help를 사용합니다.
| Category | Command | Subcommands / Key Flags | Description & default model |
|---|
| Create | gemini-api generate | -m, -i/--input, --stdin, --system, --stream=false, --body | 텍스트 및 멀티모달 생성 (gemini-3.8-flash) |
| ... | | | |
에이전트 디스커버리 및 머신 인터페이스 (Agent discovery and machine interface)
에이전트가 gemini-api를 사용하는 데 필요한 모든 것은 외부 문서나 자격 증명 없이 바이너리 자체에서 발견할 수 있습니다:
| 에이전트가 필요로 하는 경우… | 실행하는 명령어… |
|---|
| 명령어 및 플래그를 발견해야 할 때 | gemini-api --help 또는 gemini-api --usage |
| ... | |
--usage: 완전한 명령어 트리, 플래그, 기본값, 환경 변수 및 구성 키를 기계가 읽을 수 있는 KDL 형식으로 출력합니다.--schema: 요청 본문(request body)을 허용하는 모든 명령어에 대해 번들링된 JSON Schema (draft 2020-12)를 출력합니다.--dry-run: 플래그와 페이로드(payload)를 검증하고, 자격 증명이나 네트워크 접근 없이 HTTP 요청을 미리 보여줍니다. (기계가 파싱 가능한 JSON 요청 미리보기를 위해서는 --dry-run --output-format json을 사용하십시오.)--no-interactive: 모든 대화형 프롬프트(prompt)와 TUI 양식을 비활성화합니다.--agent-mode (또는 GEMINI_CLI_AGENT_MODE=1): stderr에 구조화된 JSON 오류 봉투(error envelope)를 활성화하고, stdout을 간결한 TOON 출력으로 기본 설정합니다. (--output-format json은 명시적으로 JSON을 선택합니다.)- 종료 코드 (Exit codes): 성공(
0), 런타임/API 실패(1), 잘못된 사용법/검증 오류(2), 인증/권한 부여 실패(3)를 구분합니다.
모든 전역 인증(authentication), 네트워크, 출력 및 진단 플래그는 gemini-api --help-global을 실행하여 확인하십시오.
에이전트 워크플로우 (Agent workflows)
1. 창의적 에셋 생성 및 편집 (Generate and edit creative assets)
Codex, Claude Code 또는 Antigravity와 같은 코딩 에이전트는 앱을 구축하는 동시에 이미지, 음성(speech), 음악 및 비디오를 생성할 수 있습니다.
<!-- readme-examples: skip (needs local file from previous command) -->
MASCOT_PATH=$(gemini-api image "A friendly robot mascot, soft studio lighting" --out ./assets/mascot.jpg)
...
미디어 명령어는 파일을 로컬에 작성하고 stdout으로 작성된 파일 경로만 출력합니다. --out이 디렉토리를 가리키거나 생략된 경우, CLI는 API가 반환한 MIME 유형과 일치하는 파일 확장자를 사용하여 자동으로 파일 이름을 지정합니다 (예: image/jpeg의 경우 .jpg, audio/wav의 경우 .wav, audio/mpeg의 경우 .mp3, video/mp4의 경우 .mp4).
2. 문서 분석 및 녹음 기록 전사(Transcribe)
OpenClaw나 Hermes와 같은 어시스턴트는 문서, 미디어 파일 및 YouTube URL을 답변과 결과물로 변환할 수 있습니다:
<!-- readme-examples: skip (needs local files) -->
gemini-api analyze --input product-brief.pdf "What should we build first, and why?" > plan.md
gemini-api analyze --input before.png --input after.png "Summarize the visual design changes"
...
더 큰 미디어 파일(원시 데이터 기준 약 14MB 초과 / base64 인코딩 기준 20MB 초과)의 경우, 한 번 files upload --wait으로 업로드하고 반환된 files/<id> URI를 analyze, transcribe, generate, image, video, 또는 agent run 전반에 걸쳐 재사용할 수 있습니다:
<!-- readme-examples: skip (needs local file and uploaded file URI) -->
FILE_URI=$(gemini-api files upload interview.mp4 --wait --output-format json --jq '.name')
gemini-api analyze --input "$FILE_URI" "List the key action items with timestamps"
3. 백그라운드 관리 에이전트 실행 및 폴링(Poll)
Deep Research와 같은 Gemini 관리 에이전트에 다단계 리서치 또는 코딩 작업을 위임할 수 있습니다. --background를 전달하면 CLI가 SSE 스트림을 열어 유지하는 대신, 즉시 상호작용 ID와 함께 단일 상호작용(스트리밍되지 않음, --stream이 전달된 경우 제외)을 반환합니다:
INTERACTION_ID=$(gemini-api agent run "Research battery recycling approaches and cite sources"
--agent deep-research-preview-04-2026
--background
...
반환된 `INTERACTION_ID`를 사용하여 진행 상황을 확인하거나 완료된 결과물을 검색할 수 있습니다:
```bash
gemini-api agent status "$INTERACTION_ID" --stream=false --output-format json
또한 실시간 진행 이벤트를 스트리밍(gemini-api agent status "$INTERACTION_ID" --stream)하거나 활성 실행을 취소할 수 있습니다 (gemini-api agent cancel "$INTERACTION_ID").
4. 적절한 모델 선택하기
생성(generation) 및 분석(analysis) 명령어에서 --model (-m)을 사용하여 추론(reasoning), 빠른 텍스트(fast text), 멀티모달 이해(multimodal understanding), 또는 미디어 생성(media generation)에 사용할 모델을 선택할 수 있습니다:
더 깊이 탐구하기: 사용자 지정 요청 본문 (--schema부터 --body)
단축 플래그는 일반적인 작업을 다루며, --body를 사용하면 CLI의 파일 출력 및 오류 처리를 유지하면서 에이전트가 근본적인 Interactions API 요청 스키마에 완전히 접근할 수 있게 해줍니다.
먼저 image에 대한 스키마를 검사합니다:
gemini-api image --schema > image-schema.json
다음으로, gemini-nano-banana-2.1을 선택하고, 16:9 비율의 2K 크기 이미지(image_size: "512", "1K", "2K", 또는 "4K")를 요청하며, 서버 측 상호작용 저장소 기능을 비활성화하는 hero-image.json 파일을 생성합니다 ("store": false):
cat > hero-image.json <<'JSON'
{
"model": "gemini-nano-banana-2.1",
...
--dry-run을 사용하여 정확한 HTTP 페이로드를 미리 보고, 요청을 실행합니다:
<!-- readme-examples: skip (needs local hero-image.json file) -->
gemini-api image --body @hero-image.json --out ./assets/hero.jpg --dry-run --output-format json
gemini-api image --body @hero-image.json --out ./assets/hero.jpg --output-format json
--output-format json을 사용하면 CLI가 이미지를 디스크에 작성하고 stdout에서 구조화된 아티팩트 메타데이터를 반환합니다:
{
"kind": "image",
"mime_type": "image/jpeg",
...
`--out`은 로컬 파일 저장 위치를 제어하며, `response_format`은 모델이 생성할 내용을 제어합니다 (전체 원시 API 응답 구조체를 얻으려면 `--out` 대신 `--raw-response` 플래그를 사용하십시오). 동일한 `--schema`에서 `--body`로 이어지는 작업 흐름(workflow)은 `system_instruction`, `tools`, 구조화된 JSON 형식의 `response_format.schema`, 또는 `previous_interaction_id`를 통한 상태 유지 다중 턴 연속 처리(stateful multi-turn continuations)를 구성할 때도 `gemini-api agent run` 및 기타 명령어에 적용됩니다:
<!-- readme-examples: skip (uses shell variable from previous turn) -->
```bash
# 1차 턴: 스트리밍이 아닌 상호 작용을 실행하고 해당 ID를 캡처합니다.
TURN1_ID=$(gemini-api generate "시간 계열 로그 테이블에 대한 데이터베이스 인덱싱 전략 3가지 제안." \
--stream=false --jq '.id')
...
CLI는 로컬 대화 상태를 저장하지 않습니다. 서버 측 상호 작용 및 업로드된 파일은 API에서 자체적으로 보존을 관리하며, 사용자의 작업 흐름(workflow)은 재사용하려는 ID만 유지합니다.
상태, 피드백 및 기여
