# Gemini API CLI

> Guide for using the Gemini API CLI tool. Use when you need to interact with the Gemini API via the command line, manage agents, or generate media (images, audio).

- Skill: `google-gemini/gemini-api-cli` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add google-gemini/gemini-api-cli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/google-gemini/gemini-api-cli/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: Google Gemini (https://skillmd.com/u/google-gemini)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/google-gemini/gemini-api-cli

---


# Gemini API CLI Skill

This skill provides guidance on using the `gemini-api` command-line interface.

## Overview

The `gemini-api` CLI allows you to:
- Run prompts against various Gemini models.
- Manage the full lifecycle of Gemini Agents.
- Generate and edit media (images, audio, TTS).

## References

For detailed usage and examples, see the following references:

- **Normal Model Calls**: See [references/model_calls.md](references/model_calls.md) for text generation, multi-turn conversations, and tool usage.
- **Agents (Lifecycle)**: See [references/agents.md](references/agents.md) for creating, testing, and managing agents.
- **Agent Calls**: See [references/agent_calls.md](references/agent_calls.md) for invoking antigravity-preview-05-2026 and Deep Research agents.
- **Genmedia**: See [references/genmedia.md](references/genmedia.md) for image generation, image editing, and text-to-speech.

## Basic Usage

The primary command is `gemini-api run`.

```bash
gemini-api run "Hello, who are you?"
```

Always ensure your `GEMINI_API_KEY` environment variable is set.

## Global Flags & Features

The CLI supports several flags that are useful for debugging and automation:

### Dry Run (`--dry-run`)
Prints the equivalent `curl` command and exits without making an API call. Useful for verifying what request would be sent.
```bash
gemini-api run "Hello" --dry-run
```

### Help (`--help`)
Displays usage information and available flags for any command.
```bash
gemini-api --help
gemini-api run --help
```

### JSON Output (`--json`)
Outputs raw SSE events as JSONL (one event per line), useful for machine parsing.
```bash
gemini-api run "Hello" --json
```

### Verbose (`--verbose` / `-v`)
Outputs complete JSON step objects line-by-line as they finish. Recommended for programmatic parsing by calling agents.
```bash
gemini-api run "Hello" --verbose
```