# gflow-cli

> Unofficial Python CLI for Google Flow — drives Veo (image-to-video, text-to-video, reference-to-video) and 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 only today, `--project` required there, everything else exits 36 (non-retryable); `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 (video has only a classic driver, so `auto` ≡ `classic`; 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); 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 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 --output` 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 `--output` renders to one file; 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). Keeps a local SQLite catalog of every generation, queryable via `gflow data list {projects,images,videos,profiles}`. 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] [--json]` upgrades in place through the installer that put it here (uv tool / pipx / pip; source installs refused, exit 11); `gflow doctor` is the read-only pre-flight diagnostic (exit 33 = findings present). MIT licensed, not affiliated with Google.

This file is forward-staged for a future docs site at https://ffroliva.github.io/gflow-cli/llms.txt and is also usable today by LLM agents that read the repo directly.

## 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, manifest format, 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, where secrets live, automatic-vs-sensitive incident-artifact tiers and the no-upload guarantee, HAR/traceback opt-in risks, local data-layer redaction.
- [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.
- [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 tools, CI-enforced CLI↔MCP parity.
- [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.
