# flowmusic-cli

> Unofficial CLI and MCP server for Google Flow Music (flowmusic.app, Lyria models). It generates, remixes, splits into stems and downloads songs with the user's own Google account. Install: `uv tool install flowmusic-cli`. Command: `fmusic`. Sign in once: `fmusic auth login`, which needs the human user.

Key facts:
- Add `--json` to any command: stdout gets `{"status":"ok","data":…}` or `{"status":"fail","error":{type,detail,exit_code,retryable,hint}}`. Progress goes to stderr.
- Generate: `fmusic --json generate "<genre, mood, instruments, tempo, vocals>" [--lyrics FILE] [--instrumental] [-o DIR]`. It takes 1–2 minutes and spends credits. The result is `data.clips[]` (with local `files[]`) and `data.conversation_id`.
- Follow up: `fmusic --json chat <conversation_id> "make it faster"`.
- Exit codes: 3/8 = not logged in (ask the user to run `fmusic auth login`), 10 = busy (retry), 21 = blocked by policy or region, 37 = out of credits.
- MCP: `uvx --from flowmusic-cli fmusic mcp run`. Tools: fmusic_generate, fmusic_chat, fmusic_list_clips, fmusic_get_clip, fmusic_download, fmusic_stems, fmusic_credits, fmusic_auth_status.

## Docs

- [README](https://github.com/JvanLeeuwen4/flowmusic-cli/blob/main/README.md): overview, install, quick start
- [Command reference](https://github.com/JvanLeeuwen4/flowmusic-cli/blob/main/docs/commands.md): every command, flag and JSON shape
- [MCP server](https://github.com/JvanLeeuwen4/flowmusic-cli/blob/main/docs/mcp.md): client setup and tool parameters
- [Troubleshooting](https://github.com/JvanLeeuwen4/flowmusic-cli/blob/main/docs/troubleshooting.md): exit codes, sign-in, region limits
- [How it works](https://github.com/JvanLeeuwen4/flowmusic-cli/blob/main/docs/how-it-works.md): auth flow and API endpoints
- [Claude Code skill](https://github.com/JvanLeeuwen4/flowmusic-cli/blob/main/skills/fmusic/SKILL.md)
