Google이 터미널에서 Gemini API의 주요 기능을 쓰는 명령줄 도구(CLI) 'Gemini API CLI'를 공개했다. 실행 명령은 gemini-api이며, 실험적 프리뷰 단계의 0.4.x 버전을 GitHub에서 내려받을 수 있다. 공개 발표는 2026년 10월 23일(현지시간)이고, 소개 트윗은 Dmitry Lyalin이 10월 22일에 올렸다.1,2
이미지와 영상 생성, 음악 생성, 음성 합성(TTS), 멀티모달 분석, 음성 전사, 매니지드 에이전트 실행과 관리를 지원한다. 주 대상은 셸 명령을 실행할 수 있는 AI 에이전트이며, 터미널에서 일하는 개발자도 쓴다. Google 자체 환경에만 묶여 있지 않다. 맥OS, 리눅스, 윈도우에서 쓰고, 의존성 설치가 필요 없는 단일 Go 바이너리다. 코드는 Apache 2.0, 그 밖의 자료는 CC BY 4.0 라이선스이다. 사용하려면 Gemini API 키가 필요하다.1,2
에이전트가 겪던 불편을 겨냥
Google은 에이전트가 모델 식별자를 직접 찾아야 하고, 일회성 SDK 스크립트를 짜거나 복잡한 curl 명령을 반복하고, 생성된 미디어를 긴 문자열로 다뤄야 하는 문제를 이 도구의 해결 대상으로 꼽았다. Lyalin도 트윗에서 에이전트가 모델 문자열을 추측하거나 일회성 스크립트를 쓰거나 curl을 끝없이 반복할 필요가 없다고 소개했다.1
Google은 개발 도구를 세 계층으로 설명한다. Gemini API가 추론, 멀티모달 분석, 미디어 생성, 에이전트 실행을 맡고, 파이썬·타입스크립트·Go·자바용 Google Generative AI SDK가 서비스와 백엔드를 맡는다. Gemini API CLI는 터미널과 셸 기반 에이전트용이다. Google은 운영 서비스에는 자료형이 명확한 클라이언트 라이브러리가 맞고, 터미널 개발자와 자율 에이전트에는 상태가 없고 명령과 입력 형식을 파악하기 쉬운 CLI가 필요하다고 설명했다. 이 CLI는 Gemini Interactions API와 함께 발전하고 있다.1,2
설계와 명령
상태를 저장하지 않는 구조다. 호출마다 독립적으로 실행되고, 맥락과 모델, 다음 단계는 에이전트가 정하며, 로컬에는 대화 상태가 남지 않는다. 미디어 명령은 결과를 파일로 저장하고 stdout에는 파일 경로만 출력한다. --out이 폴더이거나 생략되면 MIME 타입에 맞춰 .jpg, .wav, .mp3, .mp4 확장자로 이름을 붙인다.
에이전트가 사용법을 스스로 읽도록 --help와 --usage, --schema를 둔다. --usage는 명령 트리, 플래그, 기본값, 환경변수, 설정 키를 KDL 형식으로 보여 주고, --schema는 요청 본문의 JSON Schema(draft 2020-12)를 출력하며, 오프라인에서도 확인된다. --dry-run은 네트워크 호출이나 OS 키체인 읽기 없이 입력을 검증하고, 자격증명을 가린 HTTP 요청을 미리 보여 준다.
출력은 텍스트 스트리밍, JSON(--output-format json), TOON(--output-format toon) 중에서 고르고, --jq로 필드를 뽑을 수 있다. --agent-mode 또는 환경변수 GEMINI_CLI_AGENT_MODE=1을 켜면 stderr에 구조화된 JSON 오류가 나오고, stdout은 기본 TOON이며 JSON은 명시해야 한다. --no-interactive는 대화형 프롬프트와 TUI를 끈다. 종료 코드는 0이 성공, 1이 런타임이나 API 실패, 2가 잘못된 사용이나 검증 오류, 3이 인증·권한 실패다.1,2
짧은 플래그로 부족하면 --body로 Interactions API 요청 스키마 전체에 접근한다. system_instruction, tools, response_format.schema, 멀티턴을 잇는 previous_interaction_id를 설정할 수 있다. 명령은 generate, image, tts, music, video, analyze, transcribe, agent(run·status·cancel 등), files, models, configure, auth/whoami, 고급 명령(environments, credentials, webhooks, triggers), explore, version으로 나뉜다.2
기능별 모델과 사용법
| 기능 | 모델 식별자 |
|---|---|
| 이미지 | gemini-nano-banana-2.1 |
| 영상 | gemini-omni-1.1-flash |
| 음악 | lyria-3.5 |
| 음성 합성 | gemini-3.8-flash-tts |
| 텍스트·분석·전사 | gemini-3.8-flash |
이미지 명령은 생성과 편집(-i로 입력 이미지 지정)을 하며, 크기 옵션은 512·1K·2K·4K이고 16:9 같은 종횡비를 지정할 수 있다. 영상은 대화형으로 생성하고 편집하며 --async 옵션이 있다. 음성 합성은 --multi-speaker로 여러 화자의 대화를 만든다(예: Alice=Kore,Bob=Puck). 음악 명령은 배경음악용 연주곡도 만든다.
분석 명령은 PDF, 이미지(여러 장 비교 가능), 오디오, 영상, CSV와 텍스트 파일, 유튜브 URL을 입력으로 받는다. 전사는 오디오와 영상을 md, text, json, srt 형식으로 내보내며, SRT는 타임스탬프가 붙은 자막이다. 원본이 약 14MB(base64 인코딩 시 20MB)를 넘으면 files upload --wait로 올린 뒤 files/ 아래에 부여되는 파일 URI를 재사용한다. Files API의 보관 기간은 48시간이다.
매니지드 에이전트는 백그라운드에서 돌아가며 딥 리서치 같은 작업을 맡길 수 있다. 상호작용 식별자(interaction ID)로 진행을 확인하고 결과를 받거나 agent status, agent cancel로 취소한다. --background --stream=false를 쓰면 ID를 바로 돌려받는다. 예시 에이전트는 deep-research-preview-04-2026이다.1,2
설치, 인증, 한계
설치는 맥·리눅스용 curl 스크립트, 윈도우용 PowerShell 스크립트, go install, GitHub Releases의 사전 빌드 바이너리, 소스 빌드 중에서 고른다. 최신 main 브랜치는 Go 1.26.10 이상이 필요하며 툴체인은 자동 선택된다. 인증에는 Google AI Studio에서 발급한 Gemini API 키가 필요하다. 환경변수 GEMINI_API_KEY, OS 키체인(macOS Keychain, Linux Secret Service, Windows Credential Manager), ~/.config/gemini-api/config.yaml 중 한 곳에 두고, gemini-api configure(--interactive는 대화형)로 설정하고 gemini-api whoami로 확인한다.
사용 사례로 제시된 에이전트는 Claude Code, Codex, OpenClaw, Hermes, Cursor이고, GitHub 문서에는 Codex, Claude Code, Antigravity, OpenClaw, Hermes가 언급된다. Google의 AI 개발 환경인 Antigravity에서도 지금 이 도구를 쓸 수 있다. 에이전트가 CLI를 호출한 뒤 결과 파일이나 작업 식별자를 다음 단계로 넘기는 방식이며, 네이티브 통합은 추후 지원할 예정이다. Google은 개발자 피드백을 반영해 도구를 발전시키겠다고 밝혔다.1,2
GitHub 문서는 베타 단계여서 릴리스 사이에 호환성이 깨지는 변경이 있을 수 있다며, CI나 자동화에서는 특정 릴리스 버전을 고정하라고 권한다. 현재 오픈소스 기여(풀 리퀘스트)는 받지 않으며, 피드백과 버그는 GitHub Issues로 접수한다.2
