ffroliva/gflow-cli

> Python CLI and MCP server for Google Flow. Drive Veo (image-to-video, text-to-video) and Imagen (text-to-image) from your terminal: scripted, batched, pipeline-ready.
> ⚠️ **Read this before you install.** gflow-cli is **alpha and reverse-engineered — not affiliated with Google**. It drives a headed browser on *your own* Google Flow session, so treat it as your own account risk: automation is subject to Google's ToS, and endpoints or UI can change without notice. It works with **any Google account** that has Flow access, and every generation bills against your account's Flow credit allowance. Read the full DISCLAIMER.
>
> 🛡️ **"Will this get my account flagged?"** The honest, specific answer — what the tool does to stay unremarkable (headed real Chrome, randomised interaction timing, paced submissions), what it deliberately does **not** do (no proxies, no fingerprint spoofing, no pretending it isn't automation), what you can tune, and what we cannot promise — is in docs/ACCOUNT_SAFETY.md.
>
> 💳 **What failure costs you.** Credits are only spent on Veo *video* generation — images and composition ops are free, so most breakage costs nothing. When Flow's UI drifts mid-run, the CLI fails fast and loudly with distinct exit codes (e.g. selector drift = exit 23) instead of resubmitting, and batch items are recorded locally *before* submission so a broken run never silently burns credits on a stale state. See KNOWN_ISSUES for the current risk list.
>
> 🌐 **Headed browser today.** gflow drives Flow through a persistent Playwright Chromium profile, because Google's auth and reCAPTCHA gates require it. The Architecture section shows where you can help.
Why gflow-cli?
You have a Google account with Flow access, you have Veo credits, and you run real batch work. gflow-cli gives you:
- **Batch generation.** Loop prompts straight from the shell: for p in $(cat prompts.txt); do gflow image t2i "$p"; done. Image batching plus gflow video t2v / i2v / r2v all ship today, and gflow video extend continues an existing clip past Flow's 8s ceiling.
- **Consistent subjects.** gflow character create mints a Flow Character (face and body reference) so the same person appears from one generation to the next.
- **Prompt tools.** --tool creative-director rewrites a terse prompt into a vivid one (Google's 5-component formula) before generating — on any command. Bring your own with My Tools.
- **Pipelines.** Wire Veo into your content automation, AI-video stack, or batch experiments.
- **Terminal-native.** After one gflow auth login, you stay in the shell. No clicking through dialogs.
Same Veo and Imagen models, same quality, same billing against your own Google account, now programmatic.
60-second quick start
Outputs land under $GFLOW_CLI_OUTPUT_DIR, or you can route them to S3, MinIO, or Google Cloud Storage with GFLOW_CLI_STORAGE_URI. The first call takes 30 to 90 seconds while Chromium warms up; later calls reuse the warm session.
> **Why --browser chrome?** It is the only strategy that marks the profile as a real-Chrome profile, which is what later generation runs open it with. The default auto picks it whenever Chrome is installed — see docs/AUTHENTICATION.md.
> **Installing from a local checkout?** uv tool install **ignores uv.lock** and resolves dependencies from the pyproject.toml ranges, so it can hand you a Playwright build this project has never tested. Playwright ships the browser driver, and an untested minor can wedge a generation silently. Carry the locked version explicitly:
>
>
>
> Installing from PyPI (uv tool install gflow-cli) is unaffected — the published range is upper-bounded. Check what you actually have with uv tool run --from gflow-cli python -c "import importlib.metadata as m; print(m.version('playwright'))".