gemini-cli

name

gemini-cli

description

Use this skill for service operations only. DO NOT use this skill for CLI implementation lifecycle work such as creating, testing, updating, troubleshooting, validating, removing, or documenting the CLI tool itself; delegate those tasks to cli-tool-expert. Execute Gemini API operations using the collision-safe `gemini-api` command. CLI interface for Gemini API -- chat, image generation, video analysis, deep research, file management, and usage tracking. Triggers: gemini, gemini cli, gemini chat, gemini image, gemini research, ask gemini, generate image with gemini, analyze video with gemini, gemini api usage, gemini deep research

Execute Gemini API operations using the repo-owned CLI. Always invoke it as `gemini-api`; never invoke the ambiguous bare command `gemini`, which is also installed by Google's unrelated npm Gemini coding-agent CLI.

<quick_start> The repo-owned Gemini API CLI follows this pattern:

gemini-api <command-group> <action> [arguments] [options]

Task	Command
Chat with Gemini	gemini-api chat new "Your prompt here"
Chat with file attachment	gemini-api chat new "Describe this" --file image.jpg
Generate an image	gemini-api image generate "A sunset over mountains" -o sunset.png
Analyze a video	gemini-api video analyze video.mp4 --prompt "Summarize this"
Start deep research	gemini-api research start "Research topic"
List models	gemini-api models list --table
Show API usage	gemini-api usage show --table
Check auth status	gemini-api auth status
</quick_start>

<essential_principles> MANDATORY: Consult the adjacent usage.json at <cli-tools-root>/_repo/skills/<tool>-cli/usage.json before executing ANY gemini-api command. This file contains complete command syntax, all arguments, all options, and usage instructions for every command. Never guess at command syntax.

**MANDATORY: Use `gemini-api`, not bare `gemini`, for every command in this skill.** Both the repo-owned Python Gemini API CLI and Google's npm coding-agent CLI install an executable named `gemini`; PATH ordering or a shell's cached command path can silently select the npm CLI. The repo-owned package also installs `gemini-api` as an unambiguous alias. - **auth** -- Manage API authentication (login, logout, status) - **chat** -- Chat and content generation with optional file attachments - **files** -- Upload, list, get, and delete files via the Gemini Files API - **image** -- Generate images from text prompts with model/size/aspect ratio control - **models** -- List available Gemini models - **research** -- Run autonomous deep research tasks with citations - **usage** -- View API usage statistics (local or cloud) - **video** -- Analyze video files with multimodal prompts

<reference_index> usage.json -- Complete command tree with arguments, options, defaults, and usage instructions for every command. </reference_index>

<success_criteria>

• Command executes without error
• Output is displayed in requested format
• Correct command and flags used (verified against usage.json) </success_criteria>

Deep Research (Interactions API)

gemini-api research start|status|resume drives the Gemini Deep Research Agent through the Google GenAI Interactions API. As of the May 2026 breaking change (legacy schema removed by the API on 2026-06-08), this requires:

• google-genai >= 2.0.0 (the gemini CLI pins >=2.0.0 in gemini/pyproject.toml). SDK 1.x sends the legacy Interactions schema and the API rejects it with HTTP 400: "The legacy Interactions API schema is no longer supported … adopt the new 'steps' schema." If research fails with that 400, the SDK is too old — reinstall with the cli-tool install script so uv resolves google-genai >= 2.0.0.
• The new "steps" schema: a completed Interaction exposes steps (not the legacy outputs) and the convenience property output_text. The CLI reads interaction.output_text for the final report. Streamed events use event_type values interaction.created, step.start, step.delta, step.stop, interaction.status_update, interaction.completed, error (replacing legacy interaction.start / content.delta / interaction.complete). step.delta deltas are typed by delta.type (text → delta.text, thought_summary → delta.content.text).
• Deep Research is background-only and paid-tier-only; a single task can run 5-20+ minutes. gemini-api research start defaults to --stream; callers that capture stdout (e.g. the ClientContentWriter research_article.js) use --no-stream, which prints the synthesized report to stdout and exits 0.
• Valid --agent values (SDK Literal): deep-research-pro-preview-12-2025 (default), deep-research-preview-04-2026, deep-research-max-preview-04-2026.

Migration reference: https://ai.google.dev/gemini-api/docs/interactions-breaking-changes-may-2026

Image Editing / Reference Images

gemini image generate accepts reference images via -i / --input-image (repeatable) for image editing and multi-image composition. Only the Nano Banana models support this (gemini-3-pro-image-preview, gemini-2.5-flash-image); Imagen models (imagen-4.0-*) will error if -i is passed. Images are sent as inline bytes to the Gemini API.

gemini-api image generate "make a slight variation" -i ./ref.png -o out.png
gemini-api image generate "compose these two scenes" -i a.png -i b.png -m gemini-2.5-flash-image