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. 報告されたインストールディレクトリが、このスキルを実行するエージェント／ランタイムの $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 を使う場面

エージェントやスクリプトで Suno の音楽をプログラムから生成する場合、個人の Suno ライブラリをオフラインで管理・検索する場合、または型付き終了コードと JSON 出力を使って再現可能な生成／ポーリング／ダウンロードのパイプラインを実行する場合に、この CLI を使用してください。現在の Suno の仕様に追従し、すべてをローカルに保存するため、メンテナンスが放棄されたコミュニティ製ラッパーよりも適しています。

独自の機能

これらの機能は、この API を扱う他のツールでは利用できません。

Suno のツールにはないローカルライブラリ機能

• grep — ローカルの全文検索を使って、覚えている歌詞、プロンプト、タグのフレーズからクリップを検索します。

  エージェントがタイトルではなく内容から過去の特定の曲を探す必要がある場合に使用します。

  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 を直接実行します。

  決まったコマンドでは対応できない任意のクエリが必要な場合に使用します。

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

到達可能性の把握

• credits --forecast — 残りのクレジットと、直近の生成量を Suno の CAPTCHA によるスロットリングのしきい値と照らし合わせて表示します。

  バッチ処理を行う前に、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 — プラン／利用に関する 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>… — 1 件以上のクリップをゴミ箱に移動します（--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> — 直接の子（extend／cover）の数をカウントします

generate — 音楽、歌詞、動画の生成ジョブ

• suno-pp-cli generate create — 歌詞からカスタム曲を生成します（CAPTCHA による制限あり）。--variation high|normal|subtle、--project <id>。
• suno-pp-cli generate describe — 説明（インスピレーション）に基づいて生成します。--variation、--instrumental。

CAPTCHA による制限があるすべての generate コマンドでは、--wait-for-gate（--gate-timeout と併用。デフォルトは 30m）を指定できます。Suno の適応型ゲートが作動した場合（HTTP 422 token_validation_failed）、コマンドはゲートが再開するかタイムアウトに達するまで、待機してから再試行します。デフォルトでは無効です。自動ソルバーと併用すると、まずソルバーが実行され、残存するゲートには --wait-for-gate が対処します。また、--no-captcha の場合は、ブラウザーを使わないパッシブフォールバックを単独で実行します。--agent／JSON モードでは、ゲートエラーは stdout に error_type: "captcha_required" および retriable: true を含む構造化エンベロープとして出力されるため、エージェントは文章を解析するのではなく、フィールドに基づいて分岐できます。

• 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 をコーディングエージェントのスキルとしてインストールします

• 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 は少なくとも 1 つの一致が見つかったことを示します。終了コード 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 が captcha プロファイルを使って自動的に解決します。事前に解決したトークンを指定すれば、ブラウザーを使わずに済みます。

深くネストされたクリップを取得して必要な項目だけを選ぶ

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

クリップを取得し、エージェントに必要なフィールドだけに冗長なネストされたペイロードを絞り込んで、コンテキストを節約します。

オフラインでインストゥルメンタルを検索して順位付けする

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

残りのクレジットと最近の生成量を、captcha スロットルのしきい値と照らし合わせて表示します。

トラックをワークスペースに整理する

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 の場合、ブラウザーを表示するフォールバックは抑制され、構造化された {"error_type":"captcha_required","retriable":true} エンベロープが stdout に出力されます（終了コード 2）。自動解決機能を完全に無効にするには --no-captcha を指定するか、解決済みトークンを --token で渡してください。読み取り、ライブラリ、メタデータの各コマンドでは、CAPTCHA は不要です。

suno-pp-cli doctor を実行して設定を確認してください。ライブの生成制限を個別に確認するには --probe-gate を追加します。デフォルトのヘルスチェックで確認できるのは課金 API に接続できることだけであり、生成が制限されていても正常と判定されます。doctor --probe-gate は tripped（適応型 hCaptcha 制限が有効）または open を報告します。警告：このコマンドは実際に生成を行います。制限が発動している場合は無料ですが、制限が解除されている場合はクリップが作成され、クレジットが消費されます（プローブ用のクリップは可能な限り削除されます）。

エージェントモード

任意のコマンドに --agent を追加します。次のオプションが有効になります：--json --compact --no-input --no-color --yes。

• パイプ可能 — stdout に JSON、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 を参照してください。人間が読みやすい N results (live) の概要は、stdout が端末であり、かつ機械形式のフラグ（--json、--csv、--compact、--quiet、--plain、--select）が指定されていない場合に限り、stderr に出力されます。パイプ経由／エージェントによる利用時や、形式を明示した実行では、stdout には純粋な JSON のみが出力されます。

エージェントからのフィードバック

この 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 されることはありません。デフォルトではローカルにのみ保存されます。

バグ報告ではなく、意外だったことを書いてください。短く、具体的に、1 行で記録してください。積み重ねる価値があるのは、その部分です。

出力の配信先

すべてのコマンドで --deliver <sink> を指定できます。出力は stdout に加えて（または stdout の代わりに）指定した配信先へ送られるため、エージェントは手動でパイプをつなぐことなくコマンドの結果を振り分けられます。対応している配信先は 3 種類です：

配信先	動作
stdout	デフォルト。stdout のみに書き込みます
file:<path>	<path> に出力をアトミックに書き込みます（一時ファイルを作成してからリネームします）
webhook:<url>	出力本文を URL に POST します（--compact の場合は application/json または application/x-ndjson）

不明なスキームは、対応しているスキームを示す構造化エラーとともに拒否されます。Webhook の失敗時はゼロ以外の終了コードを返し、URL と HTTP ステータスを stderr に記録します。

名前付きプロファイル

プロファイルは、保存されたフラグ値のセットで、実行するたびに再利用できます。スケジュールされたエージェントが、同じ設定で毎回同じコマンドを呼び出す場合に使用します。これは、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 に一覧表示します。

終了コード

コード	意味
0	成功
2	使用エラー（引数が正しくありません）
3	リソースが見つかりません
4	認証が必要です
5	API エラー（上流の問題）
7	レート制限中（待機して再試行してください）
10	設定エラー

引数の解析

$ARGUMENTS を解析します。

1. 空、help、または --help → suno-pp-cli --help の出力を表示します
2. install で始まる場合 → mcp で終わる場合は MCP のインストール、それ以外の場合は上記の前提条件を参照します
3. それ以外 → 直接使用（--agent を付けて CLI コマンドとして実行します）

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。