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 for text generation, multi-turn conversations, and tool usage.
• Agents (Lifecycle): See references/agents.md for creating, testing, and managing agents.
• Agent Calls: See references/agent_calls.md for invoking antigravity-preview-05-2026 and Deep Research agents.
• Genmedia: See references/genmedia.md for image generation, image editing, and text-to-speech.

Basic Usage

The primary command is gemini-api run.

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.

gemini-api run "Hello" --dry-run

Help (--help)

Displays usage information and available flags for any command.

gemini-api --help
gemini-api run --help

JSON Output (--json)

Outputs raw SSE events as JSONL (one event per line), useful for machine parsing.

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.

gemini-api run "Hello" --verbose

Agent Calls

This reference covers how to interact with Gemini Agents using the gemini-api run command.

antigravity-preview-05-2026 (Custom Agents)

When you create a custom agent (which defaults to using antigravity-preview-05-2026 as the base agent), you interact with it using the --agent flag followed by the agent ID.

gemini-api run "Analyze this dataset for trends" --agent my-custom-agent

If the agent requires files in its workspace, ensure they are provided or already uploaded.

Passing Environment Sources

When using --agent antigravity-preview-05-2026 (or a custom agent based on it), you can pass environment sources using the --source flag. This allows you to seed files or clone repositories into the agent's environment. Custom sources override the default auto-enabled environment.

gemini-api run "Generate a video" \
  --agent antigravity-preview-05-2026 \
  --source "inline:/.agents/README.md:# Instructions" \
  --source "github:https://github.com/user/repo:/.agents"

Supported source types:

• inline:<target>:<content>: Creates a file with the specified content.
• github:<url>:<target>: Clones a GitHub repository to the target path.
• gcs:<source>:<target>: Copies files from Google Cloud Storage to the target path.

Deep Research

Deep Research is a specialized agent designed for long-running, complex research tasks. You can invoke it using the specific agent ID listed in the models/agents table.

Invoke the latest Deep Research agent:

gemini-api run "Research the latest developments in room-temperature superconductors" \
  --agent deep-research-preview-04-2026

Invoke Deep Research Max (for more extensive research):

gemini-api run "Provide a comprehensive analysis of the global semiconductor supply chain" \
  --agent deep-research-max-preview-04-2026

[!NOTE]

Deep Research queries often take longer to complete and may involve multiple steps and tool usage (like web search) automatically.

Gemini Agents

This reference covers managing the lifecycle of Gemini Agents using the CLI.

Scaffolding a New Agent

Create a new agent project directory:

gemini-api agents init my-agent

This creates a directory with the default structure.

Agent Directory Structure

my-agent/
├── agent.yaml       # Configuration (ID, tools, etc.) — 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)

Note: Only AGENTS.md, workspace/, and skills/ are inlined from the agent directory. All other root-level files and directories (e.g., README.md, package.json) are ignored during agents test and agents create.

Adding Skills

To add a skill to your agent, place the skill files (e.g., SKILL.md, references/) in the skills/ directory of your agent project. The agent will have access to these skills when running in its environment.

Agent Configuration (agent.yaml)

Required fields:

• id: Agent identifier
• base_agent: Base model (Supported only: antigravity-preview-05-2026)

Optional fields:

• description: Description of the agent
• system_instruction: Short system instruction (prefer AGENTS.md for long instructions)
• tools: List of tools (e.g., code_execution, google_search)
• environment: "remote", a base environment ID, or a structured config object to configure sources, network allowlists, and secrets injection:

  environment:
    type: "remote"
    sources:
      - type: "gcs"
        source: "gs://my-bucket/folder/"
        target: ".agents/workspace"
    network:
      allowlist:
        - domain: "api.github.com"
          transform:
            Authorization: "Bearer your-github-token"
        - domain: "*" # Catch-all

Testing an Agent Locally

You can test your agent configuration locally before creating it on the platform:

cd my-agent
gemini-api agents test --prompt "Hello, what are your instructions?"

Or specify the path:

gemini-api agents test --prompt "Hello" --path ./my-agent

Creating/Deploying an Agent

Deploy the agent to the platform:

cd my-agent
gemini-api agents create

This will output the agent ID and environment ID.

Running an Interaction with an Agent

Once created, you can run prompts against the agent:

gemini-api run "Analyze my data" --agent my-agent

Listing Agents

List all agents you have created:

gemini-api agents list

Use --json for machine-readable output:

gemini-api agents list --json

Deleting an Agent

Delete an agent from the platform:

gemini-api agents delete my-agent

Use --force to skip confirmation:

gemini-api agents delete my-agent --force

Downloading Files from Agent Environment

You can download all files from an agent's environment (e.g., generated data, logs) as a snapshot:

gemini-api files download <env-id>

Specify an output directory:

gemini-api files download <env-id> --output ./results

Handling Long-Running Tests

Tests initiated via agents test can take multiple minutes to complete.

• Do Not Interrupt: Be patient and allow the command to run.
• Streaming: Streaming is enabled by default. The CLI will stream output live.

Best Practices

• Always check that the current directory contains agent.yaml before running local commands.
• Use --dry-run to see what the CLI would do without executing.
• Prefer AGENTS.md for detailed instructions rather than putting them all in agent.yaml's system_instruction.

Genmedia (Image, Audio, TTS)

This reference covers generating and editing media using the Gemini API CLI.

Image Generation

To generate an image, use a model that supports image generation and specify an output file with --output or -o.

gemini-api run "A cat in space, oil painting" --model gemini-3.1-flash-image --output cat.png

Supported image models include:

• gemini-3-pro-image (Nano Banana Pro)
• gemini-3.1-flash-image (Nano Banana 2)
• gemini-2.5-flash-image

Image Editing

You can edit an existing image by providing it as input and describing the changes:

gemini-api run "Add a red hat to the person" \
  --input image:person.jpg \
  --response-modality image \
  --output with_hat.jpg

Text-to-Speech (TTS)

To generate audio from text, use a TTS model and specify an audio output file:

gemini-api run "Hello, I can help you with a wide range of tasks." \
  --model gemini-3.1-flash-tts-preview \
  --voice Kore \
  --output hello.wav

Supported TTS models:

• gemini-3.1-flash-tts-preview
• gemini-2.5-flash-preview-tts
• gemini-2.5-pro-preview-tts

Music Generation (Lyria)

The CLI supports Lyria models for music generation, although specific command examples are minimal. You would typically use the run command with a Lyria model and an appropriate output extension (e.g., .wav or .mp3).

Supported Lyria models:

• lyria-3-clip-preview (Music clips)
• lyria-3-pro-preview (Full-song generation)

Example (inferred usage):

gemini-api run "A happy upbeat electronic track" --model lyria-3-pro-preview --output song.wav

Normal Model Calls

This reference covers standard interactions with Gemini models using the gemini-api CLI.

Basic Prompting

Run a simple prompt against the default model (gemini-3.5-flash):

gemini-api run "What is the capital of France?"

Specifying a Model

Use the --model or -m flag to specify a different model:

gemini-api run "Explain quantum computing" --model gemini-3.1-pro-preview

Common models:

• gemini-3.5-flash (default)
• gemini-3.1-pro-preview
• gemini-3.1-flash-lite

Multi-Turn Conversations

To continue a conversation, use the --previous-interaction-id or -p flag with the ID returned from the previous command.

# First turn
gemini-api run "Remember the word: banana"
# Output will include: interaction_id: v1_...

# Second turn
gemini-api run "What word did I tell you to remember?" --previous-interaction-id v1_...

Using Tools

You can enable tools like Google Search or Code Execution:

gemini-api run "What is the current weather in Tokyo?" --tool google_search
gemini-api run "Calculate the 100th Fibonacci number" --tool code_execution

You can repeat the --tool flag to enable multiple tools:

gemini-api run "Research and analyze the latest AI trends" --tool google_search --tool code_execution

Multimodal Input

Pass files as input using the --input or -i flag:

gemini-api run "Describe this image" --input image:path/to/photo.jpg
gemini-api run "Summarize this document" --input document:path/to/report.pdf