Call the Gemini API from the shell with Google's `gemini-api` CLI, when that binary is installed — text and reasoning, image generation and editing, text-to-speech, music, video, document/audio/video/YouTube analysis, transcription and captions, file uploads, and managed agents (Deep Research) run in the background. Use when the task needs a Gemini model or a second opinion from one, a generated image/voiceover/soundtrack/clip, an answer out of a PDF or recording, an SRT caption file, or a long-running research agent. Triggers: 'use gemini', 'ask gemini', 'gemini-api', 'generate an image', 'make a voiceover', 'transcribe this', 'analyze this PDF', 'deep research'. Not for writing application code against the Gemini SDK or Vertex AI.
95%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
gemini-api is Google's single-binary CLI for the Gemini Interactions API. Each
invocation does one thing and returns either text on stdout or a file path on disk.
Verified command details, output shapes, and gotchas: references/cli.md.
gemini-api whoami prints the config file, the credential source, and the active
defaults. If it reports no API key, stop and ask the user to set one — never guess at a
key or edit their config. The persistent form is gemini-api configure --api-key "...",
which writes to the OS keychain; GEMINI_API_KEY in the environment also works.
If the binary is missing, say so and offer to install it from
https://github.com/google-gemini/gemini-api-cli (install.sh, or
go install github.com/google-gemini/gemini-api-cli/cmd/gemini-api@latest). Do not pipe
an install script into a shell without the user agreeing first, and do not hand-roll
curl calls against the REST API as a substitute.
The CLI is beta and the Interactions API moves fast. When a flag in this skill is
rejected, trust the binary: run --help on that command and adapt.
Never guess a flag. The binary describes itself, offline and without credentials:
| Need | Run |
|---|---|
| Which command, which flags | gemini-api <cmd> --help |
| The whole command tree, machine-readable | gemini-api --usage (KDL) |
| The exact request body schema | gemini-api <cmd> --schema |
| Validate before spending a call | gemini-api <cmd> ... --dry-run |
| Every global flag | gemini-api --help-global |
--dry-run makes no network call and does not read the keychain, but it does read local
--input files, so it also checks that they exist and that the MIME type is detected.
| Task | Command | Default model |
|---|---|---|
| Ask a model, stream the reply | generate | gemini-3.8-flash |
| Generate or edit an image | image | gemini-nano-banana-2.1 |
| Voiceover, narration, two-speaker dialogue | tts | gemini-3.8-flash-tts |
| Music bed, soundtrack | music | lyria-3.5 |
| Video clip, or edit one conversationally | video | gemini-omni-1.1-flash |
| Question about a PDF, image, audio, video, CSV, or YouTube URL | analyze | gemini-3.8-flash |
| Transcript or SRT captions | transcribe | gemini-3.5-transcribe |
| Long-running research or agent task | agent run --background | --agent deep-research-preview-04-2026 |
| Reuse a file over several calls, or send >14 MB of media | files upload --wait | — |
| See what models this key can reach | models / models list --all | — |
Full request control for anything the short flags do not reach: agent run --body @req.json,
after gemini-api agent run --schema. --body is available on generate, image,
music, video, and agent run only.
cat notes.md | gemini-api generate "summarize" fails with a parse error. Add --stdin to send piped
text as the prompt. This is the most common first-run failure.MASCOT=$(gemini-api image "..." --out ./assets/mascot.jpg).--stream=false -o json returns one
complete interaction object. While streaming, -o json emits the raw NDJSON event
stream instead.--jq. It works without -o json, and --raw-output (on
by default) prints strings unquoted. The reply text is nested in steps, not at the
top level:gemini-api generate "..." --stream=false \
--jq '[.steps[] | select(.type=="model_output") | .content[].text] | join("")'Exit codes are meaningful: 0 ok, 1 runtime/API failure, 2 bad usage or validation,
3 auth. Branch on them instead of grepping stderr. -o json turns errors into a
structured JSON envelope on stderr; --agent-mode does the same but also switches
default stdout to TOON, so pair it with -o json or --jq.
Every non---dry-run call spends the user's API quota, and image, music, and video calls
are the expensive ones.
-m gemini-3.1-flash-lite as of 0.4.5.
Reserve the Pro and frontier models for hard reasoning the user asked for.--dry-run first when the payload is hand-built.--out with an explicit path. Without it, generated files land in the
working directory under an auto-generated name.gemini-api files delete files/<id>.A managed agent run can take many minutes. Start it detached, keep the ID, and do other work:
ID=$(gemini-api agent run "Research battery recycling approaches, cite sources" \
--agent deep-research-preview-04-2026 --background --jq '.id')
gemini-api agent status "$ID" -o json --jq '.status'Poll on a sensible interval, not in a tight loop, and report the ID to the user so the
run is not lost if the session ends. agent cancel "$ID" stops it.
generate, image, music, video, and agent run store the interaction
server-side by default — it stays retrievable by its ID (verified). For a sensitive
prompt, add --body '{"store":false}' and say that you did, or clean up afterwards with
gemini-api agent delete-interaction <id>. tts, analyze, and transcribe send
store:false themselves and have no --body, so nothing is needed there.credentials, webhooks, triggers, and environments create or change server-side
state. Confirm with the user before running their create, update, or delete
subcommands. Never start environments connect|poll|serve unasked: those execute
remotely dispatched work on this machine.imagen (image generation), deep-research (the Deep Research agent), and
google-tts/elevenlabs (speech) each cover a slice of what this CLI does. Prefer
gemini-api when the binary is installed: one dependency and a live model catalog
instead of pinned model names.
sanjay3290/ai-skills
c842558
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.