suno-cli

Generate AI music from your terminal — full Suno v5.5 support

A 3.4MB Rust binary that talks directly to Suno's API. Generate songs with custom lyrics, style tags, vocal control, weirdness/style sliders, and every v5.5 feature — no browser needed.

Install | Quick Start | Commands | Features | Contributing

Why

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. Cookie-based auth, every generation parameter exposed as a flag, dual JSON/table output for both humans and AI agents.

Install

Homebrew (macOS/Linux)

brew tap 199-biotechnologies/tap
brew install suno-cli

Cargo (any platform)

cargo install suno-cli

Pre-built binaries

Download from GitHub Releases — binaries for macOS (Apple Silicon + Intel), Linux (x86_64 + ARM), and Windows.

Quick Start

# 1. Get your JWT from browser DevTools (Network tab → any Suno request → Authorization header)
suno auth --jwt "eyJhbG..." --device "your-device-id"

# 2. Check your credits
suno credits

# 3. Generate lyrics (free, no credits)
suno lyrics --prompt "a song about weekend coding sessions"

# 4. Generate a song
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/

Commands

suno generate       Custom mode — lyrics + tags + title + sliders
suno inspire        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
suno remaster       Remaster with a different model
suno stems          Extract vocals and instruments
suno feed           List your songs
suno status <id>    Check generation progress
suno download <id>  Download audio/video
suno credits        Show balance and plan info
suno models         List available models with limits
suno auth           Set up authentication
suno config         show | set | check
suno agent-info     Machine-readable capabilities JSON

Features

Generation Parameters

Models

Agent-Friendly

Every command supports --json for structured output. When stdout is piped, JSON is auto-detected. Progress, errors, and spinners go to stderr. Exit codes are semantic:

# Pipe-friendly: auto-JSON when piped
suno feed | jq '.[0].title'

# Explicit JSON
suno credits --json

How Auth Works

Browser DevTools → copy JWT + device-id → suno auth → stored at ~/.config/suno-cli/auth.json

The JWT expires after ~1 hour. Re-run suno auth with a fresh token when it expires. The CLI checks expiry before every request and tells you when it's time to refresh.

Project Structure

src/
├── main.rs           Entry point, command routing
├── cli.rs            All clap derive structs
├── auth.rs           JWT storage, browser-token generation
├── config.rs         Config layering (env vars, defaults)
├── errors.rs         Error types with exit codes
├── download.rs       Audio/video download with progress bar
├── api/
│   ├── mod.rs        SunoClient — auth headers, base requests
│   ├── types.rs      Clip, Model, BillingInfo, etc.
│   ├── generate.rs   Music generation + polling
│   ├── lyrics.rs     Lyrics generation
│   ├── billing.rs    Credits and plan info
│   ├── feed.rs       Song listing
│   ├── concat.rs     Clip concatenation
│   ├── cover.rs      Cover generation
│   ├── remaster.rs   Remastering
│   └── stems.rs      Stem extraction
└── output/
    ├── mod.rs        Format detection (TTY vs piped)
    ├── json.rs       JSON envelope
    └── table.rs      Terminal tables

Contributing

1. Fork the repo
2. Create a branch (git checkout -b feature/your-idea)
3. Make your changes and test with cargo test
4. Open a PR

We especially welcome:

• New API endpoint coverage (personas, voices, custom models)
• Better auth flows (Clerk cookie refresh, OS keychain)
• Integration tests

License

MIT — see LICENSE.

Built by Boris Djordjevic at Paperfoot AI

If this saves you time: