# Experimental Gemini API CLI — Documentation > [!CAUTION] > **Disclaimer**: This is not a supported Google product. > Develop, test, and deploy Gemini Agents. Run interactions across every model and modality. --- ## Installation ### Via Install Script (Recommended) You can install the pre-compiled binary directly (no cloning required) using this single-line command: ```bash curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | bash ``` ### From Source (via npm) ```bash git clone https://github.com/google-gemini/gemini-api-cli.git cd gemini-api-cli npm install -g . ``` **Requirements:** Bun ≥ 1.1 or Node.js ≥ 22 --- ## Authentication ```bash # Option 1: Environment variable (recommended) export GEMINI_API_KEY="your-api-key" # Option 2: Flag (works with any command) gemini-api run "Hello" --api-key "your-api-key" ``` Get your API key at [aistudio.google.com](https://aistudio.google.com/). --- ## Quick Start ```bash # Run a prompt against a model gemini-api run "What is the capital of France?" # Use a specific model gemini-api run "Explain quantum computing" --model gemini-3.1-pro-preview # Scaffold an agent gemini-api agents init my-agent cd my-agent # Edit agent.yaml and AGENTS.md, then test locally gemini-api agents test --prompt "Hello, what can you do?" # Deploy to the platform gemini-api agents create # Test the deployed agent gemini-api run "Hello" --agent my-agent # List and manage agents gemini-api agents list gemini-api agents delete my-agent ``` --- ## Commands ### `gemini-api run <prompt>` Create an interaction against a model or agent. ```bash gemini-api run "What is the capital of France?" gemini-api run "Explain this code" --model gemini-3.1-pro-preview gemini-api run "Analyze my data" --agent my-data-analyst ``` | Flag | Short | Type | Default | Description | |---|---|---|---|---| | `<prompt>` | | positional | — | Input prompt. | | `--model` | `-m` | string | `gemini-3.5-flash` | Model to use | | `--agent` | `-a` | string | — | Agent to use (overrides `--model`) | | `--input` | `-i` | string[] | — | Multimodal input: `image:path`, `audio:path`, `video:path`, `document:path` | | `--output` | `-o` | string | — | Save generated media to file | | `--previous-interaction-id` | `-p` | string | — | Continue from previous interaction | | `--system-instruction` | `-s` | string | — | System instruction | | `--response-modality` | | enum[] | — | `text`, `image`, `audio`, `video`, `document` | | `--response-mime-type` | | string | — | MIME type for response | | `--tool` | | string[] | — | Tool declaration (can be repeated): `code_execution`, `google_search`, `mcp_server:name:url` | | `--source` | | string[] | — | Environment source (can be repeated): `inline:target:content`, `github:url:target`, `gcs:source:target` | | `--voice` | | string | — | TTS voice name | | `--language` | | string | — | TTS language code | | `--aspect-ratio` | | enum | — | Image aspect ratio (e.g., `16:9`) | | `--image-size` | | enum | — | `512`, `1K`, `2K`, `4K` | | `--edit-strength` | | float | — | How much to change the original image (0.0 to 1.0) | | `--mask` | | string | — | Path to a mask image for localized editing | | `--service-tier` | | enum | — | `flex`, `standard`, `priority` | | `--json` | `-j` | boolean | `false` | Output raw SSE events as JSONL | | `--dry-run` | | boolean | `false` | Print curl command and exit | | `--api-key` | | string | `$GEMINI_API_KEY` | API key | | `--base-url` | | string | `$GEMINI_API_BASE_URL` | Override API base URL | **Examples:** ```bash # Model interaction gemini-api run "Write a haiku about code" # Image understanding gemini-api run "What's in this image?" --input image:photo.jpg # Image editing gemini-api run "Add a red hat" --input image:person.jpg --response-modality image --output with_hat.jpg # Image generation gemini-api run "A cat in space" --model gemini-3.1-flash-image-preview --output cat.png # Text-to-speech gemini-api run "Hello my name is gemini, i am a large language model from google. I can help you with a wide range of tasks." --model gemini-3.1-flash-tts-preview --voice Kore --output hello.wav # With tools gemini-api run "What is the weather?" --tool google_search --tool code_execution # With sources (e.g. antigravity-preview-05-2026) gemini-api run "Generate test" --agent antigravity-preview-05-2026 --source "inline:/.agents/README.md:# Instructions" --source "github:https://github.com/user/repo:/.agents" # Multi-turn gemini-api run "Remember the word: banana" # → interaction_id: int_abc123 gemini-api run "What word?" --previous-interaction-id int_abc123 # Dry run gemini-api run "Hello" --dry-run ``` --- ### `gemini-api agents` Manage the full agent lifecycle. #### `gemini-api agents init <name>` Scaffold a new agent project. ```bash gemini-api agents init my-agent gemini-api agents init my-agent --base-agent antigravity-preview-05-2026 gemini-api agents init my-agent --from-template https://github.com/google-gemini/Gemini-API-Agent-Templates/tree/main/customer-data-analysis-agent ``` | Flag | Type | Default | Description | |---|---|---|---| | `<name>` | positional | — | Agent directory name | | `--base-agent` | string | `antigravity-preview-05-2026` | Base model (only 'antigravity-preview-05-2026' is supported) | | `--from-template` | string | — | Git or GCS URL to scaffold from | #### `gemini-api agents create` Deploy agent from current directory. ```bash gemini-api agents create gemini-api agents create --path ./my-agent gemini-api agents create --dry-run ``` | Flag | Type | Default | Description | |---|---|---|---| | `--path` | string | `.` | Agent directory | | `--base-env` | string | — | Override base environment | | `--dry-run` | boolean | `false` | Print curl | | `--json` | boolean | `false` | JSON output | #### `gemini-api agents list` ```bash gemini-api agents list gemini-api agents list --json gemini-api agents list --dry-run ``` #### `gemini-api agents get <id>` ```bash gemini-api agents get my-agent gemini-api agents get my-agent --json gemini-api agents get my-agent --dry-run ``` #### `gemini-api agents delete <id>` ```bash gemini-api agents delete my-agent gemini-api agents delete my-agent --force gemini-api agents delete my-agent --dry-run ``` | Flag | Type | Default | Description | |---|---|---|---| | `--force` | boolean | `false` | Skip confirmation | #### `gemini-api agents test` Run an interaction using local agent config. ```bash gemini-api agents test --prompt "Hello" gemini-api agents test --prompt "Hello" --path ./my-agent gemini-api agents test --prompt "Continue" --previous-interaction-id int_abc --environment env_xyz gemini-api agents test --prompt "Hello" --dry-run ``` | Flag | Type | Default | Description | |---|---|---|---| | `--prompt` | string | — | Input prompt (required) | | `--path` | string | `.` | Agent directory | | `--previous-interaction-id` | string | — | Multi-turn | | `--environment` | string | — | Use existing environment | | `--json` | boolean | `false` | JSON output | | `--dry-run` | boolean | `false` | Print curl | --- ### `gemini-api files` Manage environment files. #### `gemini-api files download <env-id>` Download all files from the environment as a snapshot and extract them into a folder named `snapshot_<env-id>` in the output directory. ```bash gemini-api files download env_xyz789 gemini-api files download env_xyz789 --output ./results gemini-api files download env_xyz789 --dry-run ``` | Flag | Type | Default | Description | |---|---|---|---| | `--output` | string | `./` | Output directory | --- ## Agent Configuration ### Directory Structure ``` my-agent/ ├── agent.yaml # Configuration (not inlined) ├── AGENTS.md # System instructions (inlined to /.agents/AGENTS.md) ├── skills/ # Custom skills (all files inlined recursively) └── workspace/ # Files seeded into remote environment (all files inlined recursively) ``` ### `agent.yaml` ```yaml # Required id: my-agent base_agent: antigravity-preview-05-2026 # Optional description: "A data analyst agent" instructions: "You are a helpful assistant." # Tools tools: - type: code_execution - type: google_search # Environment environment: remote # OR derive from existing environment # base_environment: env_abc123 ``` ### `AGENTS.md` Agent instructions in markdown. Uploaded to the remote environment and loaded before running. Use for long instructions — easier to read, diff, and version than `instructions` in `agent.yaml`. ### `workspace/` Files seeded into the remote environment at `/.agents/workspace/`. All files in this directory are inlined into the API request when running `agents test` or `agents create`. **File handling:** | File type | How it's sent | Example extensions | |---|---|---| | Text files | Inlined as UTF-8 strings | `.md`, `.py`, `.csv`, `.json`, `.yaml` | | Binary files | Base64-encoded with `"encoding": "base64"` | `.pdf`, `.png`, `.jpg`, `.mp3`, `.wav`, `.zip` | | Files > 1 MB | Skipped | — | > **Note:** Only `AGENTS.md`, `workspace/`, and `skills/` are inlined from the agent directory. All other root-level files and directories are ignored. Binary files are automatically detected by extension. The following are treated as binary: - Images: `.png`, `.jpg`, `.jpeg`, `.webp`, `.gif`, `.bmp`, `.tiff`, `.heic`, `.heif` - Audio: `.wav`, `.mp3`, `.aac`, `.ogg`, `.flac`, `.opus`, `.m4a` - Video: `.mp4`, `.mov`, `.avi`, `.webm`, `.wmv` - Documents: `.pdf` - Archives: `.zip`, `.tar`, `.gz`, `.bz2`, `.xz`, `.7z` ### `environment` (in `agent.yaml`) Controls the sandbox environment for the agent: ```yaml # Enable a managed sandbox environment environment: remote # OR reuse an existing environment by ID # base_environment: env_abc123 ``` When `environment` is `"remote"`, the API provisions a sandbox with code execution capabilities. Workspace files and skills are seeded into it before the agent runs. You can also specify a structured config object to configure GCS/GitHub `sources`, establish `network` allowlists, and inject secret credentials securely via header `transform` rules: ```yaml environment: type: "remote" # Sources to copy or clone into the environment on startup sources: - type: "gcs" source: "gs://my-bucket-name/folder/" target: ".agents/workspace" - type: "github" source: "https://github.com/my-username/my-repo" target: ".agents/workspace/repo" # Outbound network security policies and headers injection (secrets) network: allowlist: - domain: "api.github.com" transform: # Injects Authorization header dynamically at egress proxy level Authorization: "Bearer your-github-token" - domain: "storage.googleapis.com" transform: Authorization: "Bearer your-gcloud-oauth-token" - domain: "*.wikipedia.org" # Catch-all rule (optional) to allow other traffic without header injection - domain: "*" ``` --- ## Tools ### `agent.yaml` Tools ```yaml tools: - type: code_execution - type: google_search search_types: [web_search, image_search] - type: url_context ``` --- ## Output Modes ### Normal (Default) Optimized for clean, readable output and valid Markdown parsing. Thoughts are concise, tool calls are consolidated into single lines, and the final response text is printed without leading indentation: ``` [thought] [tool] write_file(path="hello.py") -> {"success":true} [code] python3 hello.py -> "Hello, World!" [text] I have created a Python script named `hello.py` and successfully executed it. Here is the content of `hello.py`: ```python print("Hello, World!") ``` ``` ### Verbose (`--verbose` / `-v`) Optimized for automated parsing by agents. Steps are output as completed single-line JSON objects, followed by the final `{interaction}` metadata as a JSON line: ```json {"index":0,"type":"thought","status":"completed","thought":{"signature":"EvQBCvEBAQw5..."}} {"index":1,"type":"function_call","status":"completed","function_call":{"name":"write_file","arguments":{"path":"hello.py","content":"print(\"Hello, World!\")"}}} {"index":2,"type":"function_result","status":"completed","function_result":{"name":"write_file","result":{"success":true}}} {"interaction":{"id":"v1_ChdIcjRp...","status":"completed","usage":{"total_tokens":9131,"total_input_tokens":8970,"total_output_tokens":161,"total_cached_tokens":0},"object":"interaction"}} ``` ### JSON (`--json`) Raw streamed SSE events as JSONL (one raw event per line): ```jsonl {"event_type":"interaction.created","interaction":{...}} {"index":0,"step":{"type":"thought"},"event_type":"step.start"} {"index":0,"delta":{"signature":"EvQBC...","type":"thought_signature"},"event_type":"step.delta"} {"event_type":"interaction.completed","interaction":{...}} ``` ### Dry Run (`--dry-run`) Prints the equivalent `curl` command and exits without making an API call. --- ## Multimodal I/O ### Input ```bash gemini-api run "Describe this" --input image:photo.jpg gemini-api run "Transcribe" --input audio:meeting.wav gemini-api run "Summarize" --input document:report.pdf ``` ### Output ```bash gemini-api run "Draw a cat" --model gemini-3-pro-image-preview --output cat.png gemini-api run "Read aloud" --model gemini-3.1-flash-tts-preview --voice Kore --output speech.wav ``` --- ## Multi-Turn Conversations ```bash # First turn gemini-api run "Analyze the dataset" # → interaction_id: int_abc123 # Second turn — continues the conversation gemini-api run "Summarize in 3 bullets" --previous-interaction-id int_abc123 ``` For agent tests with environments: ```bash gemini-api agents test --prompt "Analyze data" # → interaction_id: int_abc123 # → environment: env_xyz789 gemini-api agents test --prompt "Now chart it" \ --previous-interaction-id int_abc123 \ --environment env_xyz789 ``` --- ## Interaction Logging Every interaction is automatically logged to `.gemini/logs/<interaction-id>.jsonl` in the current directory. Logs contain the request and reassembled response (SSE events combined into final content blocks). ``` .gemini/ └── logs/ └── int_abc123.jsonl ``` Each file has 2 lines: - **Line 1:** Request (model, input, tools, system instruction) - **Line 2:** Response (outputs, usage, status) Binary data (images, audio) is excluded from logs. --- ## Troubleshooting ### No API key ``` ✗ No API key found. Try: export GEMINI_API_KEY="your-api-key" gemini-api run "Hello" --api-key "your-api-key" ``` ### No agent.yaml ``` ✗ No agent.yaml found in /home/user/project. Try: gemini-api agents init my-agent cd my-agent && gemini-api agents create ``` ### Model not found ``` ✗ API error (400): Model 'nonexistent' not found. Try: gemini-api run "Hello" --model gemini-3-flash-preview ``` ### Debug output Use `--verbose` to see request/response details: ```bash gemini-api run "Hello" --verbose ``` ### Preview requests Use `--dry-run` to see the curl equivalent without making an API call: ```bash gemini-api agents create --dry-run ``` --- ## Environment Variables | Variable | Description | |---|---| | `GEMINI_API_KEY` | API key for authentication | | `GEMINI_API_BASE_URL` | Override API base URL | | `AGENTS_WORKSPACE_PATH` | Target path prefix for inline files (default: `/.agents/`) | --- ## Models | Model | Description | |---|---| | `gemini-3.5-flash` | Frontier + search (default) | | `gemini-3.1-pro-preview` | SOTA reasoning + multimodal | | `gemini-3-flash-preview` | Gemini 3 Flash Preview | | `gemini-3.1-flash-lite` | Gemini 3.1 Flash-Lite | | `gemini-2.5-flash` | Hybrid reasoning, 1M context | | `gemini-2.5-pro` | SOTA coding + reasoning | | `gemini-3-pro-image` | Nano Banana Pro (image generation) | | `gemini-3.1-flash-image` | Nano Banana 2 (image generation) | | `gemini-2.5-flash-image` | Native image generation | | `gemini-3.1-flash-tts-preview` | Text-to-speech | | `gemini-2.5-flash-preview-tts` | TTS | | `gemini-2.5-pro-preview-tts` | TTS (pro) | | `gemini-2.5-computer-use-preview-10-2025` | Computer use | | `lyria-3-clip-preview` | Music: clip generation | | `lyria-3-pro-preview` | Music: full-song | ## Agents | Agent | Description | |---|---| | `deep-research-preview-04-2026` | Deep Research (latest) | | `deep-research-max-preview-04-2026` | Deep Research Max | --- ## License Apache-2.0