gflow-cli 0.8.1

Unofficial CLI for Google Flow — drive Veo image-to-video generations from the terminal.

gflow-cli

Unofficial Python CLI for Google Flow. Drive Veo (image-to-video, text-to-video) and Imagen (text-to-image) generations from your terminal — scripted, batched, pipeline-friendly.

⚠️ Unofficial. Reverse-engineered. Not affiliated with Google. Endpoints can change at any time. Full DISCLAIMER.

🌐 Headed-browser today. gflow drives Flow via a persistent Playwright Chromium profile — Google's auth + reCAPTCHA gates currently require it. See Architecture & current limitations for the contributor opportunity.

Why gflow-cli?

For Google AI Ultra / Pro subscribers with Veo credits and batch workloads:

• Burn credits efficiently — for p in $(cat prompts.txt); do gflow image t2i "$p"; done (image batching ships today; gflow video i2v lands in Phase B)
• Build pipelines — wire Veo into your content automation, AI video stack, or batch experiments
• Stay in the terminal — no Chromium UI, no clicking through dialogs (after a one-time gflow auth login)

Same Veo + Imagen models, same quality, same Ultra/Pro billing — programmatic.

60-second quick start

# 1 · Install (uv recommended — also: pip install gflow-cli)
uv tool install gflow-cli
uv tool run --from gflow-cli playwright install chromium     # one-time, ~150 MB

# 2 · Authenticate (one-time, opens a real Chrome window)
gflow auth login --browser chrome

# 3 · Generate
gflow image t2i "a hot air balloon over Tokyo at sunrise"
# or:
gflow video t2v "Slow cinematic push-in on a sunlit forest clearing" --aspect 16:9

Outputs land under ./out/ (or $GFLOW_CLI_OUTPUT_DIR). First call is ~30–90 s while Chromium warms; subsequent calls reuse the warm session.

Why --browser chrome? Google rejects Playwright's bundled Chromium. The CLI fails fast with a friendly error (AuthBrowserRejectedError, exit code 14) if you pick anything else.

In-depth quick start

See USER_GUIDE — Journey 1: First-time setup for the 10-minute walkthrough with troubleshooting, multi-account setup, and the structured-log primer.

Demo

A single gflow image t2i "..." --aspect 9:16 --model nano2 call against a logged-in Pro/Ultra profile. Terminal shows the streaming structlog JSON for the run, the final ls of the written PNG, and nothing else — Chromium drives the Flow editor silently in the background.

Reproduce the recording: scripts/record_demo.ps1 (Windows + OBS + ffmpeg + gifski).

Documentation

docs/INDEX.md is the master routing layer. Quick links:

Topic	Read
🎯 Getting started	User Guide · Usage · Configuration
🔐 Auth & sessions	Authentication · Known issues
🏗️ Internals	Architecture · Security · Debugging
📦 Releases	Changelog · Release protocol · Project status
🤝 Contributing	Contributing · Development · GitHub workflow

For AI agents & LLMs

gflow-cli ships three agent entry points — pick the one your tool reads first.

File	Audience	Tools
AGENTS.md	Universal coding-agent spec	Cursor · Codex · Aider · Gemini CLI · Jules · Devin · Windsurf · Zed · Warp · opencode · Copilot · 60k+ repos
CLAUDE.md	Claude Code's auto-loaded memory	Claude Code
llms.txt	LLM-readable summary (llmstxt.org format)	Paste into ChatGPT / Claude / Gemini to onboard the model
skills/gflow-cli/SKILL.md	Claude Code Skill	Symlink into ~/.claude/skills/

Onboarding any agent in one line: paste this into your agent of choice —

"Read AGENTS.md and docs/INDEX.md, then help me with my Flow batch."

Architecture & current limitations

gflow CLI  →  Provider (interchangeable)  →  Flow (ui_automation) / Mock (tests) / [planned: Official Veo]
                                              ↓
                                      Playwright Chromium (headed login, headless after)
                                              ↓
                              aisandbox-pa.googleapis.com  (Google's private Flow API)

Current transport: ui_automation — drives Flow via a persistent Playwright Chromium profile. Production-stable, end-to-end verified per release (see LIVE_VERIFICATION_* per-release evidence files).

What's blocked: A pure HTTP transport for video generation. The video upload endpoint returns HTTP 401 under non-Chrome browsers + a reCAPTCHA mint we cannot reproduce headlessly. Three earlier HTTP strategies (evaluate_fetch / bearer / sapisidhash) are named in the codebase history; the actual transport modules have not yet been extracted into a subpackage.

How you can help: If you have successfully driven aisandbox-pa.googleapis.com from outside a real Chrome session — or have insight into Google's anti-bot stack here — please open an issue. A working REST transport would unlock serverless deployments, true horizontal concurrency, and roughly 10× the project's reach. Details: docs/ARCHITECTURE.md § Headed-browser dependency.

Project status

v0.8.1 — alpha (docs refresh). Image (T2I / I2I / upload) + Video T2V live end-to-end on ui_automation. Video I2V + batch are queued for Phase B. Full milestone history → docs/PROJECT_STATUS.md. Changelog → CHANGELOG.md.

License & legal

MIT License © 2026 Flavio Oliva (ffroliva). The MIT license covers gflow-cli's code only — it does not grant rights to Flow, Veo model output, or any Google service. Google's own terms (Labs Additional Terms, Ultra/Pro subscription terms) govern your generations. See DISCLAIMER.

Acknowledgements

• edge-tts — design inspiration for community SDKs over private cloud APIs.
• googleapis/python-genai — the official Veo SDK that a future provider release may alias.
• Keysight — Google Labs – Flow AI with Veo3: A Network Traffic Analysis — independent capture that helped validate the captured route patterns.

---

If gflow-cli saves you time, please ⭐ the repo — it is the cheapest way to support the project.