pp-ebay

eBay — Printing Press CLI

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

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

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

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

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

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

go install github.com/mvanhorn/printing-press-library/library/commerce/ebay/cmd/ebay-pp-cli@latest

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

独自の機能

この API の他のツールでは、以下の機能を利用できません。

発見とインテリジェンス

• auctions — 入札数と終了までの時間で絞り込んで、開催中のオークションを検索します（例：「次の1時間以内に終了し、少なくとも3件の入札があるステフ・カリーのカード」）。2025年2月にFinding APIが廃止されたため、eBayサイトではこの検索に回答できなくなりました。

  直前の入札で実際に価格が動く、価格を見極めやすい競争状況を探します。

  ebay-pp-cli auctions "Steph Curry rookie" --has-bids --ending-within 1h --json --select item_id,price,bids,time_left
  

• comp — スマートマッチング、コンディションの正規化、外れ値の除外、パーセンタイル分布を用いて、任意の商品について過去90日間の平均販売価格を調べます。

  入札価格を決めるとき（あるいは入札する価値があるか判断するとき）には、単一の基準価格ではなく、直近の販売価格の現実的な分布が必要です。トリミングで外れ値を除外し、重複排除でタイトルの違いに対処します。

  ebay-pp-cli comp "Cooper Flagg /50 Topps Chrome" --trim --json --select mean,median,sample_size
  

• comp の外れ値トリミング — 販売済み商品の比較結果に対し、IQR の1.5倍を基準に外れ値を除外します。標準偏差と四分位数を併せて、購入者が参考にすべき現実的な価格帯を示します。

  通常の購入者が実際に支払った価格と、記録的な高値や投げ売りによる外れ値を見分けられます。

  ebay-pp-cli comp "Rolex Submariner 116610LN" --trim --json --select p25,median,p75,std_dev
  

• comp --dedupe-variants — ほぼ重複する販売済み出品を、フィンガープリント（語句の集合、語順は不問）ごとに代表例1件へまとめます。

  重複排除をしないと、同じカードを5回出品した販売者の出品によって、比較価格の分布が偏ります。

  ebay-pp-cli comp "Cooper Flagg /50" --dedupe-variants
  

• listings — オークション／BIN、コンディション、価格帯で絞り込んで、出品中の商品を検索します。

  ebay-pp-cli listings --nkw "PSA Mariners Griffey" --lh-bin 1 --udlo 10 --udhi 30
  

使用する場面

• ユーザーが「このカード／時計／商品はいくらで売れた？」と尋ねた場合 → ebay-pp-cli comp "<title>" --trim
• ユーザーが「入札があり、終了間近のオークションを探して」と尋ねた場合 → ebay-pp-cli auctions "<query>" --has-bids --ending-within 1h
• ユーザーが「…のXドル未満のBuy It Now出品を探して」と尋ねた場合 → ebay-pp-cli listings --nkw "<query>" --lh-bin 1 --udhi <max>
• ユーザーが「この出品をウォッチして」／「ウォッチリストを見せて」と尋ねた場合 → ebay-pp-cli watch list
• ユーザーがプログラムによる入札を求めた場合 → 制限事項を説明してください（eBayは /bfl/placebid で追加認証を要求します）。ブラウザーから入札するよう案内してください。代わりに bid または snipe を実行しないでください。

使用しない場面

このCLIは、以下には適していません。

• 入札の実行。 bid／snipe／bid-group は実験的で、最初から最後まで正常に動作しません。ブラウザーから入札するよう案内してください。
• 販売者としての商品出品（eBay Sell API／Seller Hubを直接使用してください）。
• 注文処理または配送ラベルの生成。
• 販売者向けの在庫の一括管理。

既知の制限事項

• 入札の実行（bid、snipe、bid-group）は、Cookie のみのセッションでは eBay が /bfl/placebid で追加認証を要求するため、最初から最後まで完了できません。これらのコマンドは既定の --help には表示されず、実行すると警告が出力されます。ユーザーはブラウザーから入札してください。
• レート制限：スクレイピングを続けると、eBay の403エラーが発生します。復旧するには ebay-pp-cli auth refresh を実行し、しばらく間隔を空けてください。
• スタブコマンド：ウォッチリストの書き込み操作、保存済み検索のCRUD、フィード、offer-hunterは、「未実装」のスタブとして提供されています。

HTTP トランスポート

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

検出シグナル

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

• キャプチャ範囲：全 25 件のネットワークエントリーのうち、API エントリー 15 件
• プロトコル：html_scraping（信頼度 95%）、rest_json（信頼度 90%）
• 認証シグナル：— Cookie：cid、s、nonsession、dp1、ebaysid、ds1、ds2、shs、npii
• 生成時のヒント：requires_browser_auth、requires_protected_client、uses_chrome_cookie_import、has_per_request_csrf、has_per_request_fraud_token
• 注意事項：placebid_step_up：eBay は Cookie のみのセッションで /bfl/placebid/ からサインインページにリダイレクトするため、現時点ではこの CLI から入札を完了できません。akami_active：Akamai のボット管理が有効です。Surf は Chrome の TLS フィンガープリントを使用する必要があり、標準ライブラリの HTTP はブロックされます。rate_limit：スクレイピングを継続すると 403 エラーが発生します。認証を更新して、アクセス頻度を下げてください。

コマンドリファレンス

deal — eBay Deals フィード

• ebay-pp-cli deal — eBay Deals フィードを閲覧します

item — 商品の詳細

• ebay-pp-cli item <itemId> — 出品 ID から商品詳細を取得します

listings — 出品中の商品を検索（/sch/i.html の HTML スクレイピング）

• ebay-pp-cli listings — キーワードで eBay の出品中の商品を検索します

sold — 販売済み／取引終了の出品（過去 90 日間、HTML スクレイピング）

• ebay-pp-cli sold — キーワードで販売済み／取引終了の商品を検索します（過去 90 日間）

watch — ウォッチリスト（認証が必要、読み取り専用）

• ebay-pp-cli watch — ユーザーのウォッチリストにある商品を一覧表示します

手書きのコマンド

• ebay-pp-cli comp <query> — 販売済み商品に関するインテリジェンス：過去 90 日間にクエリに一致した商品の平均販売価格、分布、トレンドラインを表示します。
• ebay-pp-cli auctions <query> — 入札数、終了までの時間、コンディションで絞り込んで、開催中のオークションを検索します。「次の 1 時間以内に終了し、入札がある商品」の検索に使えます。
• ebay-pp-cli feed <saved-search> — 保存済み検索に一致する新着商品をストリーミングし、各商品に販売済み商品情報を追加します。
• ebay-pp-cli history — 設定可能な期間の購入履歴（落札、落札失敗、支払い済み）を表示します。
• ebay-pp-cli saved-search — ローカルの保存済み検索を CRUD で管理します。

非表示の実験的なコマンド

これらのコマンドはバイナリに含まれていますが、現在エンドツーエンドで動作しないため、--help から除外されています。名前を指定して実行すると（例：ebay-pp-cli snipe --help）、詳細を確認できます。

• ebay-pp-cli bid — 入札します（実験的機能。eBay の追加認証によってブロックされます）。
• ebay-pp-cli snipe <itemId> --max <amount> — スナイパー入札を行います（実験的機能。入札フローに依存します）。
• ebay-pp-cli bid-group — 複数の商品を連携してスナイパー入札するグループを作成します（実験的機能。スナイパー入札に依存します）。

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

やりたいことは分かっているものの、それを実行するコマンドが分からない場合は、CLI に直接問い合わせてください。

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

which は、自然言語による機能の問い合わせを、この CLI の厳選された機能インデックスから最適なコマンドに対応付けます。終了コード 0 は少なくとも 1 件の候補が見つかったことを示します。終了コード 2 は信頼できる候補が見つからなかったことを示します。その場合は --help を参照するか、クエリをより具体的にしてください。

認証のセットアップ

この CLI はブラウザーのセッションを使用します。Chrome で .ebay.com にログインしてから、次を実行してください。

ebay-pp-cli auth login --chrome

Cookie 抽出ツール（pip 経由の pycookiecheat、または Homebrew 経由の cookies）が必要です。

ebay-pp-cli doctor を実行して、セットアップを確認してください。

エージェントモード

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

• パイプ対応 — JSON は stdout に、エラーは stderr に出力します

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

  ebay-pp-cli deal --agent --select id,name,status
  

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

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

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

レスポンスエンベロープ

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

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

データには .results を、ライブデータかローカルデータかの確認には .meta.source を解析してください。人間が読める N results (live) の要約は、stdout がターミナルの場合にのみ stderr に出力されます。パイプ接続時やエージェントによる利用時には、stdout に純粋な JSON が出力されます。

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

この CLI に気になる点があった場合（エージェントが気づいた場合も含む）、記録してください。

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

記録はローカルの ~/.ebay-pp-cli/feedback.jsonl に保存されます。EBAY_FEEDBACK_ENDPOINT が設定され、かつ --send が渡された場合、または EBAY_FEEDBACK_AUTO_SEND=true が設定された場合を除き、POST されることはありません。デフォルトではローカルにのみ保存されます。

バグ報告ではなく、意外に感じたことを書いてください。簡潔かつ具体的に、1 行で記録します。積み重ねにつながるのはその部分です。

出力の配信

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

シンク	効果
stdout	デフォルト。標準出力のみに書き込みます
file:<path>	出力を <path> にアトミックに書き込みます（tmp + rename）
webhook:<url>	出力本文を URL に POST します（--compact の場合は application/json または application/x-ndjson）

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

名前付きプロファイル

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

ebay-pp-cli profile save briefing --json
ebay-pp-cli --profile briefing deal
ebay-pp-cli profile list --json
ebay-pp-cli profile show briefing
ebay-pp-cli profile delete briefing --yes

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

終了コード

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

引数の解析

$ARGUMENTS を解析します。

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

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

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

   go install github.com/mvanhorn/printing-press-library/library/commerce/ebay/cmd/ebay-pp-mcp@latest
   

2. Claude Code に登録します。

   claude mcp add ebay-pp-mcp -- ebay-pp-mcp
   

3. 次のコマンドで確認します。claude mcp list

直接使用

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

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

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