suno-music-cli

A small, friendly command-line client for sunoapi.org. Submit lyrics or a description, get a task ID back, poll until ready, and download the resulting MP3 — all from your terminal, scriptable end to end.

Features

• Generate music from a description or your own lyrics, in any language.
• Tune the result with sliders for style adherence, weirdness, and audio weight; control vocal gender, models (V4 through V5_5), and personas.
• Extend an existing track from any timestamp, with optional fresh parameters or inherited defaults.
• Watch and download with a single --wait flag, or fire-and-forget and poll later with --last.
• URL-only mode — get the 15-day CDN link without downloading the file.
• Local job cache so you never have to copy-paste task IDs.
• JSON output on every read command for jq pipelines.

Install

pip install suno-music-cli

Requires Python 3.10 or newer.

Configure

Get an API key from sunoapi.org and provide it one of two ways:

export SUNO_API_KEY=sk-...                # ephemeral
suno config set-key sk-...                # persistent, in ~/.suno/config.toml

Optional overrides: SUNO_BASE_URL, SUNO_CALLBACK_URL. See Documentation.md §2.

Quick start

# Submit a job (the model writes its own lyrics from the description)
suno generate -p "ambient piano, soft rain, late night" -m V5

# Watch it through to completion
suno status --last --watch

# Save the audio
suno download --last -o ./out/

--last always points to the most recent job in your local cache.

Commands at a glance

Every flag is documented in Documentation.md §3.

A richer example: custom lyrics with full control

suno generate \
  --custom \
  --lyrics-file ./lyrics.txt \
  --style-file  ./style.txt \
  --title       "Midnight Drive" \
  --model       V5 \
  --vocal-gender f \
  --style-weight 0.85 \
  --weirdness    0.20 \
  --negative-tags "metal, heavy distortion" \
  --wait

Custom mode lets you provide your own lyrics with section markers ([Verse 1], [Chorus], [Bridge]), works in non-Latin scripts, and honors a long, structured style descriptor. The three weight sliders fine-tune how closely the model follows your direction. See §4 — Techniques for the craft side of getting good music out of Suno.

URLs vs files

suno download --last --url-only          # print the CDN URLs (15-day links)
suno download --last -o ./out/           # save to ./out/<title>.mp3
suno download --last -o song.mp3 --track 1

A taskId typically returns two tracks; multi-track outputs are saved with an 8-character suffix to keep filenames unique.

Documentation

The full reference — every flag, every API field, all the music-creation techniques (lyrics structure, style descriptors, slider pairings, language handling, troubleshooting) — lives in Documentation.md.

Highlights:

• Concepts — modes, models, status lifecycle, character limits.
• Command reference — every flag mapped to its API field.
• Techniques — how to write a style descriptor that actually works, what the sliders do, multilingual lyrics tips.
• Troubleshooting — common errors and fixes.

Limits and constraints (good to know)

• 20 requests per 10-second window (server rate limit).
• Stream URLs available 30–40s after submit, download URLs 2–3 minutes after.
• Generated files retained on the CDN for 15 days, then deleted.
• Per-model character caps for prompt, style, and title — see §1.5.

Contributing

Issues and pull requests welcome at github.com/bengeos/suno-music-cli.

License

MIT © 2026 Biniam Kassahun