gflow-cli

gflow-cli

Google Flow 向けの Python CLI および MCP サーバーです。ターミナルから Veo（画像から動画、テキストから動画）と Imagen（テキストから画像）を操作できます。スクリプト化、バッチ処理、パイプラインに対応しています。

⚠️ インストール前にお読みください。 gflow-cli は アルファ版であり、リバースエンジニアリングによって開発されています。Google とは提携していません。 ご自身の Google Flow セッションで画面表示ありのブラウザーを操作するため、ご自身のアカウントに伴うリスクとしてお考えください。自動化は Google の利用規約の対象となり、エンドポイントや UI は予告なく変更される場合があります。Flow を利用できる すべての Google アカウントで動作し、生成のたびにアカウントの Flow クレジットが消費されます。詳しくは DISCLAIMER をお読みください。

🛡️ 「アカウントに警告が付く可能性はありますか？」 誠実かつ具体的な回答として、目立たない動作を維持するためにツールが行うこと（実際の Chrome を画面表示ありで使用、操作タイミングをランダム化、送信ペースを調整）、意図的に行わないこと（プロキシなし、フィンガープリント偽装なし、自動化を隠すことなし）、調整可能な項目、そして保証できないことについては、docs/ACCOUNT_SAFETY.md をご覧ください。

💳 失敗した場合のコスト。 クレジットが消費されるのは Veo の 動画 生成のみです。画像と構成操作は無料なので、ほとんどの不具合によるコストはかかりません。実行中に Flow の UI が変わった場合、CLI は再送信せず、異なる終了コード（例：セレクターの変更なら exit 23）で即座に明確なエラーを返します。また、バッチ項目は送信前にローカルへ記録されるため、実行が壊れて古い状態のままクレジットを消費してしまうことはありません。現在のリスクリストは KNOWN_ISSUES をご覧ください。

🌐 現在は画面表示ありのブラウザーを使用します。 Google の認証と reCAPTCHA の確認に対応するため、gflow は永続化された Playwright Chromium プロファイルを通じて Flow を操作します。ご協力いただける点については、Architecture セクションをご覧ください。

gflow-cli を使う理由

Flow を利用できる Google アカウントと Veo クレジットがあり、実際のバッチ処理を行うなら、gflow-cli が役立ちます。

• バッチ生成。 シェルからプロンプトを直接ループできます：for p in $(cat prompts.txt); do gflow image t2i "$p"; done。画像のバッチ処理に加え、gflow video t2v／i2v／r2v はすべて今すぐ利用でき、gflow video extend を使えば、既存のクリップを Flow の 8 秒制限を超えて延長できます。
• 一貫性のある被写体。 gflow character create で Flow Character（顔と体の参照）を作成すると、生成ごとに同じ人物を登場させられます。
• プロンプトツール。 --tool creative-director は、生成前に簡潔なプロンプトを生き生きとした表現に書き換えます（Google の 5 要素の構成）。どのコマンドでも使えます。My Tools で独自のツールを利用することもできます。
• パイプライン。 Veo をコンテンツ自動化、AI 動画スタック、バッチ実験に組み込めます。
• ターミナル中心。 gflow auth login を一度実行すれば、あとはシェル内で完結します。ダイアログをクリックして操作する必要はありません。期限切れのセッションは gflow auth renew でヘッドレスに更新されます。

同じ Veo と Imagen のモデル、同じ品質、ご自身の Google アカウントへの同じ課金を、プログラムから利用できます。

60 秒で始める

# 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
# later: `gflow update` upgrades in place (every command shows a banner when a newer release is out)

# 2 · Authenticate (one-time, opens a real Chrome window)
# Behind a proxy (e.g. Clash)? Set GFLOW_CLI_BROWSER_PROXY=http://127.0.0.1:7897 first (docs/CONFIGURATION.md)
gflow auth login --browser chrome

# Check the session (spends nothing)
gflow auth status
gflow credits user          # Veo credit balance (opens Flow in the browser; spends nothing)

# 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 "..."

出力は $GFLOW_CLI_OUTPUT_DIR に保存されます。また、GFLOW_CLI_STORAGE_URI を使って、S3、MinIO、Google Cloud Storage に保存することもできます。Chromium の起動中は最初の呼び出しに 30～90 秒かかりますが、以降の呼び出しでは起動済みのセッションが再利用されます。

なぜ --browser chrome なのですか？ プロファイルを実際の Chrome プロファイルとしてマークする戦略はこれだけであり、以降の生成処理では、そのプロファイルが開かれます。デフォルトの auto は Chrome がインストールされている場合にこれを選択します。詳しくは docs/AUTHENTICATION.md をご覧ください。

ローカルのチェックアウトからインストールしていますか？ uv tool install <path> は uv.lock を無視し、pyproject.toml の範囲指定から依存関係を解決するため、このプロジェクトで一度もテストされていない Playwright のビルドがインストールされることがあります。Playwright にはブラウザードライバーが含まれており、テストされていないマイナーバージョンによって生成処理が気付かないうちに停止するおそれがあります。ロックされたバージョンを明示してください：

uv tool install --force --with playwright==1.59.0 .

PyPI からのインストール（uv tool install gflow-cli）には影響しません。公開されている範囲指定には上限が設定されています。実際にインストールされているバージョンは、uv tool run --from gflow-cli python -c "import importlib.metadata as m; print(m.version('playwright'))" で確認できます。

トラブルシューティングや複数アカウントの設定も含む、10 分間の詳しいガイドについては、USER_GUIDE: Journey 1 をご覧ください。

使用例

コマンドを実行するだけで、Flow の出力が得られます。左：gflow image t2i でライブラリにフォトリアリスティックなシーンを生成。右：フレーム間の変換。

デモ

ログイン済みの Flow プロファイルに対して、gflow image t2i "..." --aspect 9:16 --model nano2 を 1 回実行します。ターミナルには実行時の structlog の JSON がストリーミングされ、その後、保存された PNG の一覧が表示されます。Chromium がバックグラウンドで Flow エディターを目立たないように操作します。

scripts/record_demo.ps1（Windows、OBS、ffmpeg、gifski）で録画を再現できます。左右分割表示を含む、その他の形式については docs/DEMOS.md をご覧ください。

ドキュメント

docs/INDEX.md は主要な案内ページです。クイックリンク：

トピック	参照先
🎯 はじめに	ユーザーガイド · 使用方法 · 設定
ストレージとカタログ	外部ストレージ · データレイヤー
🎭 キャラクター	キャラクター、再利用可能な被写体（gflow character）
🤖 エージェント機能と自動化	指示（gflow instructions、永続的なブリーフカード） · 動画（gflow movie、複数シーンのマニフェスト） · ツール（--tool、プロンプトの書き換え） · MCP サーバー（gflow mcp run / gflow serve）
🔐 認証とセッション	認証 · 既知の問題
📣 インストール元	マーケットプレイス（各チャンネルと、それぞれが実際に提供するもの） · コンテナー（イメージは内容を調査できますが、生成はできない理由）
🏗️ 内部構造	アーキテクチャ · セキュリティ · デバッグ
📦 リリース	変更履歴 · ロードマップ · リリース手順 · プロジェクトのステータス
🤝 コントリビューション	貢献方法 · 開発 · GitHub ワークフロー

AI エージェントと LLM 向け

gflow-cli には、エージェント用のエントリーポイントが 4 つあります。お使いのツールが最初に読み込むものを選んでください。

ファイル	対象	ツール
AGENTS.md	汎用コーディングエージェント仕様	Cursor · Codex · Aider · Antigravity · Jules · Devin · Windsurf · Zed · Warp · opencode · Copilot
CLAUDE.md	Claude Code が自動読み込みするメモリ	Claude Code
llms.txt	LLM が読み取れる概要（llmstxt.org 形式）	ChatGPT、Claude、Gemini に貼り付けてモデルを導入
skills/gflow-cli/SKILL.md	Claude Code Skill	~/.claude/skills/ にシンボリックリンクを作成

プラグインのインストール（Claude Code）

1 ステップで、gflow-cli と video-production のスキル、および MCP サーバーを利用できます。

/plugin marketplace add ffroliva/gflow-cli
/plugin install gflow@gflow-cli

プラグインは無効の状態で配布されます。Claude Code はプラグインを有効にすると、その MCP サーバーを自動的に起動します。独自の確認プロンプトは表示されません。また、このサーバーはユーザー自身の Google アカウントを使用するため、Veo の動画生成にはクレジットが消費されます。そのため、インストールしただけでは何も起動せず、有効化は意図的に行う操作です。画像とコンポジションは無料で、クレジットを消費するのは動画のみです。確実に防ぐには、gflow mcp run --no-spend でサーバーを自分で登録してください。この方法では、クレジットを消費するツールは一切登録されません。どのリビジョンが /plugin marketplace add で取得されるかなど、詳細は docs/MCP.md を参照してください。

Codex ユーザーの場合：codex plugin marketplace add . を実行し、続いて codex plugin add gflow@gflow-cli を実行してください。

1 行で任意のエージェントを導入できます。お使いのエージェントに、次の内容を貼り付けてください。

「AGENTS.md と docs/INDEX.md を読んでから、Flow のバッチ処理を手伝ってください。」

アーキテクチャと現在の制限事項

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

現在のトランスポート： ui_automation は永続的な Playwright Chromium プロファイルを通じて Flow を操作します。本番環境で安定しており、リリースごとにエンドツーエンドで検証されています（各リリースの LIVE_VERIFICATION_* 証跡ファイルを参照してください）。

2 つの Flow フロントエンド： Google はアカウントを labs.google から flow.google.com に移行しています（#639）。同じ製品ですが、ウィジェットツールキットと通信プロトコルが異なります（aisandbox-pa ではなく batchexecute）。移行済みドライバーは、テキストから動画、ローカルの開始フレームを使った画像から動画、ローカルファイルを使った参照画像から動画、テキストから画像、ローカルファイルを使った画像から画像、および単一セグメントの video extend に対応しています。画像生成では Nano Banana 2.1（nano2、#958）／2 Lite／Pro、該当ホストで実測した 5 種類のアスペクト比（16:9、4:3、1:1、3:4、9:16）、および 1～4 枚の生成数に対応しています。トランスポートの境界では、既存のプロジェクトが必要です。画像では @Name によるキャラクターの指定が可能です（#723）。エージェント専用コンポーザーが提供されているアカウント（#799）では、テキストから画像とテキストから動画のみを利用できます。画像の --ref <uuid> は、カタログに同じ --project 内のものとして記録されていれば、元の場所のまま参照されます（#995）。その他の UUID メディア参照、名前を伴わないエンティティ ID、指示、Imagen 4、および残りの機能マトリクスは、移植されるまで labs ドライバーを使います（GFLOW_CLI_FLOW_HOST については CONFIGURATION を参照してください）。

ブロックされているもの： 動画生成用の純粋な HTTP トランスポートです。動画のアップロードエンドポイントは、Chrome 以外のブラウザーでは HTTP 401 を返します。また、ヘッドレス環境では再現できない reCAPTCHA のトークン発行が必要です。これまでに試した 3 つの HTTP 戦略（evaluate_fetch、bearer、sapisidhash）は、調査用に src/gflow_cli/api/transports/experimental/ に置かれており、本番経路からは切り離されています。

協力いただけること： 実際の Chrome セッション以外から aisandbox-pa.googleapis.com を操作した経験がある方、またはここで使われている Google のボット対策の仕組みに詳しい方は、Issue を作成してください。REST トランスポートが実現すれば、サーバーレス環境へのデプロイ、真の水平並行処理、そしてプロジェクトの到達範囲を約 10 倍に広げることが可能になります。詳細：docs/ARCHITECTURE.md § Headed-browser dependency。

プロジェクトの状況

アルファ版。 画像（t2i、i2i、アップロード、アップスケール、バッチ）と動画（t2v、i2v、r2v、チェーン、延長、アップスケール）は、5 モデルの Veo ピッカーと --duration、--count を備え、ui_automation 上でエンドツーエンドに実行できます。単一の生成にとどまらず、gflow movie は複数シーンのマニフェストをレンダリングし、gflow instructions は永続的な Agent-Mode ブリーフカードを管理し（クレジット不要）、gflow character は再利用可能な被写体を扱い、gflow scene はクレジット不要のサーバー側スティッチングを行い、--tool はプロンプトを書き換えるツールを適用します。また、MCP サーバー（stdio の gflow mcp run／Streamable HTTP の gflow serve）は、CI で適用される CLI↔MCP の同等性契約に基づいて、主要機能を AI エージェントに提供します。

マイルストーンの全履歴は CHANGELOG.md にあります。プロジェクトの今後の方向性については、ROADMAP.md をご覧ください。

gflow-cli を支援

gflow-cli は、1 人で開発・保守しています。各リリースは実際の Google Flow で検証しており、そのために実際の AI クレジットを消費します。また、ユーザーがパイプラインで実行しているため、不具合はすぐに修正されます。スポンサーシップは、その両方を支えます。

仕事で gflow-cli を利用していますか？毎月の企業向けプランでは、ここにロゴを掲載できます。また、Silver 以上のプランでは、優先的に issue に対応します。すべてのプランと各プランの特典については、docs/SPONSORS.md をご覧ください。

フォークした gflow-cli にパッチを適用しましたか？ぜひ issue を作成するか、プルリクエストを送ってください。上流に取り込まれた修正は、すべての人に役立ちます。

殿堂

スポンサーはまだいません。最初のスポンサーになる — 公開されているすべてのスポンサーをここに掲載します。

ライセンスと法的事項

MIT License © 2026 Flavio Oliva（ffroliva）。MIT ライセンスの適用対象は gflow-cli のコードのみです。Flow、Veo のモデル出力、または Google のサービスに対する権利は付与されません。生成物には、Google 独自の利用規約（Labs 追加規約およびプラン固有のサブスクリプション規約）が適用されます。DISCLAIMER をご覧ください。

謝辞

• edge-tts。プライベートなクラウド API に対するコミュニティ SDK の設計の参考にしました。
• googleapis/python-genai。将来のプロバイダーリリースでエイリアスとして利用する可能性がある、公式の Veo SDK です。
• Keysight, Google Labs – Flow AI with Veo3: A Network Traffic Analysis。ルートパターンの検証に役立った、独立したトラフィックキャプチャです。

---

統計

スターの推移

gflow-cli が時間の節約に役立ったら、ぜひリポジトリに ⭐ を付けてください。プロジェクトを支援する最も手軽な方法です。