pp-shopping

ショッピング — Printing Press CLI

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

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

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

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

2. 確認します：shopping-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/commerce/shopping/cmd/shopping-pp-cli@latest

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

Shopping は、LemmeBuyIt の集約型小売 API（70 以上の小売業者にまたがる 1 億 1,500 万点以上の商品）を利用し、ほかのツールにはないローカル SQLite レイヤーを追加します。index は商品と価格履歴を同期し、compare は共通の識別子を使って最安の小売業者を見つけます。deals は複数の店舗を対象に、割引率／価格／評価／在庫を組み合わせたクエリを実行します。arbitrage は Amazon FBA の再販利益率をランキングし、price-drops は週間の値下がりを表示し、leaderboard は割引率の区分ごとにランキングします。エージェント向けのネイティブな --json／--select、オフライン検索、型付き終了コードを備えています。

この CLI を使用する場面

エージェントがすばやく回答する必要のある、小売業者をまたいだ商品関連タスクには Shopping を使用してください。UPC を指定して最安の小売業者を探す、割引率や価格のしきい値を満たす在庫ありのお得な商品を見つける、週間の値下がり幅が大きい商品をランキングする、Amazon FBA の再販利益率を評価するといった用途に適しています。最初に一度同期しておけば、ローカルストアに対して複合クエリを繰り返し実行できる点が特に優れています。

使用しない場面

次の用途には、この CLI を使用しないでください。

• 注文、カートへの追加、決済には使用しないでください。読み取り専用のデータ API です。
• 小売以外のデータや、単一の小売業者独自の注文管理 API には使用しないでください。
• リアルタイムの価格照会には使用しないでください。ストアを参照するクエリは、現在の店頭価格ではなく、最後に index で同期した時点のデータを返します。

独自の機能

これらの機能は、この API を利用するほかのツールでは使用できません。

蓄積されるローカル状態

• index — 1 つ以上の小売業者から商品（および任意で価格履歴）を高速なローカル SQLite ストアに取り込みます。これにより、ほかのすべてのクエリを即座にオフラインで実行できます。

  まずはこちらを実行してください。compare／deals／arbitrage／analytics コマンドはすべて、index が取り込んだデータを読み取ります。

  shopping-pp-cli index --retailer walmart --retailer target --on-sale --limit 500
  

• watch status — 気になる商品を登録し、インデックスを更新するたびに、どの商品がどれだけ値動きしたか、目標価格に達したかを確認できます。

  厳選した商品の変化を前回の観測時点と比べたい場合に使用します。毎回データを再取得して価格を目視で確認する必要はありません。

  shopping-pp-cli watch status --json
  

小売業者をまたいだインテリジェンス

• compare — 同期済みの小売業者のうち、UPC／EAN／GTIN／ASIN で特定される同一商品を最も安く販売している業者を、価格差とともにランキング形式で表示します。

  小売業者ごとに N 回検索する代わりに、1 回の呼び出しで「どこが最安か」に答える場合に使用します。

  shopping-pp-cli compare 012345678905 --lookup-type upc --in-stock --json
  

• deals — 大幅な割引、価格上限以下、高評価、在庫ありといった複数の条件を同時に満たすお得な商品を、追跡対象のすべての小売業者から取得し、ランキング形式で表示します。

  商品データをそのまま並べるのではなく、人が確認する価値のあるお得な商品をエージェントが見つける必要がある場合に選択してください。

  shopping-pp-cli deals --min-discount 30 --max-price 100 --min-rating 4 --in-stock --sort discount --json
  

収益性

• arbitrage — 紹介料と FBA 手数料を差し引いた Amazon での再販利益に基づいて、同期済みの商品をランキングします。ROI と購入価格で絞り込めます。

  クリアランス商品の中から、再販 ROI の基準を実際に満たす商品だけに絞り込む場合に使用します。

  shopping-pp-cli arbitrage --retailer walmart --min-roi 30 --max-buy-price 50 --in-stock --json
  

時系列分析

• price-drops — 同期済みのすべての商品を対象に、過去1週間（またはN週間）で最も値下がりした商品を、値下がり額と値下がり率の両方でランキングします。

  各商品の履歴を手作業で再取得する代わりに、まず新たな値下げを見つける際に使います。

  shopping-pp-cli price-drops --weeks 1 --min-drop-pct 15 --limit 25 --json
  

• leaderboard — 同期済みデータを対象に、平均割引率、セール中の商品数、平均価格で、最も割引率が高い状態が続いている小売業者とカテゴリーを表示します。

  お得な商品を探す際に、どの小売業者やカテゴリーを最初にスキャンするか決めるのに使います。

  shopping-pp-cli leaderboard --by avg-discount --limit 15 --json
  

コマンドリファレンス

amazon — Amazon を管理します

• shopping-pp-cli amazon <asin> — 特定のASINについて、グラフ表示に対応したAmazon側の週次時系列データを返します。amazon_price_historyに直接アクセスします。

retailers — 小売業者とその商品の操作を行います。

• shopping-pp-cli retailers — 認証済みのAPIキーでアクセスできる小売業者の一覧を取得します。

status — APIのヘルスチェックとステータス確認を行います。

• shopping-pp-cli status — データベースへの接続状況を含む、APIサービスの現在の稼働状況を表示します。

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

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

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

whichは、自然言語で記述された機能の問い合わせを、このCLIの厳選された機能インデックスから最適なコマンドに対応付けます。終了コード0は少なくとも1件の一致があることを示し、終了コード2は確度の高い一致がないことを示します。その場合は--helpにフォールバックするか、より範囲を絞った問い合わせを使用してください。

レシピ

UPCで最安の小売業者

shopping-pp-cli compare 012345678905 --lookup-type upc --in-stock --json --select results.retailer_id,results.current_price

エージェントが実行に必要とする2つのフィールドに絞って、小売業者を横断して比較します。

在庫のあるお買い得商品

shopping-pp-cli deals --min-discount 40 --max-price 75 --in-stock --sort discount --limit 20 --json

同期済みストア全体を対象に、割引率でランキングする、割引・価格・在庫の複合クエリです。

FBA裁定取引の候補リスト

shopping-pp-cli arbitrage --retailer walmart --min-roi 30 --max-buy-price 50 --json --select results.product_name,results.roi,results.net_margin

判断に必要なフィールドだけを選択し、ROIで再販候補をランキングします。

今週の最大値下がり商品

shopping-pp-cli price-drops --weeks 1 --min-drop-pct 20 --limit 25 --json

同期済みのすべての商品を対象に、週次の時系列差分でランキングします。

認証の設定

すべてのリクエストでX-API-Keyヘッダーに単一のLemmeBuyIt APIキーを送信して認証します（SHOPPING_API_KEYを設定するか、shopping-pp-cli auth set-token <key>を実行します）。無料キーでは/shopping/の商品機能を利用でき、有料キーではさらに、商品検索全体、週次価格履歴、Amazon ASIN履歴、およびarbitrageを支えるAmazonの収益性データを利用できます。キーはhttps://www.lemmebuyit.com/developer で取得してください。

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

エージェントモード

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

• パイプ可能 — stdoutにはJSON、stderrにはエラーを出力します

• フィルター可能 — --selectでフィールドを絞り込めます。ドット付きパスはネストされた構造をたどり、配列は要素ごとに処理します。出力の多いAPIでコンテキストを小さく保つために重要です。

  shopping-pp-cli retailers --agent --select id,name,status
  

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

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

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

• 読み取り専用 — 作成、更新、削除、公開、コメント、賛成票、招待、注文、送信、その他の変更を伴うリクエストには、このCLIを使用しないでください

レスポンスエンベロープ

ローカルストアまたは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 に違和感を覚えたら、記録してください。

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

記録はローカルの ~/.local/share/shopping-pp-cli/feedback.jsonl に保存されます。SHOPPING_FEEDBACK_ENDPOINT が設定され、かつ --send が渡されるか、SHOPPING_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」パターンです。

shopping-pp-cli profile save briefing --json
shopping-pp-cli --profile briefing retailers
shopping-pp-cli profile list --json
shopping-pp-cli profile show briefing
shopping-pp-cli profile delete briefing --yes

明示的に指定したフラグは常にプロファイル値より優先され、プロファイル値はデフォルト値より優先されます。agent-context は、実行時に調査するエージェントがプロファイルを見つけられるよう、available_profiles に利用可能なすべてのプロファイルを一覧表示します。

終了コード

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

引数の解析

$ARGUMENTS を解析します。

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

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

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

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

2. Claude Code に登録します。

   claude mcp add shopping-pp-mcp -- shopping-pp-mcp
   

3. 確認します。claude mcp list

直接使用

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

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

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