pp-suno

What this skill does

<!-- 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:
   ```bash
   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.4 or newer). This installs into `$GOPATH/bin` (default `$HOME/go/bin`), so add that directory to `$PATH` instead:

```bash
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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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 collecti