Generate AI music from your terminal — full Suno v5.5 support
Star this repo Follow @longevityboris
License: MIT Rust crates.io PRs Welcome
A single Rust binary that talks directly to Suno's API. Generate songs with custom lyrics, style tags, your own voice persona, vocal control, weirdness/style sliders, covers, remasters, and every v5.5 feature. Zero-friction auth — one command extracts credentials from your browser automatically.
Install | Quick Start | Commands | Features | Contributing
Suno has no official API. The web UI works, but you can't script it, pipe lyrics from a file, batch-generate, or integrate it into a music production workflow.
This CLI fixes that. Auto-auth from your browser, every generation parameter exposed as a flag, dual JSON/table output for both humans and AI agents. Downloads auto-embed synced lyrics into MP3 files.
brew tap paperfoot/tap brew install suno
cargo install suno
Download from GitHub Releases — binaries for macOS (Apple Silicon + Intel), Linux (x86_64 + ARM), and Windows.
Already have suno installed? Pull the latest binary from GitHub Releases without touching your package manager:
suno update --check # see what's available suno update # install the latest release
Tip: when Suno changes their API mid-cycle, run
suno updatefirst — it's faster thancargo install sunoor waiting for the Homebrew bottle to refresh.
# 1. Authenticate (auto-extracts from Chrome/Arc/Brave/Firefox/Edge) suno auth --login # 2. Check your credits suno credits # 3. Generate a song with full control suno generate \ --title "Weekend Code" \ --tags "indie rock, guitar, upbeat" \ --exclude "metal, heavy" \ --lyrics-file lyrics.txt \ --vocal male \ --weirdness 40 \ --style-influence 65 \ --wait --download ./songs/ # 4. Generate with your voice persona suno generate \ --title "My Song" \ --tags "pop, warm" \ --persona e483d2f0-50ca-4a09-8a74-b9e074646377 \ --lyrics "[Verse]\nHello from the CLI" # 5. Let Suno write the lyrics for you suno describe --prompt "a chill lo-fi track about rainy mornings" --wait
suno generate Custom mode — lyrics + tags + title + sliders + voice persona
suno describe Description mode — Suno writes lyrics from your prompt
suno lyrics Generate lyrics only (free, no credits)
suno extend Continue a clip from a timestamp
suno concat Stitch clips into a full song
suno cover Create a cover with different style/model
suno remaster Remaster with a different model version
suno stems Extract vocals and instruments
suno list List your songs
suno search <query> Search songs by title or tags
suno info <id> Detailed view of a single clip
suno persona <id> View a voice persona
suno status <ids> Check generation progress
suno credits Show balance and plan info
suno models List available models with limits
suno download <ids> Download audio/video with embedded lyrics
suno delete <ids> Delete/trash clips
suno set <id> Update title, lyrics, caption, or remove cover
suno publish <ids> Toggle public/private visibility
suno timed-lyrics Get word-level timestamped lyrics (--lrc for LRC format)
suno auth Set up authentication
suno config show | set | check
suno agent-info Machine-readable capabilities JSON
suno install-skill Install agent skill into Claude Code / Cursor
suno update Self-update from GitHub Releases (--check to peek first)
suno auth --login # Extracts session from your browser automaticallyReads the Clerk auth cookie from Chrome, Arc, Brave, Firefox, or Edge. Exchanges it for a JWT via Clerk token exchange, stores the refreshable session in a 0600 local auth file, and refreshes stale JWTs automatically when the underlying browser session is still valid.
Auth methods (in order of convenience):
suno auth --login— automatic browser extraction (recommended)suno auth --cookie <cookie>— manual paste for headless servers; accepts either raw__clientor a full browserCookieheadersuno auth --jwt <token>— direct JWT, expires in ~1 hoursuno auth --refresh— force a fresh JWT from the stored Clerk session
suno auth with no flags checks the existing session, or starts browser login if no auth is configured. suno auth --logout removes stored credentials.
| Flag | What it does | Values |
|---|---|---|
--title |
Song title | up to 100 chars |
--tags |
Style direction | "pop, synths, upbeat" (1000 chars) |
--exclude |
Styles to avoid | "metal, heavy, dark" (1000 chars) |
--lyrics / --lyrics-file |
Custom lyrics with [Verse] tags |
up to 5000 chars |
--prompt (describe) |
Free text description | up to 500 chars |
--model |
Model version | v5.5, v5, v4.5+, v4.5, v4, v3.5, v3, v2 |
--vocal |
Vocal gender | male, female |
--persona |
Voice persona ID | UUID from Suno voice creation |
--weirdness |
How experimental | 0-100 |
--style-influence |
How strictly to follow tags | 0-100 |
--variation |
Output variation | high, normal, subtle |
--instrumental |
No vocals | flag |
--wait |
Block until done | flag |
--download <dir> |
Auto-download after generation | directory path |
Generate songs using your own voice. Create a voice in Suno's web UI, then use the persona ID:
# View persona details suno persona <persona_id> # Generate with your voice suno generate --persona <persona_id> --title "My Song" --tags "pop" --lyrics "[Verse]\nHello world" # Works with describe mode too suno describe --persona <persona_id> --prompt "a warm ballad about starlight"
Create covers with different styles or remaster clips with newer models:
# Cover with different style tags suno cover <clip_id> --tags "jazz, smooth piano" --model v5.5 --wait # Remaster an old clip with the latest model suno remaster <clip_id> --model v5.5 --wait --download ./remastered/
Both route through Suno's unified web generation endpoint (/api/generate/v2-web/).
# Full details for any clip suno info <clip_id> # JSON for scripting suno info <clip_id> --json | jq '.data.audio_url'
# Update title and lyrics on an existing clip suno set <clip_id> --title "New Title" --lyrics-file updated.txt # Make clips public suno publish <clip_id_1> <clip_id_2> # Get timed lyrics in LRC format suno timed-lyrics <clip_id> --lrc > song.lrc
Downloads automatically embed lyrics into MP3 files via ID3 tags:
- USLT (plain lyrics) — shown in most music players
- SYLT (synced word-by-word timestamps) — shown in Apple Music with timing
suno download <id1> <id2> --output ./songs/
Files use slug format: title-slug-clipid8.mp3 — no overwrites when Suno generates 2 variations.
| Version | Codename | Default | Notes |
|---|---|---|---|
| v5.5 | chirp-fenix | Yes | Latest, best quality |
| v5 | chirp-crow | Previous generation | |
| v4.5+ | chirp-bluejay | Extended capabilities | |
| v4.5 | chirp-auk | Stable | |
| v4 | chirp-v4 | Legacy |
Remaster models: v5.5 = chirp-flounder, v5 = chirp-carp, v4.5+ = chirp-bass.
Every command supports --json for structured output. When stdout is piped, JSON is auto-detected. Progress and errors go to stderr. Exit codes are semantic:
| Code | Meaning | Agent action |
|---|---|---|
| 0 | Success | Continue |
| 1 | Runtime error (network, API) | Retry with backoff |
| 2 | Config error | Fix config, don't retry |
| 3 | Auth error | Run suno auth --login |
| 4 | Rate limited | Wait 30-60s, retry |
| 5 | Not found | Verify resource ID |
Error responses include actionable suggestions:
{
"version": "1",
"status": "error",
"error": {
"code": "auth_expired",
"message": "JWT expired — run `suno auth` to refresh",
"suggestion": "Run `suno auth --login` to refresh your session"
}
}# Pipe-friendly: auto-JSON when piped suno list | jq '.data[0].title' # Agent capabilities discovery suno agent-info
Teach Claude Code (or Cursor) how to use suno with one command:
# Claude Code (~/.claude/skills/suno/SKILL.md) suno install-skill # Cursor (./.cursor/rules/suno.mdc in the current workspace) suno install-skill --target cursor # Print the skill content without writing suno install-skill --print # Custom path suno install-skill --path ~/my-agents/suno.md --force
After installation, your coding agent automatically picks up the skill on the next session and knows how to invoke suno for music generation, downloads, stems, covers, and remasters.
| Endpoint | Version | Status |
|---|---|---|
| Feed | v3 (POST /api/feed/v3) |
Latest |
| Generate | v2-web (POST /api/generate/v2-web/) |
Latest web generation route |
| Concat | v2 (POST /api/generate/concat/v2/) |
Latest |
| Aligned lyrics | v2 (GET /api/gen/{id}/aligned_lyrics/v2/) |
Latest |
| Persona | GET /api/persona/get-persona-paginated/{id}/ |
Confirmed |
Generation tasks use /api/generate/v2-web/ with the current web request shape. Normal generation and voice-persona generation are verified; cover/remaster support is implemented but should be recaptured whenever Suno changes the web schema.
- Fork the repo
- Create a branch (
git checkout -b feature/your-idea) - Make your changes and test with
cargo test - Open a PR
We especially welcome:
- Audio upload implementation (S3 presigned flow documented in
API_INTELLIGENCE.md) - Voice persona creation workflow (endpoints captured, request bodies needed)
- Integration tests with
assert_cmd - OS keychain/Secret Service/CredMan storage for auth secrets
MIT — see LICENSE.