Experimental Gemini API CLI

An experimental CLI for the Gemini API.

Features

• Model Interactions: Run prompts against Gemini models with support for streaming, system instructions, and service tiers.
• Multimodal Support: Handle image understanding, image generation, and text-to-speech (TTS).
• Agent Lifecycle: Scaffold (init), deploy (create), test, and delete custom agents.
• Deep Research: Support for long-running Deep Research tasks with automatic polling and reconnection.
• Tools: Integrate tools like Code Execution and Google Search.
• Environment Management: Download snapshots of agent environments and pass custom sources (inline, github, gcs) to agents.

Installation

Via Install Script (Recommended)

You can install the pre-compiled binary directly (no cloning required) using this single-line command:

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

From Source (via npm/Node.js)

If you don't have Bun, you can install it as a Node.js package (requires Node.js ≥ 22):

git clone https://github.com/google-gemini/gemini-api-cli.git
cd gemini-api-cli
npm install -g .

Quick Start (for development)

# Install dependencies
bun install

# Run in dev mode
bun run dev -- run "Hello"

# Build standalone binary for current platform
bun run compile
./dist/gemini-api --version

Commands

# Run an interaction against a model
gemini-api run "What is the capital of France?"

# Scaffold, test, and deploy agents
gemini-api agents init my-agent
gemini-api agents test --prompt "Hello"
gemini-api agents create

# Manage environment files
gemini-api files download <env-id>

E2E Tests

We have a suite of End-to-End (E2E) tests located in tests/e2e/. These scripts run both the --dry-run variant (to show the command) and the live variant (to show the result).

To run a specific test:

bash tests/e2e/cuj_01.sh

See E2E.md for a full list of Critical User Journeys and their status.

Skills

This repository includes a skill for AI agents to understand how to use this CLI.

• Gemini API CLI Skill — Comprehensive guide for agents, covering:
  • Normal model calls (text, multi-turn, tools)
  • Agent lifecycle management (init, create, test, delete)
  • Agent calls (invoking antigravity-preview-05-2026 and Deep Research)
  • Genmedia (image generation, editing, TTS, music)

Documentation

• DOCS.md — Full user guide and reference
• tests/e2e/E2E.md — End-to-End Test Plan

Releasing New Versions

To release a new version and make the binaries available via the install script:

1. Update the version in package.json and src/cli.ts.
2. Commit and push the changes.
3. Create a new Release on GitHub with a tag matching v* (e.g., v0.2.0).
4. The Release Binaries GitHub workflow will automatically trigger, build the standalone binaries for all supported platforms, and upload them as assets to the release.

Licensing & Disclaimer

Copyright 2026 Google LLC

All software is licensed under the Apache License, Version 2.0 (Apache 2.0); you may not use this file except in compliance with the Apache 2.0 license. You may obtain a copy of the Apache 2.0 license at: https://www.apache.org/licenses/LICENSE-2.0

All other materials are licensed under the Creative Commons Attribution 4.0 International License (CC-BY). You may obtain a copy of the CC-BY license at: https://creativecommons.org/licenses/by/4.0/legalcode

Unless required by applicable law or agreed to in writing, all software and materials distributed here under the Apache 2.0 or CC-BY licenses are distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the licenses for the specific language governing permissions and limitations under those licenses.

This is not an official Google product.