Pp Suno

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/media-and-entertainment/suno/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

Suno — Printing Press CLI

Prerequisites: Install the CLI

This skill drives the suno-pp-cli binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to $HOME/.local/bin on macOS/Linux and %LOCALAPPDATA%\Programs\PrintingPress\bin on Windows:

   npx -y @mvanhorn/printing-press-library install suno --cli-only

2. Verify: suno-pp-cli --version
3. Ensure the reported install directory is on $PATH for the agent/runtime that will invoke this skill.

If the npx install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.6 or newer). This installs into $GOPATH/bin (default $HOME/go/bin), so add that directory to $PATH instead:

go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/suno/cmd/suno-pp-cli@latest

If --version reports "command not found" after install, the runtime cannot see the binary directory on $PATH. Do not proceed with skill commands until verification succeeds.

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, WAV download, and workspaces, all with --json, --select, --dry-run, and typed exit codes.

When to Use This CLI

Use this CLI when an agent or script needs to generate Suno music programmatically, manage and search a personal Suno library offline, or run reproducible generate/poll/download pipelines with typed exit codes and JSON output. It is the right choice over the abandoned community wrappers because it tracks the current Suno contract and persists everything locally.

Unique Capabilities

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

Command Reference

billing — Account credits, plan, and available models

• suno-pp-cli billing — Show credits, plan, and models
• suno-pp-cli billing eligible-discounts — Show discounts you're eligible for
• suno-pp-cli billing usage-plan — Show the plan comparison table
• suno-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 lyrics
• suno-pp-cli clips publish <clip_id> — Toggle a clip public or private
• suno-pp-cli clips delete <clip_id>… — Trash (or, with --undo, restore) one or more clips
• suno-pp-cli clips timed-lyrics <clip_id> — Word-level timestamped lyrics for a clip
• suno-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-url
• suno-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 info
• suno-pp-cli clips comments <clip_id> — List comments on a clip
• suno-pp-cli clips parent <clip_id> — Show a clip's parent (the clip it was derived from)
• suno-pp-cli clips similar <clip_id> — Find clips similar to a given clip
• suno-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.

All captcha-gated generate commands accept --wait-for-gate (with --gate-timeout, default 30m): when Suno's adaptive gate is tripped (HTTP 422 token_validation_failed), the command backs off and retries until the gate reopens or the timeout elapses. Off by default. It composes with the auto-solver — the solver runs first and --wait-for-gate rides out any residual gate, while under --no-captcha it drives the passive, no-browser fallback on its own. In --agent/JSON mode a gate failure is emitted as a structured envelope on stdout with error_type: "captcha_required" and retriable: true, so agents branch on a field rather than parsing prose.

• suno-pp-cli generate extend <clip_id> — Extend a clip from a timestamp
• suno-pp-cli generate cover <clip_id> — Cover / restyle a clip
• suno-pp-cli generate remaster <clip_id> — Remaster a clip
• suno-pp-cli generate concat — Finalize/concatenate an extended clip into a full song
• suno-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 id
• suno-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 persona
• suno-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 workspaces
• suno-pp-cli project get <project_id> — Show a workspace and its clips
• suno-pp-cli project create — Create a new workspace
• suno-pp-cli project rename <project_id> — Rename a workspace
• suno-pp-cli project trash — Trash (or restore) a workspace
• suno-pp-cli project default — Show your default workspace
• suno-pp-cli project pinned-clips — List clips pinned to your default workspace
• suno-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 playlists
• suno-pp-cli trending list — Show trending clips
• suno-pp-cli user config — Show your user config
• suno-pp-cli user personalization — Show your personalization settings
• suno-pp-cli user personalization-memory — Show your personalization memory
• suno-pp-cli notification list — List your notifications
• suno-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 this SKILL 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 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 library
• suno-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 sessions
• suno-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 NDJSON
• suno-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

Finding the right command

When you know what you want to do but not which command does it, ask the CLI directly:

suno-pp-cli which "<capability in your own words>"

which resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code 0 means at least one match; exit code 2 means no confident match — fall back to --help or use a narrower query.