# mmx CLI Flag Reference

The `mmx` CLI exposes MiniMax Music 2.6 parameters as separate flags, giving finer control than packing everything into a single prompt string. This is the full reference.

## Installation and Auth

```bash
# Check installation
mmx --version

# Check auth
mmx auth status

# Login with API key
mmx auth login --api-key "$MINIMAX_API_KEY"

# Set region (if needed)
mmx config set --key region --value global
```

## Command: Standard Generation

```bash
mmx music generate \
  --prompt "..." \
  --lyrics "..." \
  --vocals "..." \
  --genre "..." \
  --mood "..." \
  --instruments "..." \
  --bpm <number> \
  --key "..." \
  --structure "..." \
  --avoid "..." \
  --model music-2.6 \
  --format mp3 \
  --sample-rate 44100 \
  --bitrate 256000 \
  --out /tmp/song.mp3
```

## All Flags

| Flag | Required | Description | Example |
|------|----------|-------------|---------|
| `--prompt` | Yes | Music style description, max 2000 chars | `"French chanson, melancholic"` |
| `--lyrics` | One of lyrics/instrumental/optimizer | Song lyrics with structure tags, max 3500 chars | `"[Verse]\nJ'ai trouvé..."` |
| `--lyrics-file` | Alt to `--lyrics` | Read lyrics from file | `song.txt` or `-` for stdin |
| `--instrumental` | Alt to `--lyrics` | No vocals | (flag only) |
| `--lyrics-optimizer` | Alt to `--lyrics` | Auto-generate lyrics from prompt | (flag only) |
| `--vocals` | Optional | Vocal style | `"passionate French male vocal"` |
| `--genre` | Optional | Music genre | `"french chanson"` |
| `--mood` | Optional | Mood/emotion | `"melancholic romantic dramatic"` |
| `--instruments` | Optional | Featured instruments | `"accordion, piano, strings"` |
| `--tempo` | Optional | Tempo description | `"slow"`, `"moderate"`, `"fast"` |
| `--bpm` | Optional | Exact BPM | `80` |
| `--key` | Optional | Musical key | `"E minor"`, `"C major"` |
| `--avoid` | Optional | Elements to avoid (comma-separated) | `"sparse, a cappella, electronic sounds"` |
| `--use-case` | Optional | Context | `"background music for film"` |
| `--structure` | Optional | Song structure | `"verse-chorus-bridge-chorus"` |
| `--references` | Optional | Reference artists or tracks | `"similar to Édith Piaf"` |
| `--extra` | Optional | Additional requirements | `"wide dynamic contrast"` |
| `--model` | Optional | Model name | `music-2.6` (paid) or `music-2.6-free` (lower RPM) |
| `--output-format` | Optional | `hex` (default) or `url` (24h expiry) | `hex` |
| `--format` | Optional | Audio format | `mp3` (default) |
| `--sample-rate` | Optional | Sample rate | `44100` (default) |
| `--bitrate` | Optional | Bitrate | `256000` (default) |
| `--out` | Optional | Output file path | `/tmp/song.mp3` |
| `--stream` | Optional | Stream raw audio to stdout | (flag only) |
| `--seed` | Optional | Reproducible seed (0–1,000,000) | `42` |

## Structure Tags (in `--lyrics`)

```
[Intro]        Opening section
[Verse]        Main verse
[Pre Chorus]   Build before chorus
[Chorus]       Main hook
[Interlude]    Instrumental break
[Bridge]       Contrast section
[Outro]        Closing section
[Post Chorus]  After-chorus
[Transition]   Connective passage
[Break]        Dramatic pause or silence
[Hook]         Catchy repeated motif
[Build Up]     Tension building before climax
[Inst]         Instrumental section
[Solo]         Instrument solo
```

**Rules:**

- Tags must be clean — no descriptions inside brackets (they get sung).
- Separate sections with blank lines.
- Use `\n` for line breaks in `--lyrics` flag.

Full tag reference with timing and effects: see [`../music-craft/references/structure-tags.md`](../../music-craft/references/structure-tags.md).

## Anti-Sparse Flags

The `--avoid` flag is the primary anti-sparse lever. Recommended text:

```
--avoid "sparse, a cappella, minimal arrangement, electronic sounds, synthetic textures"
```

For sparse-friendly genres (ambient, ballad, lofi), add explicit instruments in `--instruments` to compensate:

```bash
--instruments "piano, soft pads, sustained strings, gentle bass, light percussion, ambient textures" \
--avoid "sparse, a cappella, minimal, silence" \
--extra "quiet sections: reduced to piano and bass only, still fully played, NEVER silent"
```

## Worked Example: French Chanson Ballad

```bash
mmx music generate \
  --prompt "French chanson ballad, melancholic romantic mood, passionate theatrical French male vocal, accordion, upright bass, orchestral strings, piano, light percussion — ALL instruments ALWAYS playing throughout, NEVER go a cappella or silent, dramatic 1-2s pauses between sections, wide dynamic contrast, build from quiet verses to powerful choruses, full production, studio recording quality" \
  --lyrics "[Intro]
[Break]

[Verse]
J'ai trouvé ta lettre
Mais je n'ai pas vraiment vérifié

[Pre Chorus]
Non, je ne veux pas connaître les raisons

[Build Up]

[Chorus]
Je sais que je, je sais que je, je ne peux pas continuer avec toooooou

[Break]

[Verse]
Depuis que je t'ai vu
Je savais que tu ne me conviendrais pas

[Pre Chorus]
Non, je ne veux pas connaître les raisons

[Build Up]

[Chorus]
Je sais que je, je sais que je, je ne peux pas continuer avec toooooou

[Bridge]
Et je voulais toujours que tu partes pendant que je dormais
Il n'y a pas de sortie facile

[Break]

[Chorus]
Je sais que je, je sais que je, je ne peux pas continuer avec toooooou

[Outro]
Non, je ne regrette rieeeen" \
  --vocals "passionate theatrical French male vocal" \
  --genre "french chanson" \
  --mood "melancholic romantic dramatic" \
  --instruments "accordion, upright bass, orchestral strings, piano, light percussion" \
  --bpm 80 \
  --key "E minor" \
  --structure "intro-verse-pre-chorus-chorus-verse-pre-chorus-chorus-bridge-break-chorus-outro" \
  --avoid "sparse, a cappella, minimal arrangement, electronic sounds, synthetic textures" \
  --model music-2.6 \
  --out /tmp/song.mp3
```

## When to Use `--seed`

The `--seed` flag makes the generation reproducible. Same prompt + same seed = same output. Use when:

- iterating on a prompt and you want to compare versions with one variable changed
- debugging — a "bad" output is reproducible so you can adjust
- teaching — students can replay the same example

For exploratory generation, omit the seed and let MiniMax surprise you.

## When NOT to Use `mmx`

Use `mmx` when you need fine control over specific parameters. Use the `music_generate` tool with prompt-only when:

- the runtime already configures MiniMax with sensible defaults
- you do not need separate `--bpm`, `--key`, `--structure` flags
- the user does not care about exact BPM (just "slow" or "fast")
- you want the workflow to be portable across providers (skill 1 path)

Both produce equivalent results if the prompt and flags are aligned. The difference is in how the parameters are expressed, not in the output quality.

## Rate Limits and Token Plan

- **RPM:** 120 per minute (documented)
- **Concurrent:** 20 connections
- **Output URL:** 24h expiry
- **Token Plan 3.0:** credit-based unified pool, 5h rolling + weekly window

See the base skill's `Rate Limits` section for the full details.

## Troubleshooting

| Issue | Fix |
|---|---|
| `mmx: command not found` | Install via the MiniMax install guide, or skip `mmx` features and use `music_generate` |
| `401 Unauthorized` | Re-run `mmx auth login --api-key "$MINIMAX_API_KEY"` |
| Sparse output | Add `--avoid` with the canonical anti-sparse text + explicit `--instruments` |
| Lyrics too long (>3500 chars) | Shorten or split into sections |
| Wrong region | `mmx config set --key region --value global` |
| `429 Too Many Requests` | Wait 60s, check Token Plan usage, reduce concurrency |
| Output URL expired | Download the file within 24h of generation, or use `--output-format hex` for local saving |