pp-spotify

Spotify — Printing Press CLI

前提条件：CLI のインストール

このスキルは spotify-pp-cli バイナリを使用します。このスキルのコマンドを実行する前に、CLI がインストールされていることを必ず確認してください。インストールされていない場合は、先にインストールしてください。

1. Printing Press インストーラーを使ってインストールします。バイナリの保存先は、macOS/Linux では $HOME/.local/bin、Windows では %LOCALAPPDATA%\Programs\PrintingPress\bin がデフォルトです。

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

2. 確認します：spotify-pp-cli --version
3. 表示されたインストール先のディレクトリが、このスキルを実行するエージェント／ランタイムの $PATH に含まれていることを確認します。

npx でのインストールに失敗した場合（Node がない、オフラインなど）は、Go で直接インストールしてください（Go 1.26.6 以降が必要です）。

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

インストール後に --version で「command not found」と表示される場合、ランタイムからバイナリのディレクトリを $PATH 経由で参照できていません。確認に成功するまで、このスキルのコマンドを実行しないでください。

Spotify の Web API を使うと、音楽やポッドキャストの検索、Spotify ライブラリの管理、オーディオ再生の制御など、さまざまなことができます。利用可能な Web API エンドポイントは、左側のサイドバーから、または画面が小さい場合はページ上部のナビゲーションバーから確認できます。

Web API リクエストを正常に実行するには、アプリに有効なアクセストークンが必要です。トークンは OAuth 2.0 を通じて取得できます。

すべての Web API リクエストのベース URI は https://api.spotify.com/v1 です。

お困りですか？詳しくは Web API ガイドをご覧ください。または、質問したりほかの開発者と交流したりするには、Spotify for Developers コミュニティフォーラムをご利用ください。

コマンドリファレンス

albums — アルバムを管理

• spotify-pp-cli albums get-an — Spotify カタログから単一のアルバム情報を取得します。
• spotify-pp-cli albums get-multiple — Spotify ID で指定した複数のアルバムについて、Spotify カタログ情報を取得します。

artists — アーティストを管理

• spotify-pp-cli artists get-an — 一意の Spotify ID で指定した単一のアーティストについて、Spotify カタログ情報を取得します。
• spotify-pp-cli artists get-multiple — Spotify ID に基づいて複数のアーティストの Spotify カタログ情報を取得します。

audio-analysis — オーディオ分析を管理

• spotify-pp-cli audio-analysis <id> — Spotify カタログ内のトラックについて、詳細なオーディオ分析を取得します。

audio-features — オーディオ特徴量を管理

• spotify-pp-cli audio-features get — 一意の Spotify ID で指定した単一のトラックのオーディオ特徴量を取得します。
• spotify-pp-cli audio-features get-several — Spotify ID に基づいて複数のトラックのオーディオ特徴量を取得します。

audiobooks — オーディオブックを管理

• spotify-pp-cli audiobooks get-an — Spotify カタログから単一のオーディオブック情報を取得します。
• spotify-pp-cli audiobooks get-multiple — Spotify ID で指定した複数のオーディオブックについて、Spotify カタログ情報を取得します。

browse — ブラウズを管理

• spotify-pp-cli browse get-a-categories-playlists — 特定のカテゴリがタグ付けされた Spotify プレイリストの一覧を取得します。
• spotify-pp-cli browse get-a-category — Spotify 内の項目にタグ付けするための単一のカテゴリを取得します（たとえば、Spotify プレーヤーの「Browse」タブで使用されます）。
• spotify-pp-cli browse get-categories — Spotify 内の項目にタグ付けするためのカテゴリ一覧を取得します（たとえば、Spotify プレーヤーの「Browse」タブで使用されます）。
• spotify-pp-cli browse get-featured-playlists — Spotify のおすすめプレイリスト一覧を取得します（たとえば、Spotify プレーヤーの「Browse」タブに表示されます）。
• spotify-pp-cli browse get-new-releases — Spotify の「Browse」タブに掲載されている新しいアルバムのリリース一覧を取得します（たとえば、Spotify プレーヤーに表示されます）。

chapters — チャプターを管理

• spotify-pp-cli chapters get-a — 1 つのオーディオブックのチャプターについて、Spotify カタログ情報を取得します。
• spotify-pp-cli chapters get-several — Spotify ID で指定した複数のオーディオブックのチャプターについて、Spotify カタログ情報を取得します。

episodes — エピソードを管理します

• spotify-pp-cli episodes get-an — 一意の Spotify ID で指定した 1 つのエピソードについて、Spotify カタログ情報を取得します。
• spotify-pp-cli episodes get-multiple — Spotify ID に基づいて複数のエピソードの Spotify カタログ情報を取得します。

markets — マーケットを管理します

• spotify-pp-cli markets — Spotify を利用できるマーケットの一覧を取得します。

me — 自分を管理します

• spotify-pp-cli me add-to-queue — ユーザーの現在の再生キューで次に再生するアイテムを追加します。

• spotify-pp-cli me check-current-user-follows — 現在のユーザーが1人以上のアーティストまたは他のSpotifyユーザーをフォローしているかどうかを確認します。

• spotify-pp-cli me check-library-contains — 1つ以上のアイテムが現在のユーザーのライブラリにすでに保存されているかどうかを確認します。

• spotify-pp-cli me check-users-saved-albums — 1つ以上のアルバムが現在のSpotifyユーザーの「Your Music」ライブラリにすでに保存されているかどうかを確認します。

• spotify-pp-cli me check-users-saved-audiobooks — 1つ以上のオーディオブックが現在のSpotifyユーザーのライブラリにすでに保存されているかどうかを確認します。

• spotify-pp-cli me check-users-saved-episodes — 1つ以上のエピソードが現在のSpotifyユーザーの「Your Episodes」ライブラリにすでに保存されているかどうかを確認します。

• spotify-pp-cli me check-users-saved-shows — 1つ以上の番組が現在のSpotifyユーザーのライブラリにすでに保存されているかどうかを確認します。

• spotify-pp-cli me check-users-saved-tracks — 1つ以上のトラックが現在のSpotifyユーザーの「Your Music」ライブラリにすでに保存されているかどうかを確認します。

• spotify-pp-cli me create-playlist — 現在のSpotifyユーザーのプレイリストを作成します。

• spotify-pp-cli me follow-artists-users — 現在のユーザーを、1人以上のアーティストまたは他のSpotifyユーザーのフォロワーに追加します。注： このエンドポイントは非推奨です。

• spotify-pp-cli me get-a-list-of-current-users-playlists — 現在のSpotifyユーザーが所有またはフォローしているプレイリストの一覧を取得します。

• spotify-pp-cli me get-a-users-available-devices — ユーザーが利用できるSpotify Connectデバイスの情報を取得します。

• spotify-pp-cli me get-current-users-profile — 現在のユーザーの詳細なプロフィール情報（現在のユーザー名を含む）を取得します。

• spotify-pp-cli me get-followed — 現在のユーザーがフォローしているアーティストを取得します。

• spotify-pp-cli me get-information-about-the-users-current-playback — トラックまたはエピソード、再生位置、アクティブなデバイスなど、ユーザーの現在の再生状態に関する情報を取得します。

• spotify-pp-cli me get-queue — ユーザーのキューを構成するオブジェクトの一覧を取得します。

• spotify-pp-cli me get-recently-played — 現在のユーザーが最近再生したトラックを取得します。注： 現在、ポッドキャストのエピソードには対応していません。

• spotify-pp-cli me get-the-users-currently-playing-track — ユーザーのSpotifyアカウントで現在再生中のオブジェクトを取得します。

• spotify-pp-cli me get-users-saved-albums — 現在のSpotifyユーザーの「Your Music」ライブラリに保存されているアルバムの一覧を取得します。

• spotify-pp-cli me get-users-saved-audiobooks — 現在のSpotifyユーザーの「Your Music」ライブラリに保存されているオーディオブックの一覧を取得します。

• spotify-pp-cli me get-users-saved-episodes — 現在のSpotifyユーザーのライブラリに保存されているエピソードの一覧を取得します。

• spotify-pp-cli me get-users-saved-shows — 現在のSpotifyユーザーのライブラリに保存されている番組の一覧を取得します。

• spotify-pp-cli me get-users-saved-tracks — 現在のSpotifyユーザーの「Your Music」ライブラリに保存されている曲の一覧を取得します。

• spotify-pp-cli me get-users-top-artists — 算出された親和性に基づく、現在のユーザーのお気に入りアーティストを取得します。

• spotify-pp-cli me get-users-top-tracks — 算出された親和性に基づく、現在のユーザーのお気に入りトラックを取得します。

• spotify-pp-cli me pause-a-users-playback — ユーザーのアカウントで再生を一時停止します。このAPIはSpotify Premiumユーザーのみ利用できます。

• spotify-pp-cli me remove-albums-user — 現在のユーザーの「Your Music」ライブラリから1つ以上のアルバムを削除します。注： このエンドポイントは非推奨です。

• spotify-pp-cli me remove-audiobooks-user — Spotifyユーザーのライブラリから1つ以上のオーディオブックを削除します。注： このエンドポイントは非推奨です。

• spotify-pp-cli me remove-episodes-user — 現在のユーザーのライブラリから1つ以上のエピソードを削除します。注： このエンドポイントは非推奨です。

• spotify-pp-cli me remove-library-items — 現在のユーザーのライブラリから1つ以上のアイテムを削除します。

• spotify-pp-cli me remove-shows-user — 現在のSpotifyユーザーのライブラリから1つ以上の番組を削除します。注： このエンドポイントは非推奨です。

• spotify-pp-cli me remove-tracks-user — 現在のユーザーの「Your Music」ライブラリから1つ以上のトラックを削除します。注： このエンドポイントは非推奨です。

• spotify-pp-cli me save-albums-user — 現在のユーザーの「Your Music」ライブラリに1つ以上のアルバムを保存します。注： このエンドポイントは非推奨です。

• spotify-pp-cli me save-audiobooks-user — 現在のSpotifyユーザーのライブラリに1つ以上のオーディオブックを保存します。注： このエンドポイントは非推奨です。

• spotify-pp-cli me save-episodes-user — 現在のユーザーのライブラリに1つ以上のエピソードを保存します。注： このエンドポイントは非推奨です。

• spotify-pp-cli me save-library-items — 現在のユーザーのライブラリに1つ以上のアイテムを追加します。

• spotify-pp-cli me save-shows-user — 現在のSpotifyユーザーのライブラリに1つ以上の番組を保存します。注： このエンドポイントは非推奨です。

• spotify-pp-cli me save-tracks-user — 現在のユーザーの「Your Music」ライブラリに1つ以上のトラックを保存します。注： このエンドポイントは非推奨です。

• spotify-pp-cli me seek-to-position-in-currently-playing-track — ユーザーが現在再生中のトラックの指定した位置に移動します。

• spotify-pp-cli me set-repeat-mode-on-users-playback — ユーザーの再生のリピートモードを設定します。このAPIはSpotify Premiumユーザーのみ利用できます。

• spotify-pp-cli me set-volume-for-users-playback — ユーザーの現在の再生デバイスの音量を設定します。このAPIはSpotify Premiumユーザーのみ利用できます。

• spotify-pp-cli me skip-users-playback-to-next-track — ユーザーのキュー内の次のトラックにスキップします。このAPIはSpotify Premiumユーザーのみ利用できます。

• spotify-pp-cli me skip-users-playback-to-previous-track — ユーザーのキュー内の前のトラックにスキップします。このAPIはSpotify Premiumユーザーのみ利用できます。

• spotify-pp-cli me start-a-users-playback — ユーザーのアクティブなデバイスで新しいコンテキストの再生を開始するか、現在の再生を再開します。

• spotify-pp-cli me toggle-shuffle-for-users-playback — ユーザーの再生のシャッフルをオンまたはオフに切り替えます。このAPIはSpotify Premiumユーザーのみ利用できます。

• spotify-pp-cli me transfer-a-users-playback — 再生を新しいデバイスに転送し、任意で再生を開始します。このAPIはSpotify Premiumユーザーのみ利用できます。

• spotify-pp-cli me unfollow-artists-users — 現在のユーザーを、1人以上のアーティストまたは他のSpotifyユーザーのフォロワーから削除します。 playlists — プレイリストを管理

• spotify-pp-cli playlists change-details — プレイリストの名前と公開／非公開の状態を変更します。（当然ながら、ユーザーはそのプレイリストの所有者である必要があります。）

• spotify-pp-cli playlists get — Spotify ユーザーが所有するプレイリストを取得します。

recommendations — おすすめを管理

• spotify-pp-cli recommendations get — 指定されたシードエンティティの利用可能な情報に基づいておすすめを生成し、類似するものと照合します
• spotify-pp-cli recommendations get-genres — 利用可能なジャンルのシードパラメーター値の一覧を取得します

shows — 番組を管理

• spotify-pp-cli shows get-a — 一意の Spotify ID で識別される単一の番組について、Spotify カタログ情報を取得します。
• spotify-pp-cli shows get-multiple — Spotify ID に基づいて、複数の番組の Spotify カタログ情報を取得します。

spotify_web_search — Spotify ウェブ検索を管理

• spotify-pp-cli spotify-web-search — アルバム、アーティスト、プレイリスト、トラック、番組に関する Spotify カタログ情報を取得します

tracks — トラックを管理

• spotify-pp-cli tracks get — 一意の Spotify ID で識別される単一のトラックについて、Spotify カタログ情報を取得します。
• spotify-pp-cli tracks get-several — Spotify ID に基づいて、複数のトラックの Spotify カタログ情報を取得します。
• spotify-pp-cli tracks resolve — アーティスト名とタイトルからトラック URI を正確に 1 つ特定します。標準入力からトラックリスト全体を読み込みます。
• spotify-pp-cli tracks where — ライブラリ内のトラックが表示されるすべての場所（プレイリスト、保存済み、再生履歴、トップ）を表示します。

users — ユーザーを管理

• spotify-pp-cli users <user_id> — Spotify ユーザーの公開プロフィール情報を取得します。

トラックリストをプレイリストに変換する

/search はランキング形式のページを返しますが、その順位はタイトルの完全一致ではなく関連性に基づいています。そのため、ライブ版、リマスター版、カバー版が、指定したスタジオ録音より上位になることがよくあります。tracks resolve はこの再ランキングを担い（完全一致が正規化後の完全一致より優先され、正規化後の完全一致は前方一致より優先されます。また、指定したアーティストは常に別のアーティストより優先されます）、入力行ごとに URI を 1 つ出力します。そのため、曲ごとに検索したり、手書きで jq を使ったりする代わりに、3 つのコマンドでセットリストをプレイリストにできます。

# 1. Resolve the tracklist to URIs (one title per line on stdin).
pbpaste | spotify-pp-cli tracks resolve --artist Northlane --agent > resolved.json

# 2. Check what didn't resolve before creating anything.
jq -r '.results.results[] | select(.uri == null) | .query_title' resolved.json

# 3. Create the playlist and add the URIs.
PLAYLIST=$(spotify-pp-cli me create-playlist --name "Northlane / Milan" --agent \
  --select id | jq -r '.results.id')
spotify-pp-cli playlists items add-to-playlist "$PLAYLIST" --agent \
  --uris "$(jq -c '[.results.results[].uri | select(. != null)]' resolved.json)"

各行の match_kind は、どのように一致したか（exact、normalized、prefix、substring、または別のアーティストの録音だけが一致した場合の *_other_artist）を示すため、エージェントは人による確認が必要な行を判断できます。--fail-on-miss を追加すると、いずれかのタイトルを特定できなかった場合に終了コード 2 で終了します。

プレイリストの内容を読む：.track ではなく .item

playlists items get-playlists は Spotify の /playlists/{id}/items エンドポイントを呼び出します。このエンドポイントの各行では、トラックが item の下に格納されています。Spotify のドキュメントやほとんどのサンプルで説明されているのは、各行で track を使う旧式の /playlists/{id}/tracks エンドポイントです。そのため、ドキュメントからコピーした jq '.results.items[].track' は、ここでは気づかないうちに null を返します。.item を使ってください。

spotify-pp-cli playlists items get-playlists <playlist_id> --agent \
  | jq -r '.results.items[].item.name'

playlists tracks ... サブツリーは旧式の /tracks エンドポイントを対象としていますが、現在のアプリ認証情報では Spotify から HTTP 403 が返されます。playlists items ... サブツリーを優先してください。

適切なコマンドを見つける

やりたいことは分かっていても、どのコマンドを使うのか分からない場合は、CLI に直接問い合わせてください。

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

which は、自然言語で記述した機能に関する問い合わせを、この CLI が用意した機能インデックス内で最も一致するコマンドに対応付けます。終了コード 0 は 1 つ以上の候補があることを示し、終了コード 2 は確かな候補がないことを示します。その場合は --help を使うか、より絞り込んだ問い合わせをしてください。

認証の設定

spotify-pp-cli auth setup を実行すると、トークンを取得するための URL と手順が表示されます（URL を開くには --launch を追加してください）。次に、トークンを保存します。

spotify-pp-cli auth set-token YOUR_TOKEN_HERE

または、環境変数として SPOTIFY_OAUTH_2_0 を設定してください。

設定を確認するには、spotify-pp-cli doctor を実行してください。

エージェントモード

任意のコマンドに --agent を追加します。次のオプションに展開されます：--json --compact --no-input --no-color --yes。

• パイプ可能 — stdout には JSON、stderr にはエラーが出力されます。意図的な例外が 1 つあります。何にも一致しない --select は、解析する価値のあるデータである available_fields の診断情報を通常のエンベロープ内で stdout に書き込み、それとともに 1 行の説明を stderr に出力します。

• フィルター可能 — --select でフィールドのサブセットを保持します。ドット区切りのパスはネストされた構造をたどり、配列では各要素をたどります。プロジェクションは、ネストされたオブジェクトのエンベロープ（単一の範囲付きコレクションを包むオブジェクト）を通過してコレクションに到達するため、エンベロープキーを指定しなくてもラップされたペイロード内のフィールドにアクセスできます。詳細な API でコンテキストを小さく保つために重要です：

  spotify-pp-cli audio-analysis mock-value --agent --select id,name,status
  

  何にも一致しない --select は空の結果ではなくエラーです。CLI は終了コード 2 で終了し、全ペイロードにフォールバックする代わりに、利用可能なフィールドを示す診断情報を返します。パスは {meta, results} エンベロープではなく、データを起点とします。--select results.tracks.items.name ではなく、--select tracks.items.name と指定してください：

  spotify-pp-cli spotify-web-search --q "track:4D artist:Northlane" --type track \
    --json --select results.tracks.items.name
  # exit 2
  # {"results":{"error":"--select matched no fields","select":"results.tracks.items.name",
  #             "available_fields":["tracks","tracks.href","tracks.items", ...]}}
  

• プレビュー可能 — --dry-run で送信せずにリクエストを表示します

• オフラインに対応 — sync/search コマンドは、利用可能な場合にローカルの SQLite ストアを使用できます

• 非対話型 — プロンプトは表示されず、すべての入力はフラグで指定します

• 明示的な再試行 — すでに存在するものの作成を成功として扱う場合に限り --idempotent を使い、削除対象が存在しない場合を成功として扱う場合に限り --ignore-missing を使います

レスポンスエンベロープ

ローカルストアまたは 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 が出力されます。

エンベロープの保証：

• エンベロープはプリンターによって正確に 1 回だけ追加されます。results にさらに {meta, results} のネストされたラッパーが含まれることを想定しないでください。また、meta.source は常にデータの実際の取得元を示します。
• 実際の POST/PUT/DELETE を送信するコマンドは、どの出力経路でも source: "live" を報告します。
• 単一オブジェクトのエンドポイント（artists get-an、albums get-an、...）は、ネストされた断片ではなく、リソース全体を results に返します。
• 複数タイプのライブ検索でタイプごとのエラーが発生した場合、成功したタイプは保持され、不完全な結果セットは meta.reason に報告されます。不完全な検索を網羅的なものとして扱う前に、meta.reason を確認してください。

ライブ検索

search <query> は、type パラメーターを必要とする Spotify のライブ /search エンドポイントを呼び出します。CLI は要求されたタイプ（デフォルトではカタログ内のすべてのタイプ、または --type で指定された 1 つのタイプ）を解決して明示的に送信し、データが入力されたすべてのタイプ別レスポンスを集約します。Spotify がライブエンドポイントを提供していないタイプ（例：me、chapters）はローカル専用です。--data-source live を指定してこれらを要求すると、終了コード 2 で即座に失敗し、利用可能な代替手段（local または auto）を示します。

パスと状態

エージェントは、CLI のパス解決機能をランタイム契約の一部として扱う必要があります。

• 1 回の実行で指定する場合は --home <dir> を使用し、4 種類すべてのパスを 1 つのルートの下に移動する場合は SPOTIFY_HOME=<dir> を設定します。

• 特定の種類だけを別の場所にする必要がある場合に限り、種類ごとの環境変数を使用します：SPOTIFY_CONFIG_DIR、SPOTIFY_DATA_DIR、SPOTIFY_STATE_DIR、SPOTIFY_CACHE_DIR。

• 解決順序は、種類ごとの環境変数、--home、SPOTIFY_HOME、XDG（XDG_CONFIG_HOME、XDG_DATA_HOME、XDG_STATE_HOME、XDG_CACHE_HOME）、プラットフォームのデフォルト設定です。

• config には config.toml やプロファイルなどの設定が含まれます。data には credentials.toml、data.db、Cookie、認証サイドカーが含まれます。state には永続化されたクエリ、ジョブ、teach.log が含まれます。cache には再生成可能な HTTP／キャッシュファイルが含まれます。

• 保存されたシークレットは、data ディレクトリ内の credentials.toml に格納されます。既存の従来形式の config.toml 内のシークレットは互換性のために読み込まれ、最初の認証書き込み時に config.toml から削除されます。

• spotify-pp-cli doctor --fail-on warn を実行すると、パスと認証情報の保存場所に関する警告を確認できます。解決されたディレクトリを必要とするエージェント向けに、agent-context はスキーマ v4 の paths ブロックを提供します。

• MCP の場合は、MCP ホストの設定を通じて移動先を指定します。MCP バイナリは CLI フラグを継承しません。

  {
    "mcpServers": {
      "spotify": {
        "command": "spotify-pp-mcp",
        "env": {
          "SPOTIFY_HOME": "/srv/spotify"
        }
      }
    }
  }
  

フリートでの優先順位：継承された種類ごとの環境変数は、その種類について明示的な --home より優先されます。フリート全体で継続的に使用する設定には SPOTIFY_HOME または種類ごとの環境変数を使い、--home は単一の実行に限って使用してください。環境変数を解除しても、移動は元に戻りません。SPOTIFY_HOME を解除する前にファイルを手動で移動してください。そうしないと、doctor は以前のルートに残された認証情報を見つけられません。

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

あなた（またはエージェント）がこの CLI の気になる点に気づいたら、記録してください。

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

エントリーは、解決された data ディレクトリ内の feedback.jsonl にローカル保存されます。SPOTIFY_FEEDBACK_ENDPOINT が設定され、かつ --send が渡されるか SPOTIFY_FEEDBACK_AUTO_SEND=true が設定されている場合を除き、POST されることはありません。デフォルトの動作はローカルのみです。

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

出力の配信

すべてのコマンドで --deliver <sink> を指定できます。出力は標準出力に加えて（または標準出力の代わりに）指定した出力先へ送られるため、エージェントはコマンド結果を手動でパイプ処理せずに振り分けられます。次の 3 種類の出力先に対応しています。

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

不明なスキームは、サポート対象を示す構造化エラーとともに拒否されます。Webhook の失敗時はゼロ以外の終了コードが返され、URL と HTTP ステータスが標準エラー出力に記録されます。

名前付きプロファイル

プロファイルは、実行のたびに再利用されるフラグ値の保存セットです。スケジュール実行や定期実行を行うエージェントが、実行ごとに異なる入力を受け取りながら同じフラグを再利用する場合に使います。

spotify-pp-cli profile save briefing --json
spotify-pp-cli --profile briefing audio-analysis mock-value
spotify-pp-cli profile list --json
spotify-pp-cli profile show briefing
spotify-pp-cli profile delete briefing --yes

明示的なフラグは常にプロファイルの値より優先され、プロファイルの値はデフォルト設定より優先されます。agent-context は available_profiles の下にすべての利用可能なプロファイルを一覧表示するため、情報を調べるエージェントは実行時にプロファイルを検出できます。

終了コード

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

引数の解析

$ARGUMENTS を解析します。

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

MCP サーバーのインストール

この CLI の公開ライブラリのエントリーまたはビルド済みリリースから MCP バイナリをインストールし、登録します。

claude mcp add spotify-pp-mcp -- spotify-pp-mcp

確認：claude mcp list

直接使用

1. インストール済みか確認します：which spotify-pp-cli 見つからない場合は、インストールを提案します（このスキルの冒頭にある前提条件を参照してください）。
2. ユーザーの問い合わせに最適なコマンドを、上記の「独自の機能」と「コマンドリファレンス」から選びます。
3. --agent フラグを付けて実行します：

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

4. 曖昧な場合は、サブコマンドのヘルプを確認します：spotify-pp-cli <command> --help。