flowmusic-cli 0.1.0__tar.gz

flowmusic_cli-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,12 @@
+{
+  "name": "flowmusic-cli",
+  "owner": { "name": "JvanLeeuwen4", "url": "https://github.com/JvanLeeuwen4" },
+  "plugins": [
+    {
+      "name": "fmusic",
+      "source": "./",
+      "description": "Generate, remix and download music with Google Flow Music (Lyria): skill + MCP server.",
+      "category": "media"
+    }
+  ]
+}

flowmusic_cli-0.1.0/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "fmusic",
+  "version": "0.1.0",
+  "description": "Generate, remix and download music with Google Flow Music (Lyria) via the unofficial fmusic CLI + MCP server.",
+  "author": { "name": "JvanLeeuwen4", "url": "https://github.com/JvanLeeuwen4" },
+  "homepage": "https://github.com/JvanLeeuwen4/flowmusic-cli",
+  "repository": "https://github.com/JvanLeeuwen4/flowmusic-cli",
+  "license": "MIT",
+  "keywords": ["music", "lyria", "flow music", "audio", "mcp"]
+}

flowmusic_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python: ["3.10", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv run --extra dev ruff check src tests
+      - run: uv run --extra dev pytest -q
+
+  pypi:
+    # Requires a "trusted publisher" on pypi.org for this repo + workflow `ci.yml` + environment `pypi`.
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  mcp-registry:
+    # Publishes server.json to https://registry.modelcontextprotocol.io (auth via GitHub OIDC,
+    # allowed because the server name is io.github.JvanLeeuwen4/...).
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: pypi
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install mcp-publisher
+        run: |
+          curl -fsSL "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_linux_amd64.tar.gz" | tar xz mcp-publisher
+      - name: Wait for PyPI to serve the new version
+        run: |
+          v="${GITHUB_REF_NAME#v}"
+          for i in $(seq 1 30); do
+            curl -fs "https://pypi.org/pypi/flowmusic-cli/$v/json" >/dev/null && exit 0
+            sleep 10
+          done
+          echo "version $v not on PyPI yet" && exit 1
+      - run: ./mcp-publisher login github-oidc
+      - run: ./mcp-publisher publish

flowmusic_cli-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+out/
+session.json
+*.wav
+*.m4a

flowmusic_cli-0.1.0/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "fmusic": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/JvanLeeuwen4/flowmusic-cli", "fmusic", "mcp", "run"]
+    }
+  }
+}

flowmusic_cli-0.1.0/AGENTS.md

@@ -0,0 +1,51 @@
+# AGENTS.md
+
+This file is a guide for AI coding agents and contributors working **on** this repository.
+
+To **use** the tool, read [README.md](README.md), [docs/commands.md](docs/commands.md) and [docs/mcp.md](docs/mcp.md). Agents using it through Claude Code should also read the skill in [skills/fmusic/SKILL.md](skills/fmusic/SKILL.md).
+
+## What this is
+
+`flowmusic-cli` is an unofficial Python CLI and MCP server for Google Flow Music (flowmusic.app). It signs in once with a browser, then makes plain HTTP calls to the site's `/__api` backend. [docs/how-it-works.md](docs/how-it-works.md) describes every endpoint and payload.
+
+## Setup and checks
+
+```bash
+uv venv && uv pip install -e ".[dev]"
+uv run --extra dev pytest -q          # unit tests (no network, respx mocks)
+uv run --extra dev ruff check src tests
+```
+
+## Rules
+
+- **Tests never touch the network.** Mock HTTP with `respx`. Fixtures in `tests/fixtures/` are scrubbed captures of real responses; keep them free of real user ids, emails and tokens.
+- **Never commit secrets.** That includes `session.json`, cookie values, `ya29.` tokens and anything under `out/`.
+- **Errors are typed.** Raise a subclass from `errors.py`; each one maps to a stable exit code, so don't renumber them. User-facing advice goes in `hint`.
+- **Output channels.** Results go to stdout through `emit_json` / `out`. Progress and chatter go to stderr through `err` / `ctx.say`. `--json` output must stay one JSON object.
+- **Keep the CLI and MCP tools in sync.** A new capability belongs in `cli.py` and in `mcp_server.py`, plus `docs/commands.md` and `docs/mcp.md`.
+- **The API is reverse-engineered.** When a response shape changes, update `docs/how-it-works.md` along with the code, and add a fixture or test for the new shape.
+- **Be careful with live testing.** It spends real credits on the developer's account, and `clips delete` is permanent. Only delete clips you created during the test.
+
+## Layout
+
+```text
+src/flowmusic_cli/
+  cli.py              Click commands (entry point: fmusic / flowmusic)
+  mcp_server.py       MCP tools + `mcp setup`
+  config.py           constants + FMUSIC_* env settings
+  errors.py           typed errors → exit codes
+  output.py           stdout/stderr helpers
+  auth/               session.py, supabase.py (refresh), browser_login.py
+  api/                client.py, sse.py, generate.py, download.py
+tests/                pytest + respx
+docs/                 user + contributor docs
+skills/fmusic/        Claude Code skill
+.claude-plugin/       Claude Code plugin + marketplace manifest
+.mcp.json             MCP server config used by the plugin
+server.json           MCP Registry metadata
+```
+
+## Releasing
+
+1. Bump `version` in `pyproject.toml`, `src/flowmusic_cli/__init__.py`, `server.json` (twice) and `.claude-plugin/plugin.json`.
+2. `git tag vX.Y.Z && git push --tags`. CI runs the tests, publishes to PyPI (trusted publishing), then publishes `server.json` to the MCP Registry.

flowmusic_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joost
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flowmusic_cli-0.1.0/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.5
+Name: flowmusic-cli
+Version: 0.1.0
+Summary: Unofficial command-line client for Google Flow Music (flowmusic.app, Lyria) — generate, download and manage songs from your terminal.
+Project-URL: Homepage, https://github.com/JvanLeeuwen4/flowmusic-cli
+Project-URL: Issues, https://github.com/JvanLeeuwen4/flowmusic-cli/issues
+Author: Joost
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,flow music,google,lyria,mcp,music generation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: filelock>=3.13
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.2
+Requires-Dist: platformdirs>=4.2
+Requires-Dist: playwright>=1.45
+Requires-Dist: rich>=13.7
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# flowmusic-cli
+
+**Make music with Google Flow Music (Lyria) from your terminal, your scripts, or your AI agent.**
+
+`fmusic` is a command-line client and MCP server for [flowmusic.app](https://www.flowmusic.app). You sign in once with your own Google account. After that it works without a browser: you describe a song, and a few minutes later you have a WAV file plus a JSON file with its details.
+
+<!-- MCP registry ownership verification: do not remove -->
+mcp-name: io.github.JvanLeeuwen4/flowmusic-cli
+
+> [!IMPORTANT]
+> **Unofficial project.** It is not affiliated with, endorsed by, or supported by Google. It uses the same endpoints as the flowmusic.app website, so it can break when the site changes. You use your own account and credits. Follow the Flow Music [terms](https://policies.google.com/terms) and the [generative AI use policy](https://policies.google.com/terms/generative-ai/use-policy), and don't use it for spam or mass generation.
+
+---
+
+## Quick start
+
+```bash
+uv tool install flowmusic-cli        # 1. install (or: pipx install flowmusic-cli)
+fmusic auth login                    # 2. a browser opens once: sign in with Google
+fmusic generate "dreamy synthwave, airy female vocals, 100 bpm"   # 3. make a song
+```
+
+Example output:
+
+```text
+♪ take 1 (audio__create_song) Dreamy synthwave, airy female vocals, lush pads, 100 bpm
+  queued "Neon Drift" 3e2b2139-… (~35s)
+  ✓ rendered "Neon Drift"
+⬇ ~/Music/flowmusic-cli/2026-11-04/neon-drift_3e2b2139.wav
+Neon Drift  1:44  3e2b2139-2783-4171-a2b4-a51d03bc4504
+continue with: fmusic chat 13001945-… "…"
+```
+
+**What you need:**
+- Python 3.10+, via [uv](https://docs.astral.sh/uv/) or pipx.
+- Google Chrome or Edge, for the one-time sign-in.
+- A Google account with Flow Music access. A Google AI subscription gives the most credits.
+
+---
+
+## What you can do
+
+| I want to… | Command |
+|---|---|
+| Make a song from a description | `fmusic generate "folk ballad about the sea, male vocals"` |
+| Use my own lyrics | `fmusic generate "upbeat k-pop" --lyrics lyrics.txt` |
+| Make an instrumental | `fmusic generate "lofi beat, 80 bpm" --instrumental` |
+| Change a song I just made | `fmusic chat <conversation_id> "make it faster, add a bridge"` |
+| Restyle my own audio | `fmusic generate "turn this into a jazz trio" --audio demo.mp3` |
+| Split a song into stems | `fmusic stems <clip_id>` (vocals, drums, bass, other) |
+| See my songs | `fmusic clips list` |
+| Download, rename or delete songs | `fmusic clips download/rename/delete <clip_id>` |
+| Check my credits | `fmusic credits` |
+
+The full reference for every command and flag is in **[docs/commands.md](docs/commands.md)**.
+
+### How generation works
+
+Flow Music has an AI **co-producer**. Your prompt goes to it, and it decides what to make: often one or two *takes*. It rewrites your prompt into a detailed "sound prompt" and may suggest next steps. Each generation belongs to a **conversation**, and `fmusic chat <conversation_id> "…"` continues that conversation, for example to tweak, extend or remix a take.
+
+If you want exact control without the co-producer, use the **experimental** `--direct` mode. Your prompt goes to the song model as-is, and `-n` sets the number of takes:
+
+```bash
+fmusic generate "minimal techno, 126 bpm, hypnotic" --direct -n 2 --title "Night Drive"
+```
+
+---
+
+## Install
+
+| Method | Command |
+|---|---|
+| uv (recommended) | `uv tool install flowmusic-cli` |
+| pipx | `pipx install flowmusic-cli` |
+| Latest from GitHub | `uv tool install git+https://github.com/JvanLeeuwen4/flowmusic-cli` |
+| Update | `uv tool upgrade flowmusic-cli` |
+
+The package installs two equivalent commands, `fmusic` and `flowmusic`.
+
+## Sign in
+
+```bash
+fmusic auth login      # opens Chrome/Edge: sign in with Google; the window closes by itself
+fmusic auth status     # shows email, subscription tier, credits (exit code 0 = OK)
+fmusic auth logout
+```
+
+- You sign in once. Tokens refresh automatically, so you won't need to sign in again unless you log out or the session is revoked.
+- To use several accounts, add `--profile work` (or set `FMUSIC_PROFILE=work`) to any command.
+- **Can't open a browser** (for example on a server)? Sign in on flowmusic.app on another machine. In the browser's DevTools, open the Network tab and copy the `Cookie` header of any `__api` request. Then run:
+  ```bash
+  fmusic auth import "sb-sb-auth-token.0=base64-…; sb-sb-auth-token.1=…"
+  ```
+
+---
+
+## Use it from AI agents
+
+`fmusic` is built to be driven by agents. There are three ways:
+
+### 1. Claude Code plugin (skill + MCP server)
+
+```text
+/plugin marketplace add JvanLeeuwen4/flowmusic-cli
+/plugin install fmusic@flowmusic-cli
+```
+
+Then run `fmusic auth login` once in a terminal. The plugin starts the MCP server through `uvx`, so you don't need to install anything else.
+
+### 2. Any MCP client (Claude Desktop, Cursor, VS Code, Codex, …)
+
+Add this to the client's MCP configuration. It only needs [uv](https://docs.astral.sh/uv/):
+
+```json
+{
+  "mcpServers": {
+    "fmusic": { "command": "uvx", "args": ["--from", "flowmusic-cli", "fmusic", "mcp", "run"] }
+  }
+}
+```
+
+If `fmusic` is already installed, this command writes the config for you:
+
+```bash
+fmusic mcp setup --target claude-code      # or: claude-desktop, print
+```
+
+The tools and their parameters are listed in **[docs/mcp.md](docs/mcp.md)**.
+
+### 3. The CLI with `--json`
+
+Every command accepts `--json`:
+- **Results** go to stdout as one JSON object: `{"status":"ok","data":…}` or `{"status":"fail","error":{…}}`.
+- **Progress messages** go to stderr.
+- **Exit codes** are stable. See [docs/troubleshooting.md](docs/troubleshooting.md#exit-codes).
+
+```bash
+fmusic --json generate "calm piano, 70 bpm" --instrumental | jq '.data.clips[].files'
+```
+
+Agents working *on* this repository should read [AGENTS.md](AGENTS.md).
+
+---
+
+## Where files go
+
+By default, songs are saved to `~/Music/flowmusic-cli/<date>/`. Use `-o DIR` to choose a folder; the files then go directly in it. Each clip produces:
+
+```text
+neon-drift_3e2b2139.wav     # audio (or .m4a with --format m4a; both with --format both)
+neon-drift_3e2b2139.json    # title, duration, sound prompt, lyrics, ids, URLs
+neon-drift_3e2b2139.jpg     # cover art (only with --cover)
+```
+
+## Configuration
+
+All settings are optional environment variables.
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `FMUSIC_PROFILE` | `default` | Which saved account to use |
+| `FMUSIC_OUTPUT_DIR` | `~/Music/flowmusic-cli` | Where downloads go |
+| `FMUSIC_HOME` | OS user-data dir | Where sessions are stored |
+| `FMUSIC_TIMEOUT` | `60` | HTTP timeout in seconds |
+
+## Troubleshooting
+
+The most common issues:
+
+- **Uploads with vocals fail with "not available in your region".** In some regions, including the EU, Flow Music doesn't allow uploading tracks with vocals or removing vocals from them. Upload instrumentals instead.
+- **`Session expired` (exit code 3).** Run `fmusic auth login` again.
+- **Google won't let you sign in.** Make sure Chrome or Edge is installed. You can also use `fmusic auth import` instead.
+
+Everything else is in **[docs/troubleshooting.md](docs/troubleshooting.md)**.
+
+---
+
+## Documentation
+
+| Doc | For |
+|---|---|
+| [docs/commands.md](docs/commands.md) | Every command, flag and JSON shape |
+| [docs/mcp.md](docs/mcp.md) | MCP tools and client setup |
+| [docs/troubleshooting.md](docs/troubleshooting.md) | Errors, exit codes, fixes |
+| [docs/how-it-works.md](docs/how-it-works.md) | Architecture and the flowmusic.app API |
+| [AGENTS.md](AGENTS.md) | Contributors and coding agents |
+| [llms.txt](llms.txt) | A compact summary for LLMs |
+
+## Contributing
+
+Issues and pull requests are welcome. See [AGENTS.md](AGENTS.md) for the layout and test commands:
+
+```bash
+uv run --extra dev pytest
+```
+
+The sign-in approach is inspired by [gflow-cli](https://github.com/ffroliva/gflow-cli). MIT licensed.

flowmusic_cli-0.1.0/README.md

@@ -0,0 +1,197 @@
+# flowmusic-cli
+
+**Make music with Google Flow Music (Lyria) from your terminal, your scripts, or your AI agent.**
+
+`fmusic` is a command-line client and MCP server for [flowmusic.app](https://www.flowmusic.app). You sign in once with your own Google account. After that it works without a browser: you describe a song, and a few minutes later you have a WAV file plus a JSON file with its details.
+
+<!-- MCP registry ownership verification: do not remove -->
+mcp-name: io.github.JvanLeeuwen4/flowmusic-cli
+
+> [!IMPORTANT]
+> **Unofficial project.** It is not affiliated with, endorsed by, or supported by Google. It uses the same endpoints as the flowmusic.app website, so it can break when the site changes. You use your own account and credits. Follow the Flow Music [terms](https://policies.google.com/terms) and the [generative AI use policy](https://policies.google.com/terms/generative-ai/use-policy), and don't use it for spam or mass generation.
+
+---
+
+## Quick start
+
+```bash
+uv tool install flowmusic-cli        # 1. install (or: pipx install flowmusic-cli)
+fmusic auth login                    # 2. a browser opens once: sign in with Google
+fmusic generate "dreamy synthwave, airy female vocals, 100 bpm"   # 3. make a song
+```
+
+Example output:
+
+```text
+♪ take 1 (audio__create_song) Dreamy synthwave, airy female vocals, lush pads, 100 bpm
+  queued "Neon Drift" 3e2b2139-… (~35s)
+  ✓ rendered "Neon Drift"
+⬇ ~/Music/flowmusic-cli/2026-11-04/neon-drift_3e2b2139.wav
+Neon Drift  1:44  3e2b2139-2783-4171-a2b4-a51d03bc4504
+continue with: fmusic chat 13001945-… "…"
+```
+
+**What you need:**
+- Python 3.10+, via [uv](https://docs.astral.sh/uv/) or pipx.
+- Google Chrome or Edge, for the one-time sign-in.
+- A Google account with Flow Music access. A Google AI subscription gives the most credits.
+
+---
+
+## What you can do
+
+| I want to… | Command |
+|---|---|
+| Make a song from a description | `fmusic generate "folk ballad about the sea, male vocals"` |
+| Use my own lyrics | `fmusic generate "upbeat k-pop" --lyrics lyrics.txt` |
+| Make an instrumental | `fmusic generate "lofi beat, 80 bpm" --instrumental` |
+| Change a song I just made | `fmusic chat <conversation_id> "make it faster, add a bridge"` |
+| Restyle my own audio | `fmusic generate "turn this into a jazz trio" --audio demo.mp3` |
+| Split a song into stems | `fmusic stems <clip_id>` (vocals, drums, bass, other) |
+| See my songs | `fmusic clips list` |
+| Download, rename or delete songs | `fmusic clips download/rename/delete <clip_id>` |
+| Check my credits | `fmusic credits` |
+
+The full reference for every command and flag is in **[docs/commands.md](docs/commands.md)**.
+
+### How generation works
+
+Flow Music has an AI **co-producer**. Your prompt goes to it, and it decides what to make: often one or two *takes*. It rewrites your prompt into a detailed "sound prompt" and may suggest next steps. Each generation belongs to a **conversation**, and `fmusic chat <conversation_id> "…"` continues that conversation, for example to tweak, extend or remix a take.
+
+If you want exact control without the co-producer, use the **experimental** `--direct` mode. Your prompt goes to the song model as-is, and `-n` sets the number of takes:
+
+```bash
+fmusic generate "minimal techno, 126 bpm, hypnotic" --direct -n 2 --title "Night Drive"
+```
+
+---
+
+## Install
+
+| Method | Command |
+|---|---|
+| uv (recommended) | `uv tool install flowmusic-cli` |
+| pipx | `pipx install flowmusic-cli` |
+| Latest from GitHub | `uv tool install git+https://github.com/JvanLeeuwen4/flowmusic-cli` |
+| Update | `uv tool upgrade flowmusic-cli` |
+
+The package installs two equivalent commands, `fmusic` and `flowmusic`.
+
+## Sign in
+
+```bash
+fmusic auth login      # opens Chrome/Edge: sign in with Google; the window closes by itself
+fmusic auth status     # shows email, subscription tier, credits (exit code 0 = OK)
+fmusic auth logout
+```
+
+- You sign in once. Tokens refresh automatically, so you won't need to sign in again unless you log out or the session is revoked.
+- To use several accounts, add `--profile work` (or set `FMUSIC_PROFILE=work`) to any command.
+- **Can't open a browser** (for example on a server)? Sign in on flowmusic.app on another machine. In the browser's DevTools, open the Network tab and copy the `Cookie` header of any `__api` request. Then run:
+  ```bash
+  fmusic auth import "sb-sb-auth-token.0=base64-…; sb-sb-auth-token.1=…"
+  ```
+
+---
+
+## Use it from AI agents
+
+`fmusic` is built to be driven by agents. There are three ways:
+
+### 1. Claude Code plugin (skill + MCP server)
+
+```text
+/plugin marketplace add JvanLeeuwen4/flowmusic-cli
+/plugin install fmusic@flowmusic-cli
+```
+
+Then run `fmusic auth login` once in a terminal. The plugin starts the MCP server through `uvx`, so you don't need to install anything else.
+
+### 2. Any MCP client (Claude Desktop, Cursor, VS Code, Codex, …)
+
+Add this to the client's MCP configuration. It only needs [uv](https://docs.astral.sh/uv/):
+
+```json
+{
+  "mcpServers": {
+    "fmusic": { "command": "uvx", "args": ["--from", "flowmusic-cli", "fmusic", "mcp", "run"] }
+  }
+}
+```
+
+If `fmusic` is already installed, this command writes the config for you:
+
+```bash
+fmusic mcp setup --target claude-code      # or: claude-desktop, print
+```
+
+The tools and their parameters are listed in **[docs/mcp.md](docs/mcp.md)**.
+
+### 3. The CLI with `--json`
+
+Every command accepts `--json`:
+- **Results** go to stdout as one JSON object: `{"status":"ok","data":…}` or `{"status":"fail","error":{…}}`.
+- **Progress messages** go to stderr.
+- **Exit codes** are stable. See [docs/troubleshooting.md](docs/troubleshooting.md#exit-codes).
+
+```bash
+fmusic --json generate "calm piano, 70 bpm" --instrumental | jq '.data.clips[].files'
+```
+
+Agents working *on* this repository should read [AGENTS.md](AGENTS.md).
+
+---
+
+## Where files go
+
+By default, songs are saved to `~/Music/flowmusic-cli/<date>/`. Use `-o DIR` to choose a folder; the files then go directly in it. Each clip produces:
+
+```text
+neon-drift_3e2b2139.wav     # audio (or .m4a with --format m4a; both with --format both)
+neon-drift_3e2b2139.json    # title, duration, sound prompt, lyrics, ids, URLs
+neon-drift_3e2b2139.jpg     # cover art (only with --cover)
+```
+
+## Configuration
+
+All settings are optional environment variables.
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `FMUSIC_PROFILE` | `default` | Which saved account to use |
+| `FMUSIC_OUTPUT_DIR` | `~/Music/flowmusic-cli` | Where downloads go |
+| `FMUSIC_HOME` | OS user-data dir | Where sessions are stored |
+| `FMUSIC_TIMEOUT` | `60` | HTTP timeout in seconds |
+
+## Troubleshooting
+
+The most common issues:
+
+- **Uploads with vocals fail with "not available in your region".** In some regions, including the EU, Flow Music doesn't allow uploading tracks with vocals or removing vocals from them. Upload instrumentals instead.
+- **`Session expired` (exit code 3).** Run `fmusic auth login` again.
+- **Google won't let you sign in.** Make sure Chrome or Edge is installed. You can also use `fmusic auth import` instead.
+
+Everything else is in **[docs/troubleshooting.md](docs/troubleshooting.md)**.
+
+---
+
+## Documentation
+
+| Doc | For |
+|---|---|
+| [docs/commands.md](docs/commands.md) | Every command, flag and JSON shape |
+| [docs/mcp.md](docs/mcp.md) | MCP tools and client setup |
+| [docs/troubleshooting.md](docs/troubleshooting.md) | Errors, exit codes, fixes |
+| [docs/how-it-works.md](docs/how-it-works.md) | Architecture and the flowmusic.app API |
+| [AGENTS.md](AGENTS.md) | Contributors and coding agents |
+| [llms.txt](llms.txt) | A compact summary for LLMs |
+
+## Contributing
+
+Issues and pull requests are welcome. See [AGENTS.md](AGENTS.md) for the layout and test commands:
+
+```bash
+uv run --extra dev pytest
+```
+
+The sign-in approach is inspired by [gflow-cli](https://github.com/ffroliva/gflow-cli). MIT licensed.