The correct, offline-first Suno CLI — every feature the abandoned clients have, plus a local SQLite library, full-text search, and agent-native output none of them ship.
Suno has no official API and every reverse-engineered client is abandoned and wrong in ways that matter today — broken pagination, broken cover, stale pre-2026 auth, no local persistence. This CLI is built from the current contract: it walks the real opaque feed cursor, sends the now-required cover title, tolerates the drifted billing schema, authenticates against the current auth.suno.com Clerk flow via your logged-in browser, and persists your whole library to local SQLite for offline grep, SQL, lineage, and analytics. Generate, extend, cover, remaster, stems, lyrics, download — all with --json, --select, --dry-run, and typed exit codes.
Created by @mvanhorn (Matt Van Horn).
Authentication
Suno uses Clerk session auth (auth.suno.com). Run suno-pp-cli auth login --chrome to capture your logged-in session cookie from Chrome; the CLI mints and refreshes the short-lived JWT for you. No password or API key is stored. Music generation is attempted optimistically with no token. Suno gates generation adaptively (an hCaptcha anti-bot challenge that usually fires only after sustained use), so many generations succeed outright; if Suno challenges a request, the CLI tells you to retry with --token carrying an hCaptcha token (e.g. solved via 2Captcha). All read, library, and metadata commands never need a captcha.
Quick Start
# Confirm the binary and config resolve before anything touches the network.
suno-pp-cli doctor --dry-run
# After 'auth login --chrome', pull your whole library into local SQLite (walks the opaque feed cursor).
suno-pp-cli sync --full
# Find clips by a remembered lyric phrase via local full-text search.
suno-pp-cli grep "chorus" --json
# Rank your best tracks for a publishing workflow.
suno-pp-cli top --by upvote_count --limit 10 --json
Unique Features
These capabilities aren't available in any other tool for this API.
Local library no Suno tool has
-
grep — Find clips by remembered lyric, prompt, or tag phrases via local full-text search.
Reach for this when an agent needs to locate a specific past song by its content, not its title.
suno-pp-cli grep "rain" --json --select id,title,tags
-
analytics — Grouped roll-ups across your whole library: counts, average duration/bpm, total plays and upvotes by any clip field.
Use this to see which models or settings produced your most-played tracks before the next session.
suno-pp-cli analytics --type clips --group-by model_name --json
-
lineage — Render the iteration tree of a track: its extends, covers, and remixes, reconstructed from local links.
Reach for this to trace which seed a finished song descended from across many variations.
suno-pp-cli lineage 7d869de4-9476-4a4d-a6f2-c0eec968a3e2 --json
-
top — Ranked flat list of your best clips by plays, upvotes, or duration, with machine-readable output.
Use this to pipe your strongest tracks into a publishing or playlist workflow.
suno-pp-cli top --by upvote_count --limit 10 --json
-
sql — Run read-only SQL directly against your local synced clip store.
Reach for this when an agent needs an arbitrary query no fixed command covers.
suno-pp-cli sql "SELECT title, duration FROM clips WHERE make_instrumental = 1 ORDER BY duration DESC LIMIT 5" --json
Reachability awareness
-
credits --forecast — Remaining credits plus your recent generation volume measured against Suno's captcha-throttle threshold.
Use this before a batch session to judge how many more generations you can run before hCaptcha kicks in.
suno-pp-cli credits --forecast --json
Recipes
Generate a custom song and wait for it
suno-pp-cli generate create --title "Night Drive" --tags "synthwave, retro" --lyrics-file ./lyrics.txt --token <hcaptcha> --wait --json
Submits a custom generation, polls until complete, and prints the finished clip as JSON.
Pull a deeply nested clip and select only what you need
suno-pp-cli clips get --ids 7d869de4-9476-4a4d-a6f2-c0eec968a3e2 --agent --select id,title,status,audio_url,metadata.duration,metadata.tags
Fetches a clip and narrows the verbose nested payload to just the fields an agent needs, saving context.
Find and rank instrumentals offline
suno-pp-cli sql "SELECT title, duration FROM clips WHERE make_instrumental = 1 ORDER BY duration DESC LIMIT 5" --json
Queries the local store directly for your longest instrumental tracks, no API call.
Check throttle headroom before a session
suno-pp-cli credits --forecast --json
Shows remaining credits and recent generation volume against the captcha-throttle threshold.
Organize tracks into a workspace
suno-pp-cli project add ws_3f2a91 --clip clip_a1b2 --clip clip_c3d4
Adds clips to a Suno workspace (project) so they stay organized on suno.com.
Download a lossless WAV
suno-pp-cli download clip_a1b2c3 --format wav --out ./tracks
Triggers WAV conversion, polls until ready, and saves the lossless file (Pro/Premier).
Usage
Run suno-pp-cli --help for the full command reference and flag list.
Commands
billing
Account credits, plan, and available models
suno-pp-cli billing - Show credits, plan, and modelssuno-pp-cli billing eligible-discounts - Show discounts you're eligible forsuno-pp-cli billing usage-plan - Show the plan comparison tablesuno-pp-cli billing usage-plan-faq - Show plan/usage FAQ
clips
Your Suno songs (clips) — list, fetch, manage
suno-pp-cli clips list - List your library (walks the opaque next_cursor; use --all to drain). Shows a workspace column from the local membership index.suno-pp-cli clips get - Fetch clip(s) by ID (comma-separated; Suno batches 2 at a time)suno-pp-cli clips set <clip_id> - Update a clip's title, caption, or lyricssuno-pp-cli clips publish <clip_id> - Toggle a clip public or privatesuno-pp-cli clips delete <clip_id>… - Trash (or, with --undo, restore) one or more clipssuno-pp-cli clips timed-lyrics <clip_id> - Word-level timestamped lyrics for a clipsuno-pp-cli clips stems <clip_id> - Separate a clip into stems (vocals + instruments)suno-pp-cli clips convert-wav <clip_id> - Trigger WAV (lossless) conversion (Pro/Premier); poll wav-urlsuno-pp-cli clips wav-url <clip_id> - Get the WAV download URL (null until conversion finishes)suno-pp-cli clips attribution <clip_id> - Show a clip's sample/attribution infosuno-pp-cli clips comments <clip_id> - List comments on a clipsuno-pp-cli clips parent <clip_id> - Show a clip's parentsuno-pp-cli clips similar <clip_id> - Find clips similar to a given clipsuno-pp-cli clips direct-children-count <clip_ids> - Count direct children (extends/covers)
generate
Music, lyrics, and video generation jobs
suno-pp-cli generate create - Generate a custom song from lyrics (captcha-gated). --variation high|normal|subtle, --project <id>.suno-pp-cli generate describe - Description-driven (inspiration) generation. --variation, --instrumental.suno-pp-cli generate extend <clip_id> - Extend a clip from a timestampsuno-pp-cli generate cover <clip_id> - Cover / restyle a clipsuno-pp-cli generate remaster <clip_id> - Remaster a clipsuno-pp-cli generate concat - Finalize/concatenate an extended clip into a full songsuno-pp-cli generate lyrics - Submit a lyrics-generation job (returns an id to poll)suno-pp-cli generate lyrics-status <id> - Poll a lyrics-generation job by idsuno-pp-cli generate video-status <id> - Check video-generation status for a clip
persona
Voice personas
suno-pp-cli persona get <persona_id> - View a voice personasuno-pp-cli persona usage - Show how many clips use each persona (and which are orphans)
project
Workspaces (Suno 'projects') — organize your tracks into collections
suno-pp-cli project list - List your workspacessuno-pp-cli project get <project_id> - Show a workspace and its clipssuno-pp-cli project create - Create a new workspacesuno-pp-cli project rename <project_id> - Rename a workspacesuno-pp-cli project trash - Trash (or restore) a workspacesuno-pp-cli project default - Show your default workspacesuno-pp-cli project pinned-clips - List clips pinned to your default workspacesuno-pp-cli project add <project_id> - Add clip(s) to a workspace (repeatable --clip)suno-pp-cli project remove <project_id> - Remove clip(s) from a workspace (repeatable --clip)
playlist / trending / user / notification
Library and account reads
suno-pp-cli playlist list - List your playlistssuno-pp-cli trending list - Show trending clipssuno-pp-cli user config - Show your user configsuno-pp-cli user personalization - Show your personalization settingssuno-pp-cli user personalization-memory - Show your personalization memorysuno-pp-cli notification list - List your notificationssuno-pp-cli notification badge-count - Show unread notification badge count
skill
Install the Suno CLI as a coding-agent skill
suno-pp-cli skill install - Write SKILL.md into Claude/Codex/Cursor locations. --agent claude|codex|cursor|all, --print, --path <file>, --force.
Restored local & utility commands
Parity with the 2026-05-15 build — these coexist with the novel commands (grep, analytics, lineage, top, sql) above.
suno-pp-cli vibes save <name> - Save a local generation recipe (tags/prompt-template/persona/mv); replay with vibes use <name> [topic]. Also vibes list|get|delete.suno-pp-cli burn --by tag|persona|model|hour - Aggregate estimated generation credits across your local librarysuno-pp-cli budget set daily|monthly <N> - Set a local credit cap; budget show reports spend; caps block over-limit generate calls. budget clear removes the cap.suno-pp-cli sessions - Group synced clips into 30-minute-gap working sessionssuno-pp-cli ship <clip-id> - Export an editor-ready bundle (audio + video + cover + .lrc + .json sidecar)suno-pp-cli tail <resource> --interval 10s - Poll the API and stream changes as NDJSONsuno-pp-cli tree <clip-id> - Render a clip's local lineage tree (legacy view; see also lineage)suno-pp-cli custom-model - List pending custom-model training jobs
Output Formats
# Human-readable table (default in terminal, JSON when piped)
suno-pp-cli clips list
# JSON for scripting and agents
suno-pp-cli clips list --json
# Filter to specific fields
suno-pp-cli clips list --json --select id,name,status
# Dry run — show the request without sending
suno-pp-cli clips list --dry-run
# Agent mode — JSON + compact + no prompts in one flag
suno-pp-cli clips list --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Explicit retries - add
--idempotent to create retries when a no-op success is acceptable
- Confirmable -
--yes for explicit confirmation of destructive actions
- Piped input - write commands can accept structured input when their help lists
--stdin
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Health Check
suno-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Config file: ~/.config/suno-pp-cli/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
SUNO_JWT | per_call | Yes | Set to your API credential. |
Troubleshooting
Authentication errors (exit code 4)
- Run
suno-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $SUNO_JWT
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- auth login fails or commands return 401 or Token validation failed — Re-run
suno-pp-cli auth login --chrome while logged in to suno.com in Chrome; JWTs are short-lived and refreshed from the captured Clerk cookie.
- generate returns a captcha-required error — Supply an hCaptcha token with
--token <token> (e.g. from 2Captcha) or pass --no-captcha if your environment provides one; read/library commands never need it.
- list or sync only returns the first page — This CLI walks the opaque next_cursor automatically; pass
--all to drain the entire library, or --full on sync.
- cover returns HTTP 422 — This CLI sends the now-required title field automatically; pass
--title if you want a specific cover title.
Sources & Inspiration
This CLI was built by studying these projects and resources:
Generated by CLI Printing Press