cli-anything-gemini

name	cli-anything-gemini
description	Click + REPL CLI that wraps HanaokaYuzu/Gemini-API so agents can chat with Gemini and generate images via the user's logged-in web session (cookie auth, no API key, no metered billing). Use when an agent needs to invoke Gemini for chat or image generation from a shell or pipeline.

cli-anything-gemini

Generated by /cli-anything:cli-anything https://github.com/HanaokaYuzu/Gemini-API (2026-05-17).

What this CLI is

A thin Click-based shell over HanaokaYuzu/Gemini-API. The library reverse-engineers the gemini.google.com web protocol and authenticates with browser cookies (__Secure-1PSID + __Secure-1PSIDTS), so calls ride the user's existing Google AI subscription instead of a metered API key.

The CLI adds:

• a stable subcommand grammar (auth, models, chat, image, session)
• a Click-based REPL (default behaviour when invoked with no subcommand)
• a uniform --json envelope for agent consumption
• persistent session state (active chat cid, history, defaults) with file-locked auto-save
• a tested cookie loader that accepts four common JSON export shapes

When to invoke this CLI

• Agent needs a single-shot Gemini answer in a shell pipeline.
• Agent wants to keep chatting in a stateful conversation that survives across CLI invocations.
• Agent wants Gemini to generate one or more images for a prompt and have the PNG paths returned in JSON.
• Agent needs to inspect or delete previous Gemini chats.

Prerequisites

1. Python ≥ 3.10.
2. Library install: pip install gemini-webapi (or install the bundled Gemini-API/ source under this entry).
3. CLI install: from the entry's agent-harness/ directory: pip install -e ..
4. Cookies: exported from a logged-in gemini.google.com browser tab. The full Google session-cookie family is required for image generation; chat-only flows work with just __Secure-1PSID (+ optionally __Secure-1PSIDTS).

Resolution order: --cookies-json <path> > $GEMINI_COOKIES_JSON > $GEMINI_COOKIE_SECURE_1PSID (+ $GEMINI_COOKIE_SECURE_1PSIDTS) > ~/.config/cli-anything-gemini/cookies.json.

Global flags

Flag	Purpose
--cookies-json <path>	Cookies JSON file (Cookie-Editor, EditThisCookie, flat dict, or { "cookies": ... } envelope).
--proxy <url>	HTTP/HTTPS proxy.
--output-dir <path>	Where image-generation results land. Defaults to ~/Pictures/gemini/ (if it exists) else ./gemini-out/.
--default-model <id>	Override session default model. Use unspecified for the account default.
--timeout <secs>	Library timeout (default 450).
--verbose	Verbose library logging to stderr.
--persist-cookies	Allow the library's auto-refresh task to write rotated __Secure-1PSIDTS back to the cookies file. Off by default.
--json	Emit a single JSON envelope on stdout per command.
--dry-run	Skip auto-save of session state.
--session-file <path>	Override session JSON path.

Command groups

auth

• auth status — initialize a client and probe account status (read-only).
• auth show-cookies — show resolved cookies with last-4-char fingerprint only (safe to log).

models

• models list — list gemini_webapi.constants.Model enum entries with advanced_only flag (no network).

chat

• chat ask <prompt> [--model M] [--file F]… — one-shot prompt. Returns text, cid, rid, rcid, candidates, image_count. Updates active_chat.cid so subsequent chat reply reuses it.
• chat reply <prompt> [--cid C] [--model M] — resume the active chat (or specified --cid) and send a follow-up.
• chat list — recent chats with cid, title, time.
• chat read <cid> [--limit N] — fetch turns of a chat.
• chat delete <cid> — delete a chat by id; clears active_chat if it matches.

image

• image generate <prompt> [--model M] [--output-dir D] [--filename-prefix P] [--full-size/--preview-size] [--max-images N] — issues an image-gen prompt and downloads up to N returned GeneratedImages to disk. --full-size (default) routes through the library's RPC for 2048 px; --preview-size uses the 1024 px preview URL.

session

• session info — show current state (id, paths, active chat, history length, cookie source).
• session history [--limit N] — recent history entries.
• session clear — wipe active chat and history, generate a fresh session id.

repl

Run with no subcommand:

cli-anything-gemini

REPL shorthands: ask <prompt>, reply <prompt>, gen <prompt> (image), list, read <cid>, delete <cid>, models, auth, session, clear, :json (toggle), :help, :q.

Agent-facing JSON envelope

Every command supports --json. Success envelope:

{
  "ok": true,
  "command": "image.generate",
  "result": { /* command-specific payload */ },
  "meta": { "elapsed_ms": 9123 }
}

Error envelope:

{
  "ok": false,
  "command": "image.generate",
  "error": {
    "type": "UsageLimitExceeded",
    "message": "Daily quota exceeded.",
    "retriable": false
  }
}

error.type values to handle: AuthError, AuthMissing, BackendImportError, CookieError, TimeoutError, TemporarilyBlocked, UsageLimitExceeded, ModelInvalid, ImageGenerationError, APIError, GeminiError. retriable=true indicates the agent may retry after backoff (TimeoutError, TemporarilyBlocked).

Realistic examples

One-shot question with JSON output

cli-anything-gemini --json chat ask "Summarise the abstract of arxiv:2305.08322 in two sentences."

{
  "ok": true,
  "command": "chat.ask",
  "result": {
    "text": "…",
    "cid": "c_abc123…",
    "rid": "r_def…",
    "rcid": "",
    "candidates": 1,
    "image_count": 0,
    "model": "unspecified"
  },
  "meta": { "elapsed_ms": 5210 }
}

Image generation pipeline

cli-anything-gemini --json \
  --output-dir ~/Pictures/gemini \
  image generate "A friendly red panda surfing at sunset, cinematic painterly style" \
  --max-images 2

{
  "ok": true,
  "command": "image.generate",
  "result": {
    "prompt": "A friendly red panda surfing at sunset, cinematic painterly style",
    "model": "unspecified",
    "cid": "c_…",
    "rid": "r_…",
    "image_count": 2,
    "images": [
      { "path": "/Users/.../20260517T172000Z_a-friendly-red-panda-surfing-at_00.png", "size": 1234567, "kind": "GeneratedImage" },
      { "path": ".../_01.png", "size": 1198765, "kind": "GeneratedImage" }
    ],
    "output_dir": "/Users/.../Pictures/gemini",
    "text": ""
  },
  "meta": { "elapsed_ms": 9123 }
}

Agents should treat result.images[i].path as authoritative (absolute paths on disk) and inspect size for sanity (> 5 KB is a reasonable lower bound for a real PNG).

Multi-step chat with auto-resume

cli-anything-gemini --json chat ask "What is the kelvin temperature of the surface of the sun?"
cli-anything-gemini --json chat reply "Now give me the equivalent in Celsius."
cli-anything-gemini --json session info

The CLI persists active_chat.cid so the second invocation resumes the same conversation without the agent needing to track cid itself.

Failure modes worth knowing

Symptom	Likely cause	Remediation
AuthError on first call	Expired or incomplete cookies	Re-export from browser; verify auth status.
chat ask works, image generate returns 0 images and text "Are you signed in?"	Cookie set is missing image-gen-only cookies (HSID/SSID/SAPISID/…)	Export full cookie family; do not hand-pick just PSID/PSIDTS.
UsageLimitExceeded	Hit daily quota on the underlying Google account	Wait for reset.
TemporarilyBlocked	Gemini issued 429 / IP-level block	Back off, retry with --proxy.
ModelInvalid	Tried a model the account doesn't have access to	Use models list; pick one with advanced_only: false unless you're on a Pro/Ultra plan.

Preview support

This harness does not implement the preview command group. Gemini-API has no meaningful intermediate visual state — image generation already produces final assets. Per HARNESS norm, we do not invent a fake preview.

License

AGPL-3.0 (inherited from the upstream library).