suno-music-cli 0.1.2

CLI for generating music via sunoapi.org

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

Command	What it does
suno generate	Submit a generation job. Returns a taskId.
suno status	Poll record-info for a task. --watch blocks until done.
suno download	Save audio files to disk, or print URLs with --url-only.
suno extend	Continue an existing track from a timestamp.
suno lyrics	Submit a lyrics-only generation job.
suno credits	Show remaining account balance.
suno list	Show recently submitted jobs from local cache.
suno config	Manage API key and other settings.

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