pp-postman-explore

Postman Explore — Printing Press CLI

前提条件：CLI をインストールする

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

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

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

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

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

go install github.com/mvanhorn/printing-press-library/library/developer-tools/postman-explore/cmd/postman-explore-pp-cli@latest

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

この CLI を使用する場面

コミュニティが投稿した Postman コレクション／ワークスペース／API／フローをプログラムから検出、比較、または監視する必要がある場合は、この CLI を選択してください。ベンダーの代表的な Postman コレクションを探すよう依頼された AI エージェント、カテゴリ内の公開者を比較する API キュレーター、ネットワークの変化を監視するスクリプトに最適です。自身の非公開 Postman ワークスペースを管理する場合は、この CLI を使用しないでください。それには認証が必要な Postman 製品 API を使用しますが、これはまったく別のインターフェースです。

独自の機能

これらの機能は、この API 向けのほかのツールでは利用できません。

ローカルで広がる検出機能

• canonical — 1 つのコマンドでベンダーに最適なコミュニティ Postman コレクションを検索し、公開者の認証状況、フォーク数、最近の更新時期に基づいて順位付けします。

  ユーザーがエージェントにベンダーの Postman コレクションを尋ねたとき、検索結果の一覧を重複排除させることなく、1 回の呼び出しで最適な代表候補を返します。

  postman-explore-pp-cli canonical stripe --json
  

• top — カテゴリとエンティティの種類を絞り込んで、任意の指標（weekForks、monthViewCount など）でエンティティを順位付けします。

  エージェントが過去全期間の首位ではなく、今週最もフォークされたコレクションを推奨する必要がある場合、これが機能する唯一の方法です。

  postman-explore-pp-cli top --metric weekForkCount --type collection --category payments --limit 10
  

• similar — 数値のエンティティ ID を指定すると、名前、概要、カテゴリが重複するコレクションを返します。シードエンティティのテキストとの FTS 関連度スコアで順位付けされます。

  インテグレーターがコレクションを 1 つ見つけ、代替候補と比較したい場合、新たに検索する手間をかけず、1 回の呼び出しで競合候補を返します。

  postman-explore-pp-cli similar 10289 --limit 5 --json
  

比較分析

• publishers top — カテゴリ内の公開者ごとに、すべてのエンティティのフォーク数を集計し、コミュニティでの総合的な存在感に基づいてチームを順位付けします。

  ベンダー間で比較したい API キュレーターや、インテグレーションパートナーの候補を推奨するエージェントが、比較結果から選ぶ際に役立ちます。

  postman-explore-pp-cli publishers top --category developer-productivity --limit 5 --json
  

• category landscape — カテゴリのスラッグを指定すると、種類ごとのエンティティ総数、フォーク数の合計が多い公開者の上位 5 件、viewCount が多いエンティティの上位 5 件を返します。1 つのコマンドで、構造化されたデータをまとめて取得できます。

  決済、AI、DevOps などの分野を評価する API キュレーターは、どこが優勢で何が人気なのかを一目で把握したいものです。このコマンドは、まさにその全体像を提供します。

  postman-explore-pp-cli category landscape payments --json
  

期間指定のシグナル

• drift — API 側の updatedAt タイムスタンプが指定期間内にある、ローカルに同期済みのエンティティを報告します。

  最近更新されたベンダーのコレクションを追跡するエージェントは、定期的な sync の後にこれを利用します。これは指定期間内に更新されたものを表示する機能であり、2 つのスナップショット間で削除されたエンティティを差分表示するものではありません。

  postman-explore-pp-cli drift --since 7d --type collection --json
  

• velocity — 加速比（weekForkCount × 4）/ monthForkCount でコレクションを順位付けします。人気リストの上位に入る前に急成長するコレクションを見つけられます。

  人気順で上位に入る前に急成長するコレクションを見つけることは、新興ベンダーを追跡する API キュレーターにとって大きな価値があります。

  postman-explore-pp-cli velocity --type collection --top 10
  

品質シグナル

• browse — --verified-only を渡すと、browse コマンドは verified-team フラグが設定されているパブリッシャーが所有するエンティティに絞り込みます。

  コミュニティによるフォークではなく、公式ベンダーのコレクションだけが必要な場合に、最も簡潔なフィルターです。

  postman-explore-pp-cli browse collection --verified-only --category payments --json --limit 5
  

HTTP トランスポート

この CLI は、ブラウザー向けエンドポイントに Chrome 互換の HTTP トランスポートを使用します。通常の API 呼び出しに常駐ブラウザープロセスは必要ありません。

検出シグナル

この CLI は、ブラウザーで観測されたトラフィックのコンテキストをもとに生成されました。

• キャプチャ範囲：全 24 件のネットワークエントリーのうち、API エントリー 17 件
• プロトコル：rest_json（信頼度 60%）、rpc_envelope（信頼度 95%）
• 認証シグナル：なし
• 生成時のヒント：client_pattern:proxy-envelope, uses_browser_http_transport, no_auth_required, skip_clearance_cookie
• 生成されたコマンド一覧：browse; networkentity get-network-entity; networkentity get-network-entity-counts; category list-categories; category get; team get-workspaces; team get; search-all

コマンドリファレンス

category — カテゴリーを管理

• postman-explore-pp-cli category get — URL スラッグ（例：artificial-intelligence、developer-productivity、...）でカテゴリーの詳細をすべて返します。
• postman-explore-pp-cli category list-categories — API ネットワークの整理に使われているすべてのカテゴリー（例：AI、E コマース、コミュニケーション、DevOps）を返します。カテゴリー...

networkentity — ネットワークエンティティを管理

• postman-explore-pp-cli networkentity get-network-entity — 内部数値 ID（listNetworkEntities の id フィールド。entityId UUID ではありません）でエンティティの完全なレコードを返します。
• postman-explore-pp-cli networkentity get-network-entity-counts — 公開 API ネットワーク全体の集計数（コレクション、ワークスペース、API、フロー、ノートブックなど）を返します。
• postman-explore-pp-cli networkentity list-network-entities — 公開コレクション、ワークスペース、API、またはフローを一覧表示します。カテゴリーによるフィルタリング、ページネーション、最小フォーク数に対応しています...

search-all — すべてを検索

• postman-explore-pp-cli search-all — フリーテキストクエリでコレクション、ワークスペース、リクエスト、フロー、チームを検索します。queryIndices を設定しない場合は、...

team — API ネットワーク上のパブリッシャーチーム

• postman-explore-pp-cli team get — チームの小規模なプロフィールオブジェクト（id、name、description、publicHandle、profileURL、createdAt、updatedAt）を返します...
• postman-explore-pp-cli team get-workspaces — publicHandle（例：stripedev）で識別されるチームが所有する公開ワークスペースの配列を返します...

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

実行したいことは分かっていても、どのコマンドを使えばよいか分からない場合は、CLI に直接尋ねてください。

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

which は、自然言語による機能の問い合わせを、この CLI の厳選された機能インデックスから最適なコマンドに対応付けます。終了コード 0 は少なくとも 1 件一致したことを示し、終了コード 2 は確信を持てる一致がなかったことを示します。その場合は --help に切り替えるか、より絞り込んだクエリを使用してください。

レシピ

Stripe の公式コレクションを見つける

postman-explore-pp-cli canonical stripe --json --select id,name,publisher.publicHandle,metrics.forkCount

この標準コマンドは、検証済みパブリッシャーの中からフォーク数が最も多いものを選び、JSON をエージェントが実際に必要とする 4 つのフィールドに絞り込みます。

決済関連の主要パブリッシャーを比較する

postman-explore-pp-cli publishers top --category payments --limit 5 --json

決済カテゴリーにおける各パブリッシャーの全ポートフォリオのフォーク数を集計します。

今週ネットワークで何が変わったかを確認する

postman-explore-pp-cli sync --resources collection,workspace,api,flow,category && postman-explore-pp-cli drift --since 7d --type collection --json

同期してから、API 側の updatedAt が指定した期間内にあるコレクションをローカルストアにクエリします。

開発者の生産性向上に役立つ主要コレクションを参照し、検証済みパブリッシャーに絞り込む

postman-explore-pp-cli browse collection --category 4 --verified-only --limit 10 --json --select name,publisher.publicHandle,metrics.viewCount,redirectURL

ドット区切りのパスを指定して --select を使うと、レコードごとに約 5 KB ある指標配列全体の取得を避けられます。エージェントのコンテキストに対する出力を小さく保てます。

決済分野で勢いを増しているコレクションを見つける

postman-explore-pp-cli velocity --type collection --category payments --top 10

勢いのランキングは、週単位と月単位のフォーク率を比較します。これにより、通算人気ランキングの上位になる前に急成長しているコレクションを見つけられます。

シードに類似したコレクションを見つける

postman-explore-pp-cli similar 10289 --limit 5 --json

ローカルの FTS インデックスに対する類似検索です。競合するコミュニティコレクションや、相補的なコミュニティコレクションの発見に役立ちます。

カテゴリ全体のスナップショットを取得する

postman-explore-pp-cli category landscape payments --json

カテゴリの種類ごとの件数、上位のパブリッシャー、上位のエンティティを、1つの構造化されたペイロードにまとめます。

認証の設定

認証は不要です。

postman-explore-pp-cli doctorを実行して、設定を確認してください。

エージェントモード

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

• パイプで利用可能 — 標準出力にはJSON、標準エラー出力にはエラーを出力します

• フィルタリング可能 — --selectでフィールドを絞り込めます。ドット区切りのパスはネストされた構造をたどり、配列は各要素をたどります。詳細なAPIでコンテキストを小さく保つうえで重要です：

  postman-explore-pp-cli category get mock-value --agent --select id,name,status
  

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

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

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

レスポンスエンベロープ

ローカルストアまたはAPIからデータを読み取るコマンドは、出力を出所情報のエンベロープでラップします：

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

データを取得するには.resultsを解析し、ライブデータかローカルデータかを確認するには.meta.sourceを参照してください。人間が読みやすいN results (live)の概要は、標準出力が端末の場合にのみ標準エラー出力に表示されます。パイプやエージェントで利用する場合、標準出力には純粋なJSONが出力されます。

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

このCLIの問題に気づいた場合（エージェントが気づいた場合も含む）は、記録してください：

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

エントリーはローカルの~/.postman-explore-pp-cli/feedback.jsonlに保存されます。POSTMAN_EXPLORE_FEEDBACK_ENDPOINTが設定されており、かつ--sendが渡されるか、POSTMAN_EXPLORE_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ステータスを標準エラー出力に記録します。

名前付きプロファイル

プロファイルは保存済みのフラグ値のセットで、複数回の実行で再利用できます。スケジュールされたエージェントが毎回同じ設定で同じコマンドを呼び出す場合に使用します。これは、HeyGenの「Beacon」パターンです。

postman-explore-pp-cli profile save briefing --json
postman-explore-pp-cli --profile briefing category get mock-value
postman-explore-pp-cli profile list --json
postman-explore-pp-cli profile show briefing
postman-explore-pp-cli profile delete briefing --yes

明示的に指定したフラグは常にプロファイル値より優先され、プロファイル値はデフォルト値より優先されます。agent-contextは、実行時に情報を調べるエージェントが確認できるよう、すべてのプロファイルをavailable_profilesの下に一覧表示します。

終了コード

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

引数の解析

$ARGUMENTSを解析します：

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

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

1. MCP サーバーをインストールします：

   go install github.com/mvanhorn/printing-press-library/library/developer-tools/postman-explore/cmd/postman-explore-pp-mcp@latest
   

2. Claude Codeに登録します：

   claude mcp add postman-explore-pp-mcp -- postman-explore-pp-mcp
   

3. 確認します：claude mcp list

直接使用

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

   postman-explore-pp-cli <command> [subcommand] [args] --agent
   

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