구글이 에이전트용 Gemini API CLI를 공개했다

Gemini API CLI(gemini-api)는 셸을 사용할 수 있는 AI 에이전트와 스크립트·CI에서 Gemini를 호출하는 무상태·무의존성 명령줄 도구다. 텍스트와 미디어 생성, 파일 분석, Gemini 관리형 에이전트 실행을 지원하며 Antigravity, Claude Code, Codex, Cursor, OpenClaw, Hermes 등에서 쓸 수 있다.

모든 기능은 Interactions API를 사용하는 일반 셸 명령으로 실행한다. 에이전트의 하위 프로세스, 터미널, CI 파이프라인에서 같은 명령을 쓸 수 있다.

# 1. Install on macOS or Linux curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | bash # 2. Set your API key export GEMINI_API_KEY="YOUR_API_KEY" # 3. Generate media, analyze a file, or launch a background managed agent gemini-api image "Minimalist isometric icon of a cloud database" --out ./assets/db-icon.jpg gemini-api analyze -i ./docs/quarterly-report.pdf "Summarize the key findings in three bullets." gemini-api agent run "Compare WebRTC SFU architectures and cite sources" \\ --agent deep-research-preview-04-2026 \\ --background \\ --stream=false

gemini-api는 프로젝트에 SDK 코드를 추가하지 않고 셸에서 Gemini를 직접 호출하려는 에이전트나 스크립트에 적합하다. 애플리케이션에 Gemini 기능을 넣으려면 Google GenAI SDK를, 에이전트가 최신 문서를 검색하며 SDK 규칙을 따르게 하려면 Gemini Docs MCP 및 skills를 사용할 수 있다. 애플리케이션 코드, 백엔드 서비스, 실시간 Live API 세션을 만들 때는 SDK를 사용한다.

에이전트를 위한 설계

원시 REST 호출과 대화형 CLI는 에이전트에서 문제를 일으킬 수 있다. Base64 미디어가 컨텍스트 창을 채우고, 대화형 프롬프트가 하위 프로세스를 멈추게 하며, 오래된 학습 데이터 때문에 존재하지 않는 플래그를 만들어낼 수 있다는 점을 고려해 네 가지 방식을 적용했다.

• 오프라인 스키마 조회: --usage는 KDL 형식의 명령 트리를, --schema는 --body 요청의 JSON Schema를 출력한다.
• 파일은 디스크에, 경로는 표준 출력에: 미디어·전사 명령은 파일을 디스크에 쓰고 출력 경로만 표준 출력으로 내보내 바이너리 데이터가 컨텍스트에 들어오지 않게 한다.
• 드라이런과 구조화된 출력: --dry-run은 입력값을 검증하고 인증 정보를 가린 뒤 HTTP 요청을 오프라인에서 미리 보여준다. 기계 판독이 가능한 결과에는 -o json, -o toon, --jq를 쓸 수 있다. --agent-mode는 표준 오류에 구조화된 JSON 오류를 내보내며, 실패 처리는 종료 코드로 할 수 있다. --interactive를 지정하지 않는 한 명령은 프롬프트를 띄우지 않는다.
• 기본적으로 무상태: 명령은 숨은 로컬 상태를 보관하지 않는다. 여러 단계의 작업은 --previous-interaction-id, 업로드한 files/<id> URI, 또는 백그라운드 상호작용 ID를 명시해 연결한다.

-o json을 사용해도 미디어 명령은 파일을 디스크에 저장하고 메타데이터만 표준 출력으로 내보낸다. 예시는 다음과 같다.

{ "kind": "image", "mime_type": "image/jpeg", "path": "/path/to/project/assets/db-icon.jpg", "response_id": "v1_...", "size_bytes": 2914159, "status": "completed" }

설치와 인증

설치한 뒤 gemini-api를 PATH에 추가하고 GEMINI_API_KEY를 설정한다. 코딩 에이전트에도 사용 규칙을 알려줘야 한다.

macOS와 Linux에서는 설치 스크립트를 실행한다.

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

특정 릴리스를 설치하려면 GEMINI_VERSION에 릴리스 태그를 지정한다.

curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | GEMINI_VERSION=<release-tag> bash

Windows에서는 PowerShell에서 다음 명령을 쓴다.

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

Go를 사용한 설치 명령은 다음과 같다.

go install github.com/google-gemini/gemini-api-cli/cmd/gemini-api@latest

macOS, Linux, Windows용 버전별 사전 빌드 아카이브는 GitHub Releases에서 받을 수 있다. 아카이브에서 gemini-api를 꺼내 PATH에 추가하면 된다. Docker 이미지와 CI에서 버전을 고정할 때 사전 빌드 아카이브를 사용할 수 있다.

Google AI Studio에서 API 키를 만들고, API 키 안내를 참고해 셸과 에이전트의 하위 프로세스 환경에 GEMINI_API_KEY를 설정한다.

export GEMINI_API_KEY="YOUR_API_KEY"

로컬 워크스테이션에서는 키를 운영체제 키체인(macOS Keychain, Linux Secret Service, Windows Credential Manager)에 저장할 수 있다. --no-keyring을 지정하면 대신 ~/.config/gemini-api/config.yaml에 저장한다.

# Save to your OS keychain (or run gemini-api configure --interactive) gemini-api configure --api-key "YOUR_API_KEY" # Check the active credential source, then preview a request offline gemini-api whoami gemini-api generate "Confirm CLI setup in one sentence." --dry-run

코딩 에이전트 설정

프로젝트의 AGENTS.md, CLAUDE.md, .cursorrules 또는 시스템 프롬프트에 다음 내용을 추가하면 에이전트가 CLI 사용법을 알 수 있다.

## Gemini API CLI (`gemini-api`)
You have access to `gemini-api` through the shell. Use it to generate text or media (images, speech, music, video), analyze documents and recordings, or run and manage Gemini managed agents.
1. Run `gemini-api --help` or `gemini-api --usage` to choose a command, and `gemini-api <command> --schema` before building a `--body` JSON payload.
2. Preview unfamiliar or complex calls offline with `--dry-run -o json`.
3. For a single JSON result or `--jq` filtering on `generate` or `agent run`, pass `--stream=false -o json`.
4. To chain multi-step workflows, capture the output paths that media and transcription commands print to stdout, and the `id` values returned by `generate` or `agent run`.

이후에는 평소처럼 코딩 에이전트에 작업을 요청하면 된다. 원문은 개발자 도구용 랜딩 페이지를 만들고, Gemini로 대표 이미지와 15초 분량의 환영 음성을 생성하며, 경쟁 CLI의 온보딩 흐름을 비교하는 Deep Research 에이전트를 백그라운드에서 실행한 뒤 결과를 페이지에 반영하는 요청을 예로 든다.

명령 전체 목록은 gemini-api --help로 볼 수 있고, gemini-api explore를 실행하면 대화형으로 탐색할 수 있다.

각 명령은 작업에 맞는 모델을 기본값으로 사용한다. 다른 모델을 선택하려면 --model 또는 -m을 지정한다. 사용 가능한 모델은 gemini-api models로 확인한다.

이미지를 생성하거나 편집할 때는 웹·모바일 UI용 자리표시자, 아이콘, 대표 이미지를 Nano Banana로 만들 수 있다. 생성한 이미지 경로를 -i에 넘기면 편집할 수 있다. 다음 예시는 2K 해상도의 16:9 이미지를 생성한 뒤 겨울 스카프와 눈을 추가한다.

# Generate a 16:9 image at 2K resolution (512, 1K, 2K, or 4K) and capture its path HERO_PATH=$(gemini-api image "Friendly robot mascot in a sunlit workshop, space on left for headline" \\ --aspect-ratio 16:9 \\ --image-size 2K \\ --out ./public/images/hero.jpg) # Edit the generated image gemini-api image "Add a winter scarf and soft snowfall outside the window" \\ -i "$HERO_PATH" \\ --out ./public/images/hero-winter.jpg

-i를 여러 번 지정하면 캐릭터와 스타일 가이드처럼 여러 참고 이미지를 함께 사용할 수 있다.

gemini-api tts는 UI 효과음, 접근성 미리보기, 설명 음성 등에 쓸 24 kHz WAV 오디오를 합성한다. 기본 음성은 Kore이며 --voice로 바꿀 수 있다. 두 화자의 대화는 프롬프트에서 발화마다 화자를 표시하고 음성을 연결한다.

gemini-api tts "Build succeeded. All integration tests passed." \\ --voice Aoede \\ --out ./public/audio/build-ok.wav gemini-api tts "Alice: Welcome to the release walkthrough! Bob: Let's look at what shipped today." \\ --multi-speaker "Alice=Kore,Bob=Puck" \\ --out ./public/audio/release-intro.wav

Lyria로 음악을 만들고 Gemini Omni로 MP4 클립을 생성할 수 있다.

gemini-api music "Warm ambient synth and acoustic guitar background loop, 95 BPM" \\ --out ./public/audio/bg-loop.mp3 gemini-api video "A drone shot of a mountain landscape at sunrise." \\ --aspect-ratio 16:9 \\ --resolution 1080p \\ --out ./public/video/mountain-sunrise.mp4

video 명령은 기본적으로 생성이 끝날 때까지 기다린 뒤 MP4 파일을 디스크에 쓴다. --async를 지정하면 상호작용 ID를 즉시 반환하며, 나중에 gemini-api video --resume <id> --out <path>를 실행해 이어갈 수 있다. 기존 이미지에 움직임을 더하려면 -i를 지정한다.

gemini-api generate는 생성한 텍스트를 표준 출력으로 스트리밍한다.

gemini-api generate "Write a one-paragraph welcome message for new users of a note-taking app."

--stdin을 추가하면 파이프로 전달한 텍스트를 프롬프트에 넣을 수 있다. 이전 상호작용을 이어가려면 --previous-interaction-id를 지정한다.

analyze는 PDF, 스프레드시트, 스크린샷, 오디오·비디오 파일과 공개 YouTube URL에 관한 질문에 답한다. transcribe는 md, text, json, srt 형식의 전사문을 디스크에 저장한다.

gemini-api analyze -i ./docs/product-brief.pdf "List the open questions and who owns each one." > open-questions.md gemini-api transcribe -i ./fixtures/customer-call.mp4 --format srt --out ./fixtures/customer-call.srt

analyze에 -i를 여러 번 지정하면 전후 스크린샷처럼 여러 파일을 비교할 수 있다.

gemini-api는 최대 14 MB의 로컬 파일을 인라인으로 전송한다. Base64 인코딩을 포함한 요청 크기는 20 MB까지다. 더 큰 파일은 files upload --wait로 업로드하고 반환된 files/<id> URI를 재사용한다.

FILE_URI=$(gemini-api files upload ./recordings/all-hands.mp4 --wait) gemini-api analyze -i "$FILE_URI" "List action items with owners and timestamps." gemini-api transcribe -i "$FILE_URI" --format json --out ./recordings/all-hands.json

관리형 에이전트와 사용자 지정 요청

코딩 에이전트는 Gemini 관리형 에이전트에 여러 단계의 조사나 샌드박스 작업을 맡길 수 있다. 예를 들면 Deep Research 에이전트를 사용할 수 있다. --background --stream=false를 지정하면 스트림을 열어 둔 채 기다리지 않고 상호작용 ID를 즉시 받는다.

# Launch a Deep Research job in the background and capture its interaction ID RESEARCH_ID=$(gemini-api agent run "Compare open-source vector index benchmarks and cite primary papers." \\ --agent deep-research-preview-04-2026 \\ --background \\ --stream=false \\ --jq '.id') # Check status or fetch the finished result while continuing other work gemini-api agent status "$RESEARCH_ID" -o json

실행 중인 작업은 gemini-api agent cancel <id>로 취소할 수 있다. agent run으로 원격 샌드박스에서 Antigravity 에이전트를 실행하거나, agent create, list, get, delete로 사용자 지정 에이전트를 관리할 수도 있다. 에이전트 샌드박스 설정은 Environments 안내를 참고하면 된다.

전용 플래그가 없는 옵션은 --body에 Interactions API의 원시 JSON 페이로드를 전달해 설정한다. JSON을 명령에 직접 넣거나 @file.json 형식으로 파일을 지정할 수 있다. --body로 response_format 스키마, 함수 호출 도구, generation_config, "store": false 등을 설정할 수 있다. 유효한 필드를 확인하려면 먼저 gemini-api <command> --schema를 실행한다.

# Inspect the JSON Schema for the request body gemini-api generate --schema > generate-schema.json # Return schema-constrained JSON and skip storing the interaction cat logs.txt | gemini-api generate "Extract every error message from these logs." \\ --stdin \\ --body '{ "response_format": { "type": "text", "mime_type": "application/json", "schema": { "type": "object", "properties": {"errors": {"type": "array", "items": {"type": "string"}}}, "required": ["errors"] } }, "store": false }'

--body는 명령 플래그와 병합된다. 같은 키를 양쪽에서 지정하면 명령이 종료 코드 2로 실패해 입력 충돌을 초기에 알린다.

종료 코드와 제약

명령은 오류 문구를 해석하지 않고도 스크립트와 에이전트가 실패를 처리하도록 유형별 종료 코드를 반환한다. 예를 들어 3은 인증 문제, 2는 잘못된 명령 구문을 뜻한다.

모든 명령에서 공유하는 인증·출력·네트워크·진단 관련 전역 플래그는 gemini-api --help-global로 확인할 수 있다.

generate와 agent run처럼 스트리밍하는 명령에서 -o json 또는 --jq를 함께 사용해 단일 JSON 응답 객체를 받으려면 --stream=false가 필요하다. 인라인 -i 입력은 원본 파일 기준 14 MB까지이며 Base64 인코딩을 포함한 요청 페이로드는 20 MB까지다. 더 큰 파일은 gemini-api files upload로 올려야 하며, Files API에 업로드한 파일은 48시간 뒤 삭제된다.

gemini-api는 일반 HTTP 요청, SSE 스트리밍, 비동기 폴링을 지원하지만 양방향 WebSocket은 지원하지 않는다. 실시간 음성·비디오 스트리밍에는 Live API와 Google GenAI SDK를 사용해야 한다.

관련 자료: 코딩 에이전트 설정, Interactions API, Gemini 관리형 에이전트, GitHub의 gemini-api-cli.