pp-suno

Suno — Printing Press CLI

前提条件：安装 CLI

此技能使用 suno-pp-cli 二进制文件。**在调用此技能中的任何命令之前，必须确认 CLI 已安装。**如果尚未安装，请先安装：

1. 使用 Printing Press 安装程序安装。在 macOS/Linux 上，二进制文件默认安装到 $HOME/.local/bin；在 Windows 上，默认安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin：

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

2. 验证：suno-pp-cli --version
3. 确保报告的安装目录位于将调用此技能的 Agent/运行时的 $PATH 中。

如果 npx 安装失败（没有 Node、处于离线状态等），请改用直接 Go 安装（需要 Go 1.26.6 或更高版本）。这会将程序安装到 $GOPATH/bin（默认是 $HOME/go/bin），因此请将该目录添加到 $PATH：

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

如果安装后 --version 报告“command not found”，说明运行时无法在 $PATH 中找到二进制文件所在目录。验证成功前，请勿继续执行此技能中的命令。

Suno 没有官方 API，而每个逆向工程客户端都已被弃用，并且在当下至关重要的方面存在错误：分页损坏、封面功能损坏、身份验证沿用过时的 2026 年前方案，也无法在本地持久化。此 CLI 基于当前契约构建。它会遍历真正的不透明动态游标，发送现在必需的封面标题，兼容不断变化的计费架构，通过你已登录的浏览器，使用当前的 auth.suno.com Clerk 流程进行身份验证，并将整个曲库持久化到本地 SQLite，以便离线 grep、SQL 查询、溯源和分析。支持生成、延长、翻唱、重制、分轨、歌词、WAV 下载和工作区，并支持 --json、--select、--dry-run 以及类型化退出码。

何时使用此 CLI

当 Agent 或脚本需要以编程方式生成 Suno 音乐、离线管理和搜索个人 Suno 曲库，或使用类型化退出码和 JSON 输出运行可复现的生成／轮询／下载流水线时，请使用此 CLI。与已弃用的社区封装相比，这是更合适的选择，因为它能跟进当前 Suno 契约，并将所有内容持久化到本地。

独特功能

其他用于此 API 的工具都不具备这些功能。

没有其他 Suno 工具具备的本地曲库功能

• grep — 通过本地全文搜索，根据记得的歌词、提示词或标签短语查找片段。

  当 Agent 需要根据内容而非标题查找特定的旧歌曲时，可使用此功能。

  suno-pp-cli grep "rain" --json --select id,title,tags
  

• analytics — 按任意片段字段对整个曲库进行分组汇总：数量、平均时长／BPM、总播放量和点赞数。

  在下一次创作之前，可用此功能查看哪些模型或设置生成的曲目播放量最高。

  suno-pp-cli analytics --type clips --group-by model_name --json
  

• lineage — 根据本地链接重建曲目的迭代树，展示其延长版本、翻唱版本和混音版本。

  当你需要跨多个变体追溯成品歌曲源自哪个种子时，可使用此功能。

  suno-pp-cli lineage 7d869de4-9476-4a4d-a6f2-c0eec968a3e2 --json
  

• top — 按播放量、点赞数或时长排列的最佳片段列表，并提供机器可读的输出。

  可使用此功能，将表现最佳的曲目导入发布或播放列表工作流。

  suno-pp-cli top --by upvote_count --limit 10 --json
  

• sql — 直接对本地同步的片段库运行只读 SQL 查询。

  当 Agent 需要运行固定命令未涵盖的任意查询时，可使用此功能。

  suno-pp-cli sql "SELECT title, duration FROM clips WHERE make_instrumental = 1 ORDER BY duration DESC LIMIT 5" --json
  

可达性意识

• credits --forecast — 显示剩余点数，以及近期生成量与 Suno 验证码限流阈值的对比。

  批量创作前，可用此功能判断触发 hCaptcha 前还可以进行多少次生成。

  suno-pp-cli credits --forecast --json
  

命令参考

billing — 账户点数、套餐和可用模型

• suno-pp-cli billing — 显示点数、套餐和模型
• suno-pp-cli billing eligible-discounts — 显示你符合条件的折扣
• suno-pp-cli billing usage-plan — 显示套餐对比表
• suno-pp-cli billing usage-plan-faq — 显示套餐／用量常见问题

clips — 你的 Suno 歌曲（片段）——列出、获取和管理

• suno-pp-cli clips list — 列出你的资料库（遍历不透明的 next_cursor；使用 --all 获取全部结果）。显示来自本地成员索引的 workspace 列。
• suno-pp-cli clips get — 按 ID 获取剪辑（逗号分隔；Suno 每次批量处理 2 个）
• suno-pp-cli clips set <clip_id> — 更新剪辑的标题、说明或歌词
• suno-pp-cli clips publish <clip_id> — 将剪辑设为公开或私密
• suno-pp-cli clips delete <clip_id>… — 将一个或多个剪辑移入废纸篓（或使用 --undo 恢复）
• suno-pp-cli clips timed-lyrics <clip_id> — 获取剪辑中带有逐词时间戳的歌词
• suno-pp-cli clips stems <clip_id> — 将剪辑分离为多个音轨（人声和乐器）
• suno-pp-cli clips convert-wav <clip_id> — 触发 WAV（无损）转换（Pro/Premier）；轮询 wav-url
• suno-pp-cli clips wav-url <clip_id> — 获取 WAV 下载 URL（转换完成前为 null）
• suno-pp-cli clips attribution <clip_id> — 显示剪辑的采样/归属信息
• suno-pp-cli clips comments <clip_id> — 列出剪辑的评论
• suno-pp-cli clips parent <clip_id> — 显示剪辑的父剪辑（即其衍生来源）
• suno-pp-cli clips similar <clip_id> — 查找与指定剪辑相似的剪辑
• suno-pp-cli clips direct-children-count <clip_ids> — 统计直接子项（扩展/翻唱）的数量

generate — 音乐、歌词和视频生成任务

• suno-pp-cli generate create — 根据歌词生成自定义歌曲（需要通过验证码验证）。--variation high|normal|subtle、--project <id>。
• suno-pp-cli generate describe — 根据描述（灵感）生成内容。--variation、--instrumental。

所有需要验证码验证的 generate 命令都支持 --wait-for-gate（可搭配 --gate-timeout，默认值为 30m）：当 Suno 的自适应验证机制触发时（HTTP 422 token_validation_failed），命令会退避并重试，直到验证机制解除或超时。默认关闭。此选项可与自动求解器配合使用——求解器先运行，--wait-for-gate 会等待任何残余验证解除；而在 --no-captcha 模式下，它会独立驱动无浏览器的被动回退方案。在 --agent/JSON 模式下，验证失败会在标准输出中以结构化信封形式返回，并包含 error_type: "captcha_required" 和 retriable: true，因此 Agent 可以根据字段分支处理，而不必解析文本说明。

• suno-pp-cli generate extend <clip_id> — 从指定时间戳扩展剪辑
• suno-pp-cli generate cover <clip_id> — 翻唱/重新编曲剪辑
• suno-pp-cli generate remaster <clip_id> — 重制剪辑
• suno-pp-cli generate concat — 完成/拼接扩展后的剪辑，生成完整歌曲
• suno-pp-cli generate lyrics — 提交歌词生成任务（返回可供轮询的 ID）
• suno-pp-cli generate lyrics-status <id> — 按 ID 轮询歌词生成任务
• suno-pp-cli generate video-status <id> — 检查剪辑的视频生成状态

persona — 声音角色

• suno-pp-cli persona get <persona_id> — 查看声音角色
• suno-pp-cli persona usage — 显示每个角色被多少个剪辑使用（以及哪些是孤立角色）

project — 工作区（Suno 的“项目”）——将曲目整理到合集

• suno-pp-cli project list — 列出你的工作区
• suno-pp-cli project get <project_id> — 显示工作区及其剪辑
• suno-pp-cli project create — 创建新工作区
• suno-pp-cli project rename <project_id> — 重命名工作区
• suno-pp-cli project trash — 将工作区移入废纸篓（或恢复）
• suno-pp-cli project default — 显示你的默认工作区
• suno-pp-cli project pinned-clips — 列出固定到默认工作区的剪辑
• suno-pp-cli project add <project_id> — 将剪辑添加到工作区（可重复使用 --clip）
• suno-pp-cli project remove <project_id> — 从工作区移除剪辑（可重复使用 --clip）

playlist / trending / user / notification — 资料库和账户读取

• suno-pp-cli playlist list — 列出你的播放列表
• suno-pp-cli trending list — 显示热门片段
• suno-pp-cli user config — 显示你的用户配置
• suno-pp-cli user personalization — 显示你的个性化设置
• suno-pp-cli user personalization-memory — 显示你的个性化记忆
• suno-pp-cli notification list — 列出你的通知
• suno-pp-cli notification badge-count — 显示未读通知徽标计数

skill — 将 Suno CLI 安装为编码 Agent 技能

• suno-pp-cli skill install — 将此 SKILL 写入 Claude/Codex/Cursor 位置。--agent claude|codex|cursor|all、--print、--path <file>、--force。

已恢复的本地和实用工具命令 — 与 2026-05-15 版本保持一致；这些命令与上方的新命令共存

• suno-pp-cli vibes save <name> — 保存本地生成配方（标签/提示词模板/角色/MV）；使用 vibes use <name> [topic] 重新生成。另有 vibes list|get|delete。
• suno-pp-cli burn --by tag|persona|model|hour — 汇总本地库中预估的生成积分
• suno-pp-cli budget set daily|monthly <N> — 设置本地积分上限；budget show 会报告支出；超出上限时会阻止 generate 调用。budget clear 会移除上限。
• suno-pp-cli sessions — 将同步的片段按 30 分钟间隔分组成工作会话
• suno-pp-cli ship <clip-id> — 导出可直接用于编辑的素材包（音频 + 视频 + 封面 + .lrc + .json 旁置文件）
• suno-pp-cli tail <resource> --interval 10s — 轮询 API，并以 NDJSON 流式输出变更
• suno-pp-cli tree <clip-id> — 渲染片段的本地谱系树（旧版视图；另请参阅 lineage）
• suno-pp-cli custom-model — 列出待处理的自定义模型训练任务

查找合适的命令

当你知道想做什么，但不知道该用哪个命令时，可以直接询问 CLI：

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

which 会根据自然语言功能查询，从 CLI 精选的功能索引中找出最匹配的命令。退出代码 0 表示至少找到一个匹配项；退出代码 2 表示无法确定匹配项，此时可改用 --help 或缩小查询范围。

示例

生成一首自定义歌曲并等待完成

suno-pp-cli generate create --title "Night Drive" --tags "synthwave, retro" --lyrics "Neon lights on wet asphalt" --token hc_demo_token --wait --json

提交自定义生成任务，轮询直至完成，并将生成的片段以 JSON 格式输出。省略 --token 时，CLI 会通过验证码配置文件自动完成验证；也可以提供预先验证的令牌以跳过浏览器。

拉取深层嵌套的片段，并仅选择所需内容

suno-pp-cli clips get --ids 7d869de4-9476-4a4d-a6f2-c0eec968a3e2 --agent --select id,title,status,audio_url,metadata.duration,metadata.tags

获取片段，并将冗长的嵌套载荷精简为 Agent 所需的字段，以节省上下文。

离线查找并排序纯音乐

suno-pp-cli sql "SELECT title, duration FROM clips WHERE make_instrumental = 1 ORDER BY duration DESC LIMIT 5" --json

直接查询本地存储，找出时长最长的纯音乐曲目，无需调用 API。

开始会话前检查限流余量

suno-pp-cli credits --forecast --json

显示剩余积分和近期生成量，并与验证码限流阈值进行对照。

将曲目整理到工作区

suno-pp-cli workspace add ws_3f2a91 --clip clip_a1b2 --clip clip_c3d4

将片段添加到 Suno 工作区（项目），以便在 suno.com 上保持井然有序。

下载无损 WAV

suno-pp-cli download clip_a1b2c3 --format wav --out ./tracks

触发 WAV 转换，轮询直至就绪，并保存无损文件（Pro/Premier）。

身份验证设置

Suno 使用 Clerk 会话身份验证（auth.suno.com）。运行 suno-pp-cli auth login --chrome，从 Chrome 中捕获已登录的会话 Cookie；CLI 会为你签发并刷新短期 JWT。不会存储密码或 API 密钥。音乐生成会在没有令牌的情况下乐观尝试。Suno 会动态启用生成限制（hCaptcha 反机器人验证通常只会在持续使用一段时间后触发），因此许多生成请求都能直接成功。触发限制时，CLI 会自动使用专用的受控 Chrome 配置文件解决验证问题——运行 suno-pp-cli auth captcha login --profile <name> 登录某个配置文件，然后在任何受限命令中传入 --captcha-profile <name> 以选择该账户。在 --agent/--no-input 模式下，会抑制可见浏览器回退，并在 stdout 上输出结构化的 {"error_type":"captcha_required","retriable":true} 信封（退出码 2）。若要完全跳过自动解题器，请传入 --no-captcha，或使用 --token 提供已解决验证的令牌。读取、库和元数据命令都不需要验证码。

运行 suno-pp-cli doctor 验证设置。添加 --probe-gate 可专门检查实时生成限制：默认健康检查只能证明计费 API 可访问，即使生成受限，检查仍会显示正常。doctor --probe-gate 会报告 tripped（动态 hCaptcha 限制已启用）或 open。警告：此命令会实际发起一次生成——限制启用时免费，但限制未启用时会创建一段片段并消耗额度（探测片段会尽力删除）。

Agent 模式

在任何命令中添加 --agent。它会展开为：--json --compact --no-input --no-color --yes。

• 可管道传输 — JSON 输出到 stdout，错误输出到 stderr

• 可筛选 — --select 保留部分字段。点分路径可深入嵌套结构；数组会逐元素遍历。对于冗长 API，这对控制上下文大小至关重要：

  suno-pp-cli clips list --agent --select id,name,status
  

• 可预览 — --dry-run 显示请求但不发送

• 适合离线使用 — 本地 SQLite 存储可用时，同步/搜索命令可以使用该存储

• 非交互式 — 从不提示，每项输入都是一个标志

• 明确重试 — 仅当已存在的创建结果应视为成功时，才使用 --idempotent

响应信封

从本地存储或 API 读取数据的命令会将输出封装在来源信封中：

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

解析 .results 获取数据，并查看 .meta.source 判断数据来自实时接口还是本地存储。只有当 stdout 是终端，且未设置任何机器格式标志（--json、--csv、--compact、--quiet、--plain、--select）时，才会向 stderr 输出人类可读的 N results (live) 摘要——通过管道接收输出的 Agent 和明确指定输出格式的运行都会在 stdout 上获得纯 JSON。

Agent 反馈

当你（或 Agent）发现此 CLI 有问题时，请记录下来：

suno-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
suno-pp-cli feedback --stdin < notes.txt
suno-pp-cli feedback list --json --limit 10

条目会保存在本地的 ~/.local/share/suno-pp-cli/feedback.jsonl。只有设置了 SUNO_FEEDBACK_ENDPOINT，并且传入了 --send 或 SUNO_FEEDBACK_AUTO_SEND=true 时，条目才会通过 POST 发送。默认行为仅保存到本地。

写下令你感到意外的地方，而不是提交 Bug 报告。简短、具体、一行即可：这才是会不断积累的部分。

输出传递

每条命令都接受 --deliver <sink>。除 stdout 外，输出还会发送到指定目标，也可以仅发送到指定目标，这样 Agent 无需手动通过管道传输，就能路由命令结果。支持三种目标：

目标	效果
stdout	默认；仅写入 stdout
file:<path>	将输出原子性地写入 <path>（临时文件 + 重命名）
webhook:<url>	将输出正文 POST 到该 URL（使用 --compact 时，内容类型为 application/json 或 application/x-ndjson）

遇到未知方案时会拒绝执行，并返回结构化错误，列出受支持的方案。Webhook 失败会返回非零状态，并在 stderr 中记录 URL 和 HTTP 状态码。

命名配置

配置是保存的一组标志值，可在多次调用中重复使用。当计划任务中的 Agent 每次运行都以相同配置调用同一命令时，适合使用配置——这是 HeyGen 的“Beacon”模式。

suno-pp-cli profile save briefing --json
suno-pp-cli --profile briefing clips list
suno-pp-cli profile list --json
suno-pp-cli profile show briefing
suno-pp-cli profile delete briefing --yes

显式标志始终优先于配置值；配置值优先于默认值。agent-context 会在 available_profiles 下列出所有可用配置，让具备自省能力的 Agent 在运行时发现它们。

退出代码

代码	含义
0	成功
2	用法错误（参数错误）
3	未找到资源
4	需要身份验证
5	API 错误（上游问题）
7	请求过于频繁（等待后重试）
10	配置错误

参数解析

解析 $ARGUMENTS：

1. 为空、help 或 --help → 显示 suno-pp-cli --help 输出
2. 以 install 开头 → 以 mcp 结尾 → 安装 MCP；否则 → 参见上文的先决条件
3. 其他任何情况 → 直接使用（作为 CLI 命令执行，并带上 --agent）

MCP 服务安装

1. 安装 MCP 服务：

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

2. 在 Claude Code 中注册：

   claude mcp add suno-pp-mcp -- suno-pp-mcp
   

3. 验证：claude mcp list

直接使用

1. 检查是否已安装：which suno-pp-cli 如果未找到，则建议安装（参见本技能开头的先决条件）。
2. 将用户查询与上文“独特功能”和“命令参考”中的最佳命令匹配。
3. 使用 --agent 标志执行：

   suno-pp-cli <command> [subcommand] [args] --agent
   

4. 如果存在歧义，请查看子命令帮助：suno-pp-cli <command> --help。