Metadata-Version: 2.5
Name: gnmyflow
Version: 0.3.1
Summary: GnmyFlow: a fast CLI and MCP server for Google Flow and Google Flow Music. Fork of StudioWright; unofficial and not affiliated with Google.
Project-URL: Repository, https://github.com/anggi-susanto/gnmyflow
Project-URL: Issues, https://github.com/anggi-susanto/gnmyflow/issues
Project-URL: Upstream, https://github.com/umutkocak/studiowright
Author: Umut Koçak
Maintainer: anggi-susanto
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: click>=8.5.0
Requires-Dist: filelock>=4.1.0
Requires-Dist: mcp[cli]>=2.3.0
Requires-Dist: pillow>=11.0
Requires-Dist: platformdirs>=4.12.4
Requires-Dist: playwright>=1.63.0
Description-Content-Type: text/markdown

<div align="center">

# GnmyFlow

**Google Flow and Google Flow Music, from your terminal and your AI agent.**

Images, video clips and songs made in your own signed-in Chrome, on your own subscription.<br>
No API keys. No cookie exports. No captcha solvers. No browser extension.

![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-3776AB?logo=python&logoColor=white)
![License: MIT](https://img.shields.io/badge/license-MIT-green)
![MCP server](https://img.shields.io/badge/MCP-server-6E56CF)
![Claude Code plugin](https://img.shields.io/badge/Claude%20Code-plugin-D97757)
![Tested on Windows 11](https://img.shields.io/badge/tested%20on-Windows%2011-0078D4)

</div>

> [!IMPORTANT]
> GnmyFlow is an unofficial fork of [StudioWright](https://github.com/umutkocak/studiowright), originally authored by Umut Koçak. It is not affiliated with, endorsed
> or sponsored by Google. It drives Flow's and Flow Music's web pages in **your** browser
> and spends **your** credits. Read the [disclaimer](#disclaimer) before you use it.

```bash
sw image "a lighthouse keeper with a teal coat, flat textured 2D" --aspect 16:9
sw video "he turns towards the sea" --start keeper.jpg --duration 4 --resolution 360p
sw music "moody indie folk, warm male vocal" --lyrics-file chorus.txt --length 1:00
```

## Contents

- [Showcase](#showcase)
- [Why GnmyFlow](#why-gnmyflow)
- [Features](#features)
- [Install](#install)
- [Quick start](#quick-start)
- [Use it from AI agents](#use-it-from-ai-agents)
- [Command reference](#command-reference)
- [Batch files](#batch-files)
- [Costs and safety](#costs-and-safety)
- [How it works](#how-it-works)
- [Troubleshooting](#troubleshooting)
- [Configuration](#configuration)
- [Development](#development)
- [Disclaimer](#disclaimer)

## Showcase

The showcase below was inherited from StudioWright and made with StudioWright, from one small batch file and two chat
messages.

```json
{"id": "keeper", "kind": "image", "prompt": "a lighthouse keeper with a teal coat, standing, flat textured 2D illustration", "refs": ["style.png"]}
{"id": "keeper-close", "kind": "image", "prompt": "close-up portrait of the same lighthouse keeper, flat textured 2D", "refs": ["keeper"]}
{"id": "keeper-clip", "kind": "video", "prompt": "the lighthouse keeper turns his head towards the sea, gentle wind", "start": "keeper", "resolution": "360p", "duration": 4}
```

<table>
<tr>
<td width="50%"><img src="docs/media/keeper.jpg" alt="A lighthouse keeper in a teal coat on a cliff at night"><br><sub><b>keeper</b> · Nano Banana 2.1 · style from a reference image · 22 s</sub></td>
<td width="50%"><img src="docs/media/keeper-closeup.jpg" alt="Close-up of the same lighthouse keeper"><br><sub><b>keeper-close</b> · the same character, by referring to the first job · 21 s</sub></td>
</tr>
<tr>
<td width="50%"><img src="docs/media/keeper-clip.gif" alt="The keeper turns towards the sea"><br><sub><b>keeper-clip</b> · Omni Flash, 4 s, start frame from the first job · 32 s · 4 credits</sub></td>
<td width="50%"><a href="docs/media/beacon-in-the-dark.mp4"><img src="docs/media/beacon-cover.jpg" alt="Cover art of the song Beacon in the Dark: a lighthouse in a storm"></a><br><sub><b>Beacon in the Dark</b> · written and sung by the Flow Music Producer · 37 s · 5 credits<br><a href="docs/media/beacon-in-the-dark.mp4">▶ listen (MP4)</a> · <a href="docs/media/beacon-in-the-dark.mp3">MP3</a></sub></td>
</tr>
</table>

The song took two chat turns:

```bash
sw music chat "Write a four-line chorus about a lighthouse keeper who waits for the ships."
sw music chat "Moody indie-folk please. Make the song now, about one minute long." --session <id from the first reply>
```

## Why GnmyFlow

Most ways to automate Google's media models need one of these: a paid API key, cookies
copied out of your browser, a captcha-solving service, an unpacked browser extension, or a
third-party relay that holds your session. GnmyFlow needs none of them.

| | Paid model APIs | Cookie-based wrappers | Hosted relays | **GnmyFlow** |
| --- | :---: | :---: | :---: | :---: |
| Uses the credits of your Flow / Flow Music plan | ✗ | ✓ | ✓ | **✓** |
| No API key or per-call billing | ✗ | ✓ | ✗ | **✓** |
| Your session never leaves your machine | ✓ | ✗ | ✗ | **✓** |
| No captcha solving or token forging | ✓ | ✗ | ? | **✓** |
| Every option of the web app | partial | partial | partial | **✓** |
| Images, video **and** music in one tool | ✗ | ✗ | partial | **✓** |

What makes it different:

- **It acts like you.** GnmyFlow types, clicks and chooses files in Flow's real pages,
  in a Chrome you signed in to yourself. It only *reads* the replies those pages receive,
  to learn ids and download links. It never forges, replays or alters a request.
- **One package, three front doors.** The same engine is a CLI (`sw`), an MCP server
  (`sw mcp`) and a Claude Code plugin.
- **Built for real production.** Price checks before you spend (`--dry-run`,
  `--max-credits`), resumable batch files that chain results, sized downloads (2K images,
  1080p/4K clips), pacing across processes, and a cooldown when Google asks for a break.
- **Fast on a warm tab.** About 20 s for an image, 30-60 s for a clip, 40 s for a song.

## Features

**Images (Google Flow)**
- Nano Banana 2.1 (default), Nano Banana Pro and Nano Banana 2 Lite.
- Aspect ratios 16:9, 4:3, 1:1, 3:4, 9:16; one to four images per call.
- Reference images from files or earlier results; each file is uploaded once per project
  and then reused by content.
- Downloads at Flow's own sizes: 1K (original), 2K (upscaled by Flow), 4K where the plan
  allows.

**Video (Google Flow)**
- Omni Flash (default), Veo 3.1 Lite, Fast and Quality.
- Text only, start frame, start and end frames, or ingredients (several reference images).
- Omni: 360p / 720p and 4, 6, 8 or 10 s. Aspect 16:9 or 9:16.
- Downloads at 720p, 1080p or 4K (upscaled by Flow), or as a GIF.
- `--dry-run` shows Flow's price without submitting; `--max-credits` refuses anything
  more expensive.

**Music (Google Flow Music)**
- Songs with your lyrics (any language) or instrumentals; Lyria 3.5 or Lyria 3 Pro;
  BPM, length (1:00-3:00), seed, title, and cover art from a file or a prompt.
- **Edit existing songs:** extend, cover in another style, replace a section, variation,
  trim.
- **Stems:** drums, bass, vocals and other, each as its own file.
- **Downloads:** WAV (48 kHz), M4A or MP3; vertical MP4 videos from Flow Music's
  templates.
- **The Producer agent:** chat with it to write lyrics, plan songs, remix your own audio
  or make AI music videos; songs it makes are saved automatically.
- **Your own audio:** upload a file and extend, cover or split it like any other song.

**Automation**
- CLI with `--json` output, an MCP server with 16 tools, and a Claude Code plugin with a
  skill.
- JSON Lines batch files that resume where they stopped and pass results between jobs.
- A job history (`sw jobs`) and a screenshot of the page whenever a job fails.

## Install

This fork is not published on PyPI yet. Install from the repository only after
the rename changes have been pushed. The plugin pin `v0.3.1` targets the first fork
release and will only work after that tag is published. The existing `v0.3.0` tag
predates the rename and must not be moved or reused for the fork release.

Requirements: Python 3.12+, [uv](https://docs.astral.sh/uv/), Google Chrome, and a Google
account with a Flow plan (images and video) and/or a Flow Music plan (music).

```bash
uv tool install git+https://github.com/anggi-susanto/gnmyflow
sw --version
```

The primary command is `gnmyflow`. Compatibility aliases `sw` and `studiowright`
run the same CLI. Do not install both forks into the same environment: they share
the `studiowright` Python namespace and legacy commands.

<details>
<summary>From a local checkout (for development)</summary>

```bash
git clone https://github.com/anggi-susanto/gnmyflow.git
cd gnmyflow
uv sync
uv tool install --python 3.13 -e .
```

</details>

### Updating

- **Plugin** (MCP server and skill): `claude plugin update gnmyflow@gnmyflow`, or in
  Claude Code `/plugin` → Installed → gnmyflow → Update now; then `/reload-plugins`.
  Each plugin version runs the GnmyFlow release of the same version. To update
  automatically, turn it on once: `/plugin` → Marketplaces → gnmyflow → Enable
  auto-update.
- **Command line**: `uv tool install --force git+https://github.com/anggi-susanto/gnmyflow@vX.Y.Z`
  with the release you want (see [Releases](https://github.com/anggi-susanto/gnmyflow/releases)).

## Quick start

**1. Sign in once.** Chrome opens on a profile that belongs to GnmyFlow only. Sign in
to Google, open Flow once, then close the window.

```bash
sw auth login
sw auth login --url https://www.flowmusic.app/    # only if you will make music
```

Run `sw stop` first if GnmyFlow's Chrome is already running.

**2. Make something.**

```bash
sw image "a red fox in the snow, flat 2D" --aspect 1:1
sw video "slow push-in on a quiet harbour at dawn" --model veo-lite --dry-run   # price only
sw music "calm documentary underscore, soft piano, warm strings" --bpm 80 --length 1:30
```

Files land in `Downloads/studiowright` (change it with `--out`), and each command prints
their paths. Add `--json` for ids, sizes, timings and credits.

**3. Keep Chrome in the background.** `sw window hide` moves the window off-screen. Never
minimize it: a minimized Chrome stops rendering and Flow stalls.

## Use it from AI agents

Every client below runs `gnmyflow mcp` over stdio; `sw mcp` remains compatible.
If a client cannot find `gnmyflow`, give it the full executable path.

Generating takes real time (an image ~20 s, a clip up to a few minutes), so give the
client a generous tool timeout where it has one.

### Claude Code plugin (recommended)

The plugin adds the MCP server and a skill that teaches Claude the options, prices and
safe habits.

```bash
claude plugin install gnmyflow --marketplace anggi-susanto/gnmyflow
```

or inside Claude Code:

```text
/plugin marketplace add anggi-susanto/gnmyflow
/plugin install gnmyflow@gnmyflow
```

The plugin starts its own matching GnmyFlow release with `uvx`, so it needs only `uv`
and Chrome; installing `sw` separately is for the command line.

Then just ask:

> Make a 16:9 image of a lighthouse keeper, then a 4-second clip where he turns to the
> sea. Check the price first.
>
> Write a one-minute instrumental bed for a documentary intro and give me the stems.

### Claude Code (MCP server only)

```bash
claude mcp add --scope user gnmyflow -- gnmyflow mcp
```

For long video jobs, raise the tool timeout, e.g. `MCP_TOOL_TIMEOUT=900000` in your
environment.

<details>
<summary><b>Claude Desktop</b></summary>

Settings → Developer → Edit Config, then add the server to `claude_desktop_config.json`
(`%APPDATA%\Claude\` on Windows, `~/Library/Application Support/Claude/` on macOS):

```json
{
  "mcpServers": {
    "gnmyflow": { "command": "gnmyflow", "args": ["mcp"] }
  }
}
```

Quit Claude Desktop completely and start it again.
</details>

<details>
<summary><b>Cursor</b></summary>

`~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):

```json
{
  "mcpServers": {
    "gnmyflow": { "command": "gnmyflow", "args": ["mcp"] }
  }
}
```
</details>

<details>
<summary><b>VS Code (GitHub Copilot)</b></summary>

`.vscode/mcp.json` (note the `servers` key):

```json
{
  "servers": {
    "gnmyflow": { "type": "stdio", "command": "gnmyflow", "args": ["mcp"] }
  }
}
```

For all workspaces, run **MCP: Open User Configuration** and add the same entry.
</details>

<details>
<summary><b>Codex CLI</b></summary>

```bash
codex mcp add gnmyflow -- gnmyflow mcp
```

or in `~/.codex/config.toml`:

```toml
[mcp_servers.gnmyflow]
command = "gnmyflow"
args = ["mcp"]
tool_timeout_sec = 900
```
</details>

<details>
<summary><b>Gemini CLI</b></summary>

```bash
gemini mcp add -s user gnmyflow gnmyflow mcp
```

or in `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "gnmyflow": { "command": "gnmyflow", "args": ["mcp"], "timeout": 900000 }
  }
}
```
</details>

### MCP tools

| Tool | What it does |
| --- | --- |
| `flow_generate_image` | Images with any model, aspect, count, references and download size |
| `flow_generate_video` | Clips with any model and mode, frames, references, size; `dry_run`, `max_credits` |
| `flow_upload` / `flow_download` | Upload references once; fetch existing media again at any size |
| `flow_create_project` / `flow_use_project` | Choose where Flow keeps the work |
| `flow_options` / `flow_status` | Every model and option; recent jobs, pacing and cooldown |
| `music_generate` | A song or instrumental, with lyrics, BPM, length, seed, model, title, cover art |
| `music_edit` | Extend, cover, replace, variation or trim an existing song |
| `music_stems` | Split a song into drums, bass, vocals and other |
| `music_video` | A vertical MP4 of a song from Flow Music's templates |
| `music_download` | Existing songs as WAV, M4A or MP3 |
| `music_library` | The newest songs, the credit balance and the plan (free) |
| `music_chat` | Talk to the Producer agent; saves any songs it makes |
| `music_upload` | Upload your own audio as a private song |

## Command reference

`sw --help` and `sw <command> --help` show every option. The most used ones:

### Images and video

```bash
sw image "PROMPT" [--model nano-banana-2.1|nano-banana-pro|nano-banana-2-lite]
                  [--aspect 16:9|4:3|1:1|3:4|9:16] [--count 1-4] [--ref FILE_OR_ID ...]
                  [--size 1K|2K|4K] [--project ID] [--out DIR] [--json]

sw video "PROMPT" [--model omni-flash|veo-lite|veo-fast|veo-quality] [--mode frames|ingredients]
                  [--start FILE_OR_ID] [--end FILE_OR_ID] [--ref FILE_OR_ID ...]
                  [--aspect 16:9|9:16] [--resolution 360p|720p] [--duration 4|6|8|10]
                  [--size 720p|1080p|4K|270p] [--max-credits N] [--dry-run] [--json]

sw upload FILE ...                 # upload references once, print their media ids
sw download MEDIA_ID ... [--size 2K|1080p]
sw project create "TITLE" | use ID | list
sw run BATCH.jsonl [--keep-going]
sw credits                         # Flow (as of the last clip) and Flow Music balances
sw jobs | sw pace | sw window show|hide | sw stop | sw mcp
```

### Music

`SONG` is a song id, a unique id prefix, a flowmusic.app song URL, or `last`.

```bash
sw music "SOUND" [--lyrics TEXT | --lyrics-file FILE] [--bpm N] [--length 1:00-3:00] [--seed N]
                 [--model lyria-3.5|lyria-3-pro] [--title T] [--cover IMAGE | --cover-prompt TEXT]
                 [--format wav|m4a|mp3] [--out DIR] [--json]

sw music extend SONG [--from 0:45] [--until 2:30] [--prompt TEXT] [--lyrics-file FILE]
sw music cover SONG --prompt "slow jazz trio, brushed drums"
sw music replace SONG --start 0:20 --end 0:35 [--prompt TEXT] [--lyrics-file FILE]
sw music variation SONG
sw music trim SONG --start 0:05 --end 0:35
sw music stems SONG
sw music video SONG [--template simple|modern|player]
sw music download SONG ... [--format wav|m4a|mp3]
sw music chat "MESSAGE" [--session ID] [--audio FILE] [--image FILE] [--confirm-rights]
sw music upload FILE --confirm-rights
sw music list | sw music credits
```

`sw music "SOUND"` is short for `sw music create "SOUND"`. Flow Music asks you to confirm
that you have the rights to files you upload; `--confirm-rights` is that confirmation, and
GnmyFlow never gives it on its own.

## Batch files

A batch is JSON Lines (one job per line) or a JSON list. Jobs run in order, and a job can
use an earlier job's result by its `id`.

```json
{"id": "keeper", "kind": "image", "prompt": "a lighthouse keeper, flat 2D", "refs": ["style.png"]}
{"id": "clip", "kind": "video", "prompt": "he turns to the sea", "start": "keeper", "duration": 6, "max_credits": 12}
{"id": "bed", "kind": "music", "sound": "calm piano underscore", "length": "1:30"}
{"id": "bed-long", "kind": "music", "action": "extend", "song": "bed", "end": "2:30"}
{"id": "bed-stems", "kind": "music", "action": "stems", "song": "bed-long"}
```

```bash
sw run shots.jsonl
```

- `refs`, `start` and `end` take file paths (relative to the batch file), media ids or job
  ids. A music job's `song` takes a song id or a job id.
- Music `action`s: `create` (default), `extend`, `cover`, `replace`, `variation`, `trim`,
  `stems`, `video`. Extend, replace and trim take their times as `start` / `end`.
- Results are appended to `shots.jsonl.results.jsonl`. Running the batch again skips jobs
  that already finished; `--keep-going` continues past a failure.

## Costs and safety

Prices as Flow and Flow Music showed them in October 2026. Your plan may differ.

| Google Flow | Credits |
| --- | --- |
| Image, any Nano Banana model | 0 (daily quota) |
| Omni Flash clip, 360p, 4 s | 4 |
| Omni Flash clip, 720p, 4 / 6 / 8 / 10 s | 7 / 10 / 12 / 15 |
| Veo 3.1 Lite / Fast / Quality, 8 s | 10 / 20 / 100 |

| Google Flow Music | Credits | Time |
| --- | --- | --- |
| New song, extend, cover, replace, variation | 5 | 30-50 s |
| Trim, stems, video template, chat, upload, downloads | 0 | 10-60 s |
| Song made by the Producer in chat | 5 | ~40 s |
| AI music video (through chat) | expensive; check in the app | minutes |

Built-in guards:

- `--dry-run` / `dry_run` sets up a clip and reports Flow's price without submitting.
- `--max-credits` / `max_credits` refuses a clip that costs more.
- Submits are spaced (20 s plus jitter) per profile, across processes.
- When Google reports unusual activity, the profile cools down for 30 minutes and every
  call says so instead of retrying.
- One job at a time per profile (and one Flow Music job at a time), queued by a lock.
  Downloads run in a tab of their own beside generations, since they submit nothing.
- Upscaled downloads (2K/4K, 1080p) are spaced a minute apart. Flow refuses bulk upscaling
  with "unusual activity"; GnmyFlow then pauses upscales for an hour (generations go
  on) and saves new media at their original size meanwhile.

## How it works

```mermaid
flowchart LR
    A["You, Claude or any MCP client"] -->|"sw … / MCP tools"| B["GnmyFlow"]
    B -->|"CDP on 127.0.0.1"| C["Your Chrome<br/>dedicated profile, signed in by you"]
    C -->|"types, clicks, chooses files"| D["Google Flow"]
    C -->|"types, clicks, chooses files"| E["Google Flow Music"]
    D -. "replies are read, never changed" .-> B
    E -. "replies are read, never changed" .-> B
    B --> F[("Downloads/studiowright")]
```

- GnmyFlow starts your installed Chrome on its own profile and attaches over the
  DevTools protocol on loopback. Chrome keeps running between commands, so every call finds
  a warm, signed-in tab.
- Generation uses page controls; selected project and download operations also use
  authenticated browser requests. Replies supply media ids, progress and download links.
- You sign in manually. Chrome retains authentication state in the dedicated profile.
  Loopback CDP has no application authentication: other local processes may control it.
- Job records contain prompts and local paths; failures can save page screenshots.
  Diagnostic scripts in `spikes/` may capture session material. These files are sensitive;
  there is no automatic retention cleanup or application-level encryption. Do not share
  profiles, databases, screenshots or captures without reviewing them.
- No production telemetry destination was identified in the source audit. This is not a
  guarantee about Chrome, dependencies or third-party provider traffic.

Technical notes: [Flow](docs/notes/flow.md) · [Flow Music](docs/notes/flow-music.md).

## Troubleshooting

<details>
<summary><b>"not signed in", or a sign-in page appears</b></summary>

Run `sw stop`, then `sw auth login` (Flow) or `sw auth login --url https://www.flowmusic.app/`
(Flow Music), sign in, and close the window.
</details>

<details>
<summary><b>A job is stuck or very slow</b></summary>

Make sure GnmyFlow's Chrome window is not minimized (`sw window hide` is the safe way
to hide it). Run with `sw -v …` to see each step. A failed job leaves a screenshot in the
`incidents` folder of the data directory, and `sw jobs` shows the error.
</details>

<details>
<summary><b>A clip finished in Flow but the command timed out</b></summary>

`sw download <media id>` fetches it without generating again. The timeout message prints
the ids.
</details>

<details>
<summary><b>"unusual activity" / cooldown</b></summary>

Google asked for a break. Wait for the cooldown (`sw pace` shows it), and spread large
batches out. Do not run several profiles of the same account in parallel.
</details>

<details>
<summary><b>A large project (hundreds of media)</b></summary>

Flow's grid only renders the tiles near the viewport. GnmyFlow finds older references
by searching the prompt box's picker (uploads keep their `sw-<hash>` name) or by scrolling
the grid from where the medium should be, and downloads open each medium's own edit view,
so position in the grid does not matter. Uploaded images download only at their own size;
Flow upscales generated media only.
</details>

<details>
<summary><b>2K / 1080p downloads are refused or paused</b></summary>

Flow limits how many upscales an account may request in a row and answers further ones
with "unusual activity". GnmyFlow stops at the first refusal, pauses upscales for an
hour (`sw pace` shows it) and keeps generating. Download the originals meanwhile, upscale
fewer media, or upscale locally.
</details>

<details>
<summary><b>A music video template fails</b></summary>

Flow Music sometimes cannot render a template for a song. Try again or pick another
template (`--template modern|simple|player`).
</details>

<details>
<summary><b>The MCP client cannot start the server</b></summary>

Give the client the full path of `sw`. The Claude Code plugin needs `uvx` (part of uv) on
the PATH. `sw mcp` run in a terminal should wait silently for input.
</details>

## Configuration

The Python import namespace `studiowright`, `STUDIOWRIGHT_*` environment variables,
and existing data/output directories are retained for compatibility. No profile or
database migration is performed. The renamed plugin uses `GNMYFLOW_SOURCE` for
its source override; update any previous `STUDIOWRIGHT_SOURCE` plugin override.


| Variable | Meaning | Default |
| --- | --- | --- |
| `STUDIOWRIGHT_PROFILE` | Chrome profile to use | `default` |
| `STUDIOWRIGHT_HOME` | data directory: profiles, job database, incidents | `%LOCALAPPDATA%\studiowright` on Windows |
| `STUDIOWRIGHT_OUTPUT` | where files are saved | `Downloads/studiowright` |
| `STUDIOWRIGHT_GAP_S`, `STUDIOWRIGHT_JITTER_S` | pacing between submits | 20 s + 0-6 s |
| `STUDIOWRIGHT_COOLDOWN_S` | pause after an unusual-activity refusal | 1800 s |
| `STUDIOWRIGHT_UPSCALE_GAP_S`, `STUDIOWRIGHT_UPSCALE_JITTER_S` | spacing of upscaled downloads | 60 s + 0-20 s |
| `STUDIOWRIGHT_UPSCALE_COOLDOWN_S` | pause of upscales after a refusal | 3600 s |
| `STUDIOWRIGHT_SOURCE` | what the Claude Code plugin runs with `uvx --from` (e.g. a local checkout) | the plugin's own release |

### Several Google accounts

Each profile is one signed-in Google account with its own Chrome, queue and credits.
Profiles run in parallel; jobs on the same profile take turns.

```bash
sw --profile account-1 auth login     # name it as you like; sign in, close the window
sw --profile account-1 image "…"      # or set STUDIOWRIGHT_PROFILE=account-1
sw auth list                          # each profile and the account it is signed in to
sw auth rename account-1 studio       # keeps the sign-in, projects and settings
sw auth logout studio                 # removes the profile from this computer
```

`logout` deletes only the profile's Chrome data and GnmyFlow's records of it.
Downloaded files stay where they are, and the projects stay in your Google account.
Both `rename` and `logout` wait until that profile's Chrome is closed (`sw stop`).

## Development

```bash
uv sync
uv run pytest                        # unit tests, no browser needed
uv run ruff check src tests spikes
```

### Manual release procedure (no CI)

GitHub Actions is currently disabled because the account has a billing lock, not because
GitHub Free universally excludes Actions. The previous run stopped before any test step.
Local validation passed on macOS with Python 3.12; the Linux/Windows and Python 3.13
matrix has **not** been verified. Live provider/browser behavior is a separate check.

Both registered workflows have been disabled on GitHub. Templates are retained under
`.github/disabled-workflows/*.yml.disabled`, outside the active workflow directory.
Do not restore them or enable publication without a separate review. Trusted Publishing
OIDC is deferred; manual uploads use separate TestPyPI/PyPI API tokens.

The commands below assume macOS/Linux and a shell opened at the repository root. On
Windows, use equivalent PowerShell commands and venv executables under `Scripts/`.
Do not launch Chrome, run diagnostic spikes, sign in, or generate content for these checks.
Installing dependencies accesses package indexes; the smoke test itself blocks socket
connections and Chrome startup during the CLI checks. Package installation does not
install Google Chrome or configure MCP/the Claude Code plugin. No Playwright browser
binary installation is needed: this application attaches to separately installed Chrome.

#### 1. Review and freeze the source

Obtain explicit approval for the release version and source commit. Commit/push only
with permission; build from a clean reviewed checkout, not an uncommitted working tree.
Check that package, runtime, plugin and plugin source pin all agree on `0.3.1`:

```bash
git status --short
git rev-parse HEAD
uv sync --locked
uv run --locked pytest
uv run --locked ruff check src tests spikes scripts
git diff --check
```

Stop on any failure or unexpected working-tree change. Record the source commit, Python,
OS and uv versions outside the package. Do not claim untested platforms are supported.

#### 2. Build once, inspect and record hashes

Use a new temporary workspace so old artifacts are not mixed into the release. Keep this
shell open: later commands reuse `RELEASE_WORK` and `RELEASE_DIST`.

```bash
RELEASE_WORK=$(mktemp -d "${TMPDIR:-/tmp}/gnmyflow-release.XXXXXX")
RELEASE_DIST="$RELEASE_WORK/dist"
uv build --out-dir "$RELEASE_DIST"
uv run --no-project python -c \
  'import runpy, sys; from pathlib import Path; runpy.run_path("scripts/audit_dist.py")["audit"](Path(sys.argv[1]))' \
  "$RELEASE_DIST"
uvx --from twine twine check --strict "$RELEASE_DIST"/*
(cd "$RELEASE_DIST" && shasum -a 256 gnmyflow-0.3.1* > "$RELEASE_WORK/SHA256SUMS")
cat "$RELEASE_WORK/SHA256SUMS"
```

The archive allowlist excludes profiles, session captures, incident screenshots, databases,
`.env`, caches, diagnostic spikes and media showcase files. Inspect the source as well:
an allowed Python file can still contain hard-coded secrets. Keep MIT copyright and
upstream author attribution intact. Freeze these exact archives; **do not rebuild between
TestPyPI and PyPI**. Any source/artifact change invalidates approval and requires revalidation.

#### 3. Clean installation of both local archives

```bash
uv venv "$RELEASE_WORK/wheel" --python 3.12
uv pip install --python "$RELEASE_WORK/wheel/bin/python" "$RELEASE_DIST"/*.whl
"$RELEASE_WORK/wheel/bin/python" -I scripts/smoke_install.py
uv venv "$RELEASE_WORK/sdist" --python 3.12
uv pip install --python "$RELEASE_WORK/sdist/bin/python" "$RELEASE_DIST"/*.tar.gz
"$RELEASE_WORK/sdist/bin/python" -I scripts/smoke_install.py
```

Both must pass metadata/import checks and offline help/version/capabilities for
`gnmyflow`, `sw` and `studiowright`. Dependency resolution here is fresh, rather than the
development lockfile. Do not install alongside upstream in the same environment: the
import namespace and legacy commands overlap. Additional tests on Linux/Windows and
Python 3.13 require their own machines/environments; these commands do not prove them.

#### 4. TestPyPI upload — explicit approval required

Create/manage the TestPyPI account and enable required account security (including 2FA)
through the official website. PyPI is a separate account/index. Create a TestPyPI API
token there; for the first upload a narrowly scoped project token may not yet be possible.
If an account-wide token is needed, revoke it after initial project creation and use a
project-scoped token thereafter. Never publish a placeholder to reserve the name.

Enter the token only into Twine's hidden terminal prompt (username `__token__` if asked).
Never put tokens in chat, commands/arguments, shell history, repository files or a plaintext
`.pypirc`. Avoid terminal/session recording while entering secrets. The following command
disables keyring lookup for that invocation without changing the user's global settings:

```bash
(cd "$RELEASE_DIST" && shasum -a 256 -c "$RELEASE_WORK/SHA256SUMS")
PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring \
  uvx --from twine twine upload \
  --repository-url https://test.pypi.org/legacy/ "$RELEASE_DIST"/*
```

Use an interactive terminal; do not use `--non-interactive` without configured credentials.
If credential environment overrides are already set, clear them in that shell before
upload so Twine prompts instead; never print their values. Do not use `--skip-existing`
to hide errors. For a partial upload, inspect the index, compare existing file hashes,
and upload only a missing file after review. Existing PyPI filenames cannot be overwritten.

#### 5. Verify the TestPyPI package, not a mixed-index substitute

TestPyPI may lack dependencies. Install the exact package only from TestPyPI with
`--no-deps`, then install dependencies separately from PyPI. Do not use a mixed
`--extra-index-url` install as evidence that the target package came from TestPyPI.

```bash
uv venv "$RELEASE_WORK/testpypi" --python 3.12
uv pip install --python "$RELEASE_WORK/testpypi/bin/python" --no-deps \
  --index-url https://test.pypi.org/simple/ 'gnmyflow==0.3.1'
uv pip install --python "$RELEASE_WORK/testpypi/bin/python" \
  --index-url https://pypi.org/simple/ \
  'click>=8.5.0' 'filelock>=4.1.0' 'mcp[cli]>=2.3.0' 'pillow>=11.0' \
  'platformdirs>=4.12.4' 'playwright>=1.63.0'
"$RELEASE_WORK/testpypi/bin/python" -I scripts/smoke_install.py
```

Review `https://test.pypi.org/pypi/gnmyflow/0.3.1/json`: compare the uploaded filenames
and `digests.sha256` with the frozen manifest. Read metadata/README/license on the project
page. TestPyPI success does not reserve the PyPI name or validate provider behavior.

#### 6. PyPI upload — separate explicit approval required

Confirm the name is still usable, source commit is unchanged, and TestPyPI verification
passed. Public HTTP errors are not evidence of name availability; a 404 is not a guarantee
that PyPI permits registration. Use a real release, not a placeholder. Configure 2FA and
an API token on **PyPI**, separate from TestPyPI; use project scope when available and
revoke any bootstrap account-wide token afterward.

```bash
git status --short
git rev-parse HEAD
(cd "$RELEASE_DIST" && shasum -a 256 -c "$RELEASE_WORK/SHA256SUMS")
PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring \
  uvx --from twine twine upload \
  --repository-url https://upload.pypi.org/legacy/ "$RELEASE_DIST"/*
```

This uploads the **same bytes** already tested. Do not rebuild. Verify filenames and
SHA-256 values at `https://pypi.org/pypi/gnmyflow/0.3.1/json`, then install from PyPI alone:

```bash
uv venv "$RELEASE_WORK/pypi" --python 3.12
uv pip install --python "$RELEASE_WORK/pypi/bin/python" \
  --index-url https://pypi.org/simple/ 'gnmyflow==0.3.1'
"$RELEASE_WORK/pypi/bin/python" -I scripts/smoke_install.py
```

#### 7. Tag, GitHub release and updates

After verification and separate approval, create/push `v0.3.1` at the exact reviewed source
commit. Never move the existing `v0.3.0` tag. Create the GitHub release with the source
commit, artifact hashes, upstream attribution, compatibility details and platform/security
limitations. The plugin's pinned source becomes usable only once the tag exists. Update
the installation notice after publication; do not announce success prematurely.

Keep the archives and hash manifest as release evidence; remove only the disposable
venvs when no longer needed. Users may install with `uv tool install gnmyflow` or
`pipx install gnmyflow`, then update with `uv tool upgrade gnmyflow` or
`pipx upgrade gnmyflow`. VCS installations use an explicitly selected release tag.

For a bad release, stop publication, yank the affected version when appropriate, and
publish a new fixed version. PyPI releases cannot be overwritten; do not delete/reuse
filenames or move tags. A yanked version can still be installed with an explicit pin, so
publish a clear advisory. Reinstall a known-good version to roll back; preserve existing
profiles/databases. Revoke compromised tokens immediately and rotate them outside chat.

References: [Twine](https://twine.readthedocs.io/en/stable/),
[TestPyPI](https://packaging.python.org/en/latest/guides/using-testpypi/),
[Trusted Publishing (future option)](https://docs.pypi.org/trusted-publishers/).

- `src/studiowright/flow/` drives Flow, `src/studiowright/music/` drives Flow Music, and
  `studio.py` adds locking, pacing, job records and downloads on top.
- `spikes/` holds the small scripts used to map each page. Most only open menus and read
  replies, at no cost; their docstrings say when one spends credits.
- Tested on Windows 11. The code also finds Chrome on macOS and Linux, but those platforms
  have not been tested yet.

## Disclaimer

- GnmyFlow is not affiliated with, endorsed or sponsored by Google LLC. Google, Flow,
  Flow Music, Veo, Nano Banana and Lyria are trademarks of Google LLC.
- The MIT license covers this code only. It grants no rights to Google's services or to
  what they generate. Your use of Flow and Flow Music, and of their output, is governed by
  Google's terms and your plan.
- Automated use of a web app may conflict with its terms. Use your own account, at your
  own risk and at a human pace. GnmyFlow stops when Google asks it to.
- The web apps can change at any time and break GnmyFlow until it is updated.

## License

[MIT](LICENSE) © 2026 Umut Koçak

### Single-submit create contract (version 1)

`gnmyflow capabilities --json` is a local, read-only probe: it does not open Chrome, sign in,
access an account, or generate anything. Its `production_create_contract: 1` describes
**opt-in** `sw music create "SOUND" --single-submit` behavior (not legacy defaults):

- At most one Generate trigger per invocation, including when no start is observed.
- No heuristic library recovery by title or creation time after an ambiguous failure.
  The original error is propagated; callers must not automatically retry paid creation.
- `--cover-prompt` is rejected because it can generate additional paid cover art.
  A local `--cover` image is allowed. Refilling a failed compose panel before Generate
  is still allowed.
- This is not an exactly-once server guarantee, cross-invocation idempotency, a credit
  reservation, or an assertion that an ambiguous submission spent no credits.

The JSON fields are `production_create_contract` (integer), `single_submit` (boolean),
`heuristic_recovery` (boolean), `create_flag` (string), `models` and `formats` (arrays of
accepted strings), and `min_length` / `max_length` (inclusive seconds). Models, formats,
and length bounds come from request options. Existing create/edit/chat/batch/MCP callers
retain legacy behavior unless a `MusicRequest(single_submit=True)` is explicitly used.
