# gflow-cli

> gflow-cli is an open-source (MIT) MCP server and Python CLI that automates Google Flow: it generates Veo 3.1 and Omni video and Nano Banana and Imagen images from Claude Code, Claude Desktop, Cursor, Codex, VS Code or the terminal, billed to the user's own Google Flow credits. Install with `uv tool install gflow-cli`, sign in once with `gflow auth login --browser chrome`. Independent project, not affiliated with Google.

## Key facts

- Two surfaces, one package: the `gflow` CLI (70+ commands, typed exit codes, `gflow --help --json` for the whole tree) and an MCP server with 27 tools (`gflow mcp run` over stdio, `gflow serve` for Streamable HTTP at `/mcp`); CLI-to-MCP parity is enforced in CI.
- Listed in the official MCP Registry as `io.github.ffroliva/gflow-cli`; install from PyPI (`gflow-cli`); macOS, Windows and Linux; Python 3.11+.
- Connect a client: Claude Code plugin (`/plugin marketplace add ffroliva/gflow-cli`, then `/plugin install gflow@gflow-cli`), `gflow mcp setup` (Claude Desktop), `gflow mcp setup --target cursor`, `gflow mcp setup --target vscode`, or any MCP client with command `uvx gflow-cli mcp run`.
- Video models: Veo 3.1 Lite, Fast and Quality (8 s); Omni Flash (10 s) and Omni 1.2 Flash (15 s), up to 7 reference images. Flow retires Veo 3.1 Fast, Veo 3.1 Quality and Omni Flash on 2026-12-05 (`retires_on` in `gflow models --json`); use Veo 3.1 Lite or Omni 1.2 Flash. Image models: Nano Banana 2.1, Nano Banana Pro, Nano Banana 2 Lite, Imagen 4. `gflow models list` prints the current table.
- Video: text-, image- (with start and end frames) and reference-to-video; `video extend` past the 8 s limit; `video chain`; free server-side stitching with `scene create`; upscale to 1080p. Images: text- and image-to-image, 1-4 per call, upscale to 2K/4K.
- Consistency and pipelines: reusable Characters (`gflow character`, `@Name` mentions), JSON batch runs (`gflow run`), multi-scene films (`gflow movie run`), persistent Agent-Mode briefs (`gflow instructions`), prompt-rewriting tools (`--tool creative-director`).
- Spend safety: only video spends Flow credits (images count against a daily image quota); `gflow mcp run --no-spend` never registers the credit-spending tools; `--max-credits N` (or `GFLOW_CLI_MAX_CREDITS`) refuses a billed video run before submit when Flow's quote exceeds N (exit 45); every error carries `charged: yes|no|maybe` and a `next_action`; a billed request is never resent automatically.
- No API key: gflow-cli needs no Gemini or Vertex AI key; it uses the Google account's own Flow access and Flow credits.
- Compared with other Google Flow automation tools (README comparison table, sourced from each project's README on 2026-11-19 and 2026-11-20), it is the only one in that table that installs from PyPI and is listed in the official MCP Registry. kodelyx/flow-agent is also both a CLI and an MCP server (5 MCP tools against gflow-cli's 26), and it offers an OpenAI-compatible API and credit pooling across accounts, which gflow-cli does not. Features gflow-cli does not have yet are tracked in https://github.com/ffroliva/gflow-cli/issues/1367.
- Name: other projects also use the name gflow-cli, including Node.js packages on npm and JSR. This one is the Python package `gflow-cli` on PyPI, maintained at https://github.com/ffroliva/gflow-cli.
- Maturity: beta, 130+ releases since May 2026, every release since v0.54.0 live-verified against real Google Flow.
- Not supported: browser-free (serverless) video generation, because every billed submit needs a reCAPTCHA Enterprise token minted in a live page.

## Details

Open-source MCP server and Python CLI for Google Flow — drives Veo 3.1 and Omni (text-to-video, image-to-video, reference-to-video) and Nano Banana / Imagen (text-to-image) generations from the terminal by reverse-engineering Flow's private REST API at aisandbox-pa.googleapis.com — and, for accounts Google has moved to flow.google.com (#639), that frontend's batchexecute wire: text-to-video, image-to-video from a local `--initial-frame` (optionally a local `--end-frame` (#639), no UUID frame), reference-to-video from local `--ref` files, text-to-image, image-to-image from local files, and a single-segment `video extend` (Flow's own Extend control; chains, `--scene`, `--seed` and a foreign `--aspect` exit 36), `character list` / `show`, and `character create --image` / `--body-image` (built from local images, no credits) today, `--project` required there; image prompts may tag a character by name (`@Name`, #723) and reference-to-video takes a character by id plus its name (`--reference-entity` + `--reference-entity-name`, #723); an agent-only composer (#799) takes text-to-image and text-to-video only, other forms exit 36; references by UUID (except an image `--ref <uuid>` the catalog records in the same `--project`, #995), an entity id without a name, characters on t2v/i2v, Agent instructions, Imagen 4 and image batch exit 36 (non-retryable; all five aspect ratios, 3:4 included, are served since #864); `GFLOW_CLI_FLOW_HOST` = `auto` (default: flow.google.com for every request it can serve) | `flow.google.com` | `labs.google` (kill switch). Works with any Google account that has Flow access (a paid AI Pro/Ultra plan only affects credit allowances and tier-gated features such as 4K upscale). Uses Playwright Chromium under the hood (one-time real-Chrome auth, then a persistent Chrome session driven via ui_automation). Production-stable for image generation and video T2V/I2V/R2V with `--model`/`--duration`/`--count` pickers and a `--ui-mode` UI-arm gate (labs video has only a classic driver, so `auto` ≡ `classic`, and an agent-only flow.google.com composer is routed to its own driver before this gate; an explicit `--ui-mode agentic` is refused with exit 2 before any browser work, and an unreachable classic editor aborts pre-submit with exit 28 and zero credits); `gflow image generate` / `gflow video generate` are bridge verbs that resolve to t2i/i2i or t2v/i2v/r2v from the inputs and then run that verb unchanged (`--out-file PATH` only, no `-o PATH`; `--json` adds `"mode"`; a frame plus `--ref` is exit 2, #1193); there is no `batch` video subcommand — the nonfunctional stub was removed in v0.41.0; loop `gflow video t2v`/`i2v` from the shell for multi-clip runs. Also ships `gflow auth renew` (refreshes saved sessions headlessly), `gflow character` (create/list/show/rm/voices — reusable, project-scoped Flow Character entities for consistent subjects across generations), `gflow scene` (create/show — compose ordered clips into a scene; `create --out-file` renders a credit-free server-side extended video), `gflow video chain` (last-frame I2V chaining from a JSONL manifest), and `gflow video extend` (continues an existing clip by chained 8s Veo extensions, seeded server-side from the source clip rather than an extracted still, landing as a Scene that `--out-file` renders to one file on labs.google; on flow.google.com it runs one segment and `--out-file` saves the clip Flow returns (with the Omni key, measured 2026-11-08, Flow grows the source clip in place by ~4s); note a segment carries ~7s of content though Flow bills 8s, so multi-segment renders hold a frozen second at each internal seam — see KNOWN_ISSUES). `gflow run --config <batch.json>` runs a JSON image batch whose rows may generate from an earlier row (`"ref": "batch:N"`, referenced in place, no upload) or from a local image file (uploaded once per run); `gflow image batch` refuses any row ref. Keeps a local SQLite catalog of every generation, queryable via `gflow data list {projects,images,videos,profiles}`, and local usage statistics via `gflow data stats` (#1164); local usage counters in `<home>/telemetry.db` are inspectable via `gflow telemetry status|show` (strictly local, no upload). Ships an MCP server (`gflow mcp run` stdio, `gflow serve` Streamable HTTP) with generate/list/instructions tools, a credit-free non-interactive `gflow_auth_status` session probe to call before spending credits, and a `--no-spend` mode (or `GFLOW_MCP_NO_SPEND=1`) that never registers the credit-spending tools. Operational guards (v0.56.0): refuses to open a profile with an older bundled Chromium major than last wrote it (exit 11, protects the session store); `GFLOW_CLI_LEASE_WAIT_SECONDS=N` lets a second same-profile invocation wait for the lease instead of failing fast; a once-a-day stderr banner reports newer PyPI versions (`GFLOW_CLI_UPDATE_CHECK=0` silences it — do so when piping stderr into `jq`), and `gflow update [--check] [-v|--verbose] [--json]` upgrades in place through the installer that put it here (uv tool / pipx / pip; source installs refused, exit 11; a Windows pip install at 0.99.0 or older upgrades once by hand first, docs/USAGE.md#gflow-update); `gflow doctor` is the read-only pre-flight diagnostic (exit 33 = findings present). `gflow cancel <id> [--json]` aborts a queued job locally (the same abort as MCP `tasks/cancel`): a pending job, or one a worker claimed but has not submitted, becomes `cancelled` (exit 0, nothing charged; the worker stops before submitting); a job a gflow worker already submitted becomes `abandoned` and exits 22 with `cancel.server: no`, `charged: maybe`, `next_action: reconcile`, because Flow cannot cancel it (#1198). `gflow docs` makes the bundled documentation reachable from the terminal — `gflow docs` lists the topics, `gflow docs <topic>` prints one as raw Markdown, and `gflow docs --search <term>` returns the matching lines with their `docs/FILE.md:LINE` positions; the pages ship inside the wheel, so it needs no checkout, no network and no account. `gflow --help --json` (or `gflow <group> [<cmd>] --help --json`) prints the command tree as JSON — each command's path, params and `spends_credits` (true when it submits a new generation: video spends Veo credits, image the daily image quota) — for agents to discover commands without scraping help text (#1203). MIT licensed, not affiliated with Google.

`gflow capabilities [--json]` (and the MCP resource `capabilities://self`, the same document except on a no-spend server) declares, with no call to Flow, what gflow can drive: `yes`/`no`/`partial`/`unknown` per key (`generate.image`, `generate.video`, `submit.no_wait`, `status`, `wait`, `download`, `upload`, `abort.local`, `cancel.server`, `idempotent_submit`, `reconcile`, `credits.balance`), with a note on every `partial`; `cancel.server` and `idempotent_submit` are `no` (#1197, docs/CAPABILITIES.md).

`gflow models list|show` lists the image and video models gflow can drive, with aliases, durations and reference caps (no call to Flow). Every error envelope (CLI `--json`, MCP) carries `charged` (`yes`/`no`/`maybe`) and `next_action` (`retry`, `reauth`, `reconcile`, ...); a billed request or an image submit is sent once and never resent, so `reconcile` means check the project in Flow first. Details: [docs/ERRORS.md](docs/ERRORS.md), [docs/CAPABILITIES.md](docs/CAPABILITIES.md).

Credit inspection is exposed through `gflow credits user|list` and the `gflow_get_credits` MCP
tool. It reads the balance flow.google.com itself loads (the number in Flow's account menu,
#795): directly, with no browser, when Flow accepts the profile's saved session, otherwise in
the profile's browser (#1229; off by default on macOS, skipped while any proxy is configured,
and `GFLOW_CLI_WIRE_READS=0` always uses the browser); the tier fields are always null there. The balance funds Veo video generation; image generation uses
separate per-model daily quotas. Log in with `gflow auth login --browser chrome`: a bundled-
Chromium login (`--browser internal`, or `auto` without Chrome) works again (verified
on Windows; macOS not measured), but generation still needs a chrome profile (#1026).

This file is published at https://ffroliva.github.io/gflow-cli/llms.txt and in the repository root.

## Docs

- [README](https://github.com/ffroliva/gflow-cli/blob/main/README.md): Project overview, install, 60-second quick start.
- [User Guide](https://github.com/ffroliva/gflow-cli/blob/main/docs/USER_GUIDE.md): Task-oriented walkthroughs — first setup, batch video, multi-image, log forensics, recovery, multi-account.
- [Usage](https://github.com/ffroliva/gflow-cli/blob/main/docs/USAGE.md): Command-by-command reference, including `gflow credits user|list`, manifest format, and exit codes.
- [Architecture](https://github.com/ffroliva/gflow-cli/blob/main/docs/ARCHITECTURE.md): Provider abstraction, ui_automation transport, RFC 9457 error model.
- [Authentication](https://github.com/ffroliva/gflow-cli/blob/main/docs/AUTHENTICATION.md): One-time Chrome login, session storage, multi-account.
- [Debugging](https://github.com/ffroliva/gflow-cli/blob/main/docs/DEBUGGING.md): Where to look when something breaks — automatic private incident bundles (triggers, layout, review-before-sharing, HAR escalation), selector-drift diagnosis, structured log keys, WAF cadence.
- [Security](https://github.com/ffroliva/gflow-cli/blob/main/docs/SECURITY.md): Threat model, secret storage, privacy controls, usage uploads, and local data-layer redaction.
- [Usage data and privacy notice](https://github.com/ffroliva/gflow-cli/blob/main/docs/TELEMETRY.md): Weekly report fields, retention, uploads, and opt-out controls.
- [Configuration](https://github.com/ffroliva/gflow-cli/blob/main/docs/CONFIGURATION.md): All env vars, output paths, precedence.
- [External Storage](https://github.com/ffroliva/gflow-cli/blob/main/docs/EXTERNAL_STORAGE.md): S3, MinIO, and Google Cloud Storage output setup.
- [Known Issues](https://github.com/ffroliva/gflow-cli/blob/main/KNOWN_ISSUES.md): Open + mitigated issues with workarounds.
- [Data Layer](https://github.com/ffroliva/gflow-cli/blob/main/docs/DATA_LAYER.md): Local SQLite catalog schema and the `gflow data list` query CLI.
- [Telemetry](https://github.com/ffroliva/gflow-cli/blob/main/docs/TELEMETRY.md): Usage data and privacy notice: local counters, the weekly report sent after a one-time notice (no identifier), EU/EEA consent, kill switches, and the `gflow telemetry on|off|status|show` CLI.
- [Characters](https://github.com/ffroliva/gflow-cli/blob/main/docs/CHARACTER.md): The `gflow character` command group — reusable, project-scoped Flow Character entities (reference images, optional voice, optional personality).
- [Instructions](https://github.com/ffroliva/gflow-cli/blob/main/docs/INSTRUCTIONS.md): The `gflow instructions` command group — persistent Agent-Mode brief cards (credits-free CRUD, TOML/JSON full-sync via `apply`, image/character references).
- [Movie](https://github.com/ffroliva/gflow-cli/blob/main/docs/MOVIE.md): The `gflow movie` command group — multi-scene `movie.toml` manifests with styles, per-scene instructions brief-sync, and resume.
- [Tools](https://github.com/ffroliva/gflow-cli/blob/main/docs/TOOLS.md): The tools framework — `--tool creative-director` prompt rewriting on any generation command, `gflow tools list/show/run`, user-authored TOML tools.
- [MCP](https://github.com/ffroliva/gflow-cli/blob/main/docs/MCP.md): The MCP server — `gflow mcp run` (stdio) / `gflow mcp setup` (writes the client config for Claude Desktop / Cursor / VS Code) / `gflow serve` (Streamable HTTP), generation + instructions + direct narration tools, CI-enforced CLI↔MCP parity; MCP tools write only inside `GFLOW_CLI_OUTPUT_DIR` and take `profile` as a plain name.
- [Roadmap](https://github.com/ffroliva/gflow-cli/blob/main/ROADMAP.md): Themed milestones through v1.0.

## For AI coding agents

- [AGENTS.md](https://github.com/ffroliva/gflow-cli/blob/main/AGENTS.md): Universal coding-agent spec (Cursor, Codex, Aider, Antigravity, Claude Code, etc.).
- [CLAUDE.md](https://github.com/ffroliva/gflow-cli/blob/main/CLAUDE.md): Claude Code's auto-loaded memory hub.
- [docs/AGENT_GUIDE.md](https://github.com/ffroliva/gflow-cli/blob/main/docs/AGENT_GUIDE.md): Mandates and routing rules for agents.

## Optional

- [DISCLAIMER](https://github.com/ffroliva/gflow-cli/blob/main/DISCLAIMER.md): Legal scope and takedown policy.
- [CONTRIBUTING](https://github.com/ffroliva/gflow-cli/blob/main/CONTRIBUTING.md): TDD workflow, coverage targets.
- [Changelog](https://github.com/ffroliva/gflow-cli/blob/main/CHANGELOG.md): Version-by-version user-visible changes.
- [Release protocol](https://github.com/ffroliva/gflow-cli/blob/main/RELEASE.md): Signed-tag publishing flow.
