gflow-cli 0.17.0

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, plus gflow video t2v/i2v/r2v, all ship today)
• Reuse a subject across shots — gflow character create mints a Flow Character (face + body reference) so the same person appears consistently from generation to generation
• 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
# or mint a reusable Character (face + body reference):
gflow character create --project <id> --name "Aria" --face-prompt "..." --body-prompt "..."

Outputs land under $GFLOW_CLI_OUTPUT_DIR unless GFLOW_CLI_STORAGE_URI sends generated assets to S3, MinIO, or Google Cloud Storage. 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).

▶ More demos — split-screen (terminal command + Flow generating, side-by-side) and other formats: docs/DEMOS.md.

Documentation

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

Topic	Read
🎯 Getting started	User Guide · Usage · Configuration
Storage & catalog	External Storage · Data Layer
🎭 Characters	Characters — reusable subjects (gflow character)
🔐 Auth & sessions	Authentication · Known issues
🏗️ Internals	Architecture · Security · Debugging
📦 Releases	Changelog · Roadmap · 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) live under src/gflow_cli/api/transports/experimental/ — they are importable for research but not on the production critical path.

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.12.0 — alpha. Three new capabilities. gflow character mints reusable, project-scoped Flow Character entities — a named subject with reference images, an optional voice, and an optional personality — so the same subject stays consistent across generations (create / list / show / voices, #145). gflow scene composes ordered clips into a scene and renders a credit-free, server-side extended video (no local ffmpeg). gflow video chain links last-frame image-to-video clips from a JSONL manifest into one continuous sequence. This release also fixes create-project generation when Flow surfaces Agent mode as a docked chat panel. Baseline: Image (T2I / I2I / upload) + Video T2V / I2V / R2V live end-to-end on ui_automation, with a video --model picker (5 Veo models) + --duration / --count (v0.11.0 repaired gflow video i2v, issue #125, and hardened image-model selection for non-English Flow UIs, #94; v0.10.0 added --json across every generation command, a gflow models catalog, per-model reference caps, persisted profile identity, external S3 / MinIO / GCS storage, and gflow data prune). Only video batch (manifest runner) is still queued for Phase B — use a shell for-loop until then (USAGE). Full milestone history → docs/PROJECT_STATUS.md. Changelog → CHANGELOG.md. Where the project is heading → ROADMAP.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.

---

Stats

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