pp-shopify

Shopify — Printing Press CLI

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

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

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

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

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

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

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

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

この CLI を使用しないケース

作成、更新、削除、公開、コメント、賛成票の投票、招待、注文、メッセージ送信、予約、購入、またはリモートの状態変更が必要なリクエストでは、この CLI を有効にしないでください。この CLI で利用できるのは、調査、エクスポート、同期、分析を行う読み取り専用コマンドです。

コマンドリファレンス

abandoned-checkouts — 回復キャンペーンやカート放棄分析に使用する、Shopify の放棄されたチェックアウトです。

• shopify-pp-cli abandoned-checkouts get — GraphQL ID を指定して、Shopify の放棄されたチェックアウトを 1 件取得します。
• shopify-pp-cli abandoned-checkouts list — Shopify Admin GraphQL API から、放棄されたチェックアウトの一覧を取得します。

customers — 生涯注文数、生涯利用額、連絡先フィールドを含む Shopify の顧客です。

• shopify-pp-cli customers get — GraphQL ID を指定して、Shopify の顧客を 1 人取得します。
• shopify-pp-cli customers list — Shopify Admin GraphQL API から、顧客の一覧を取得します。

fulfillment-orders — 遅延、ルーティング、フルフィルメント状態の分析に使用する、Shopify のフルフィルメント注文です。

• shopify-pp-cli fulfillment-orders get — GraphQL ID を指定して、Shopify のフルフィルメント注文を 1 件取得します。
• shopify-pp-cli fulfillment-orders list — Shopify Admin GraphQL API から、フルフィルメント注文の一覧を取得します。

inventory-items — 追跡状態とロケーションごとの利用可能数量を含む Shopify の在庫アイテムです。

• shopify-pp-cli inventory-items get — GraphQL ID を指定して、Shopify の在庫アイテムを 1 件取得します。
• shopify-pp-cli inventory-items list — Shopify Admin GraphQL API から、在庫アイテムの一覧を取得します。

orders — 金額の合計、財務状態、フルフィルメント状態を含む Shopify の注文です。

• shopify-pp-cli orders get — GraphQL ID を指定して、Shopify の注文を 1 件取得します。
• shopify-pp-cli orders list — Shopify Admin GraphQL API から、注文の一覧を取得します。

products — 商品ステータス、カタログメタデータ、簡潔なバリアント在庫情報を含む Shopify の商品です。

• shopify-pp-cli products get — GraphQL ID を指定して、Shopify の商品を 1 件取得します。
• shopify-pp-cli products list — Shopify Admin GraphQL API から、商品の一覧を取得します。

Freshness Contract

この CLI で表示されるコマンドは、登録済みのストアベースの読み取りコマンドパスに限り、範囲を限定した鮮度管理を行います。--data-source auto モードでは、これらのパスは sync_state を確認し、ローカルデータを読み取る前に範囲を限定した更新を実行する場合があります。--data-source local では更新を行いません。--data-source live では API を読み取り、ローカルストアを変更しません。データソースの選択を変えずに鮮度チェックをスキップするには、SHOPIFY_NO_AUTO_REFRESH=1 を設定してください。

対象パス：

• shopify-pp-cli abandoned-checkouts
• shopify-pp-cli abandoned-checkouts get
• shopify-pp-cli abandoned-checkouts list
• shopify-pp-cli abandoned-checkouts search
• shopify-pp-cli customers
• shopify-pp-cli customers get
• shopify-pp-cli customers list
• shopify-pp-cli customers search
• shopify-pp-cli fulfillment-orders
• shopify-pp-cli fulfillment-orders get
• shopify-pp-cli fulfillment-orders list
• shopify-pp-cli fulfillment-orders search
• shopify-pp-cli inventory-items
• shopify-pp-cli inventory-items get
• shopify-pp-cli inventory-items list
• shopify-pp-cli inventory-items search
• shopify-pp-cli orders
• shopify-pp-cli orders get
• shopify-pp-cli orders list
• shopify-pp-cli orders search
• shopify-pp-cli products
• shopify-pp-cli products get
• shopify-pp-cli products list
• shopify-pp-cli products search

JSON 出力で生成された来歴エンベロープが使われる場合、鮮度メタデータは meta.freshness に表示されます。これは対象コマンドパスにおける現在のキャッシュの鮮度を示すものであり、過去データの完全なバックフィルや API 固有のデータ拡充を保証するものではありません。

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

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

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

which は、自然言語で指定した機能に関する問い合わせを、この CLI の厳選された機能インデックスから最も適合するコマンドに対応付けます。終了コード 0 は一致する候補が少なくとも 1 つあることを示し、終了コード 2 は確度の高い候補がないことを示します。その場合は --help を確認するか、より具体的な問い合わせを使用してください。

手書きの拡張機能

これらのコマンドは仕様の作成者が宣言したもので、別途手書きの配線が必要です。ジェネレーターはこれらの Cobra 登録を生成しません。見つけやすいようにここに記載しており、verify-skill の未知のコマンドチェックでジェネレーターが管理するパスとして扱われないよう、意図的に ## Command Reference の外に配置しています。

• shopify-pp-cli bulk-operations — Shopify Admin GraphQL の一括操作を実行、ポーリング、調査します。
• shopify-pp-cli store daily-brief — ローカルストアの売上、売上上位商品、リスクチェック、推奨アクションをまとめた経営層向け日次ブリーフを作成します。
• shopify-pp-cli store audit — 返金、フルフィルメントリスク、配送の異常、滞留在庫に基づいて健全性スコアを算出します。
• shopify-pp-cli growth campaign-brief — 売上上位商品、VIP 顧客、再購入促進の機会に基づいたデータ主導のキャンペーンブリーフを作成します。
• shopify-pp-cli growth winback-candidates — 購買から遠ざかっている顧客を顧客生涯価値と推奨する再購入促進の切り口でランク付けします。
• shopify-pp-cli growth vip-segments — 支出額、購入頻度、直近の購入時期に基づいて高価値顧客をセグメント化します。
• shopify-pp-cli ops fulfillment-risk — 指定した期間を超えて未完了のフルフィルメント注文を見つけます。
• shopify-pp-cli ops shipping-anomalies — 同期済みの配送明細から、送料が無料、不足、高額なものを見つけます。
• shopify-pp-cli merchandising bundle-opportunities — 併売による売上増加率と確度に基づいて、バンドルを提案します。
• shopify-pp-cli merchandising dead-stock-actions — 最近販売されていない在庫を、値下げやバンドルのアクションにつなげます。
• shopify-pp-cli merchandising launch-brief — ローカルデータに基づいて、商品の発売または再発売のブリーフを作成します。

認証の設定

shopify-pp-cli auth setup を実行すると、キーの取得先 URL と手順が表示されます（URL を開くには --launch を追加してください）。次に、以下を設定します。

export SHOPIFY_ACCESS_TOKEN="<your-key>"

または、~/.config/shopify-pp-cli/config.toml に保存してください。

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

エージェントモード

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

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

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

  shopify-pp-cli abandoned-checkouts list --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 に問題があることに（あなた、またはエージェントが）気づいたら、記録してください：

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

エントリーは ~/.local/share/shopify-pp-cli/feedback.jsonl にローカル保存されます。SHOPIFY_FEEDBACK_ENDPOINT が設定され、かつ --send が渡されるか SHOPIFY_FEEDBACK_AUTO_SEND=true が設定されている場合を除き、POST されることはありません。デフォルトの動作はローカル保存のみです。

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

出力の配信

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

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

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

名前付きプロファイル

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

shopify-pp-cli profile save briefing --json
shopify-pp-cli --profile briefing abandoned-checkouts list
shopify-pp-cli profile list --json
shopify-pp-cli profile show briefing
shopify-pp-cli profile delete briefing --yes

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

終了コード

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

引数の解析

$ARGUMENTS を解析します：

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

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

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

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

2. Claude Code に登録します：

   claude mcp add shopify-pp-mcp -- shopify-pp-mcp
   

3. 確認します：claude mcp list

直接利用

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

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

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