shoplazza-common

shoplazza CLI — 共通基盤（shoplazza-common）

このスキルは、すべてのドメインスキル（shoplazza-discounts、shoplazza-products、…）の基盤です。ドメインをまたぐ仕組みをすべて担うため、ドメインスキル側で同じ内容を繰り返す必要はありません。また、すべてのドメインスキルは、このファイルを最初に読むよう求めています。コマンドとパラメーターの正式な情報源は shoplazza <svc> <cmd> --help と shoplazza schema です。このファイルでは仕組みを説明しており、フラグを網羅しているわけではありません。

ユーザーの言語で回答してください。 スキルの説明文は英語ですが、回答言語を指定するものではありません。質問への回答、確認のための書き直し、エラーの説明を含め、ユーザーに合わせてください（中文提问 → 中文回答）。CLI コマンド、フラグ、フィールド名はそのまま記載してください（翻訳しないでください）。

アクセス階層

すべての操作は、適用可能な最上位の階層から始め、要件を満たす方法が見つかった時点で終了してください。

階層	形式	使用する場面
1. ショートカット	shoplazza <svc> +<verb> [named flags]	第一候補です。名前付きフラグ、スマートな既定値、構造化されたエラーを備えています。
2. Spec リーフ	shoplazza <svc> <cmd> --params '{…}' [--data '{…}']	ショートカットがないエンドポイントに使用します。1つのエンドポイントにつき1つのコマンドです。
3. api rest	shoplazza api rest <METHOD> <PATH>	生のフォールバックで、すべてをカバーします。最初の2つの方法では実行できない場合にのみ使用してください。

shoplazza <svc> --help では、+ が付いた項目がショートカットで、それ以外は Spec リーフです。

出力形式（.data ラッパー）

すべてのコマンドに共通する構造化出力の仕様です。

• 成功 → stdout：{"ok":true,"data":<body>}
• 失敗 → stderr：{"ok":false,"error":{"type":…,"message":…}}、終了コードはゼロ以外です。

レスポンス本文は .data の下にネストされます。そのため、すべての jq パスは .data から始まります（例：.data.products[].id）。.data のプレフィックスを付け忘れるのが、最もよくある抽出ミスです。

例外 — ローカルコマンドにはラッパーがありません。 auth status / auth scopes / profile list は、オブジェクトをトップレベルに出力します（{ok,data} はなく、--jq もサポートされません）。フィールドを直接参照してください（例：logged_in）。

共通フラグ

フラグ	説明
--dry-run	送信せずに、送信されるリクエストを出力します。破壊的操作／一括操作／金銭が発生する書き込みでは、必ず最初に --dry-run を使用してください。読み取りコマンドとショートカットでも使用できます。
-q, --jq <expr>	jq 式で JSON 出力をフィルタリングします。既定ではスカラーをそのまま出力します（囲みの引用符は付かず、末尾に改行のみ付加されます）。-r は追加しないでください。cobra は -r を別のフラグとして解析し、コマンドを拒否します。これは単一文字列のフラグです。
--fields <f1,f2,…>	一部のショートカットのみで使用できるレスポンスフィールドの選択機能です。確認済み：products +search（カンマ区切り：products +search --fields id,title）。すべてのコマンドで使えるわけではありません。ほとんどのコマンドには --fields がありません。使用前に <shortcut> --help を確認してください。指定する名前はレスポンスのキーです。サーバーが追加の基本フィールドを返す場合があり、未知の名前はエラーにならず無視されます。
--page-limit <n>	一覧表示ショートカットのページサイズです。範囲は1～250です。API の既定値は10です。下記の「絞り込んだ一覧の読み取り」を参照してください。
--format json|pretty|table	出力形式です。既定値は json です。スクリプトや jq では json、人が読む場合は pretty／table を使用してください。グローバルフラグです。
--profile <name>	この呼び出しで使用するプロファイルです（「Profiles」を参照）。グローバルフラグです。

フィールドの選択：一部の検索ショートカットでは --fields を使用できます（--help で確認してください）。それ以外の場合は、--jq で選択／フィルタリングしてください。

フィルター適用済みリストの読み取り

{"ok":true,…} を返す読み取り結果は、指定したフィルターやページが実際に適用されたことを示す証拠にはなりません。エラーにならずに起きる失敗が 2 種類あり、どちらもエラーではなく、確信を持った誤った回答につながります。

1. 切り捨て — ページのデフォルトは 10 件です。 リストのエンドポイントは、--page-limit で指定しない限り 10 件を返します（最大 250 件）。残りは has_more / cursor で示されます。has_more は false ではなく null を返す場合があるため、true でなければ終了とみなしてください。回答が完全性に依存する場合（「いくつ」「どれ」「X のすべて」、自分で集計する合計など）は、--page-limit 250 を渡してカーソルをたどってください。単純な件数を知りたい場合は、行を数えるよりも、そのドメインの +count ショートカットを優先してください。

2. フィルターが黙って無視される — API は認識できないクエリパラメーターを無視します。 400 エラーにはなりません。パラメーター名が変更されたフラグを使うと、フィルターが適用されていない結果が 200 で返り、「この顧客は本当にこれだけの注文をしている」という結果に見えます。

そのため、フィルター適用済みの読み取り結果を回答に使ったり、書き込みに渡したりする前に、フィルターが適用されたことを確認してください。

shoplazza <svc> +search --<filter> <value> --dry-run   # 1. which param actually goes on the wire
shoplazza <svc> +count                                  # 2. unfiltered total, for comparison
shoplazza <svc> +count --<filter> <value>               # 3. filtered total — must be < the unfiltered one

フィルター適用後の件数がフィルターなしの合計と同じなら、要注意です。 返されたレコードが実際にフィルター条件を満たしていることを、フィルター対象のフィールドに対する --jq のスポットチェックで確認してください。フィルターが無視されている場合は、schema <svc>.<cmd> --view request にエンドポイントが実際に受け付けるパラメーターが一覧表示されます。仕様のリーフか、ドキュメントに記載されたパラメーターを使う api rest を利用してください。

精度の優先順位 — 同じ対象に対して複数のフィルター方法が用意されている場合は、最も対象を絞り込める方法を優先してください。専用の完全一致パラメーター（多くの場合は配列。例：customer_emails、skus、order_tags）は、一般的なキーワード検索より優先され、さらに --jq で全ページを手作業でフィルターする方法より優先されます。完全一致パラメーターは一致対象が明確ですが、キーワード検索では意図していないフィールドが一致する場合があります。

どの階層を使うか — ユーザーの動詞を読み取ってください。 言い回しから、値全体を指しているのか、その一部を指しているのかが分かります。それによって、完全一致とキーワード検索のどちらを使うかが決まります。

ユーザーの表現	意味	階層
「是 / 为 / 等于 / =」、「编号 / 号码 / 值 is X」、または単独で値全体を表す文字列（メールアドレス全体、ABC-001 のような SKU 全体、電話番号全体など）	値全体	完全一致の配列パラメーター
「包含 / 含 / 像 / 类似 / 以…开头 / 前缀 / 片段 / 部分」、X*、contains / starts-with / like	一部	キーワード検索

「是 / equals」は、フィールド名のすぐ隣にある場合でも、完全一致を示す確かな合図です。値全体に一致させ、あいまい検索はしないでください。

数だけでなく、根拠も伝えてください。 リストの読み取り結果をもとに回答する場合は、適用したフィルターと、完全性を確認した根拠（「18 件中 3 件、フィルターなしの合計は 18 件」など）を伝えてください。これにより、フィルターが無視された場合に、ユーザーが気づけるようになります。

操作する前に対象を特定してください。 書き込みではレコードの ID を指定しますが、ユーザーは注文番号、コード、メールアドレス、タイトルなど、別の情報で対象を指定します。まず読み取りで対象を特定し、その後、件数に応じて対応してください。

• 一致するものが 0 件 → 停止してその旨を伝えてください。より広い条件で書き込みを行ったり、ID を作り出したりしないでください。
• 一致するものが 1 件 → 続行してください（破壊的操作や金銭に関わる操作では、引き続き --dry-run を使い、操作内容を言い換えて確認してください）。
• 一致するものが 2 件以上 → 候補を一覧表示し、どれを対象にするか尋ねてください。推測したり、黙って「最初の」ものに対して操作したりしてはいけません。

番号は ID ではありません（例：注文番号と内部の order_id）。一方をもう一方が必要な場所に渡すと、間違ったレコードに当たるか、エラーになります。推測せず、読み取りで特定してください。

スキーマのイントロスペクション

仕様のリーフや api rest を呼び出す前に、スキーマを確認してパラメーター、ボディ、レスポンスの形式を確かめてください。フィールドを推測してはいけません。

shoplazza schema                              # list all modules
shoplazza schema discounts                    # list a module's commands
shoplazza schema discounts.get                # a command's params / body / response
shoplazza schema orders.create --view request # request side only (--view all|request|response)

API REST フォールバック

最初の 2 つの階層で表現できない場合に限ります。{…} テンプレートではなく、解決済みの実際の URLを記述します。

shoplazza api rest GET  /openapi/2026-01/products
shoplazza api rest GET  /openapi/2026-01/products/gid_123 --params '{"page_size":10}'
shoplazza api rest POST /openapi/2026-01/discounts/automatic --data @body.json

--params ／ --data（標準入力用の -、ファイル用の @file を含む）、--dry-run、-q/--jq に対応しています。

大きな整数 ID は JSON で引用符で囲みます。 --params ／ --data では、大きな数値 ID を裸の数値ではなく文字列（{"id":"669923000979557666"}）として渡してください。裸の大きな整数は浮動小数点数に変換され（→ 6.69…e+17）、リクエストが拒否されます。ID が約 15 桁を超える場合はどこでも該当します（例：shop redirects）。

インストール

CLI の事前確認

shoplazza が見つからない（command not found）場合、または shoplazza --version が失敗する場合、CLI はインストールされていません。インストールするとユーザーのマシンに変更が加わります。使用する方法を伝え、承諾を待ってください。マシンにすでにあるものに基づいて選びます。

方法	コマンド	条件
npm（推奨）	npm install -g shoplazza-cli	Node.js ≥ 16 がある（node -v）
Homebrew	brew install Shoplazza/tap/shoplazza-cli	brew を使用できる macOS ／ Linux
インストールスクリプト	curl -fsSL https://raw.githubusercontent.com/Shoplazza/shoplazza-cli/main/install.sh | bash	Node.js がない macOS ／ Linux。/usr/local/bin にインストールします（変更するには INSTALL_DIR=<dir> を指定）
リリースバイナリ	https://github.com/Shoplazza/shoplazza-cli/releases からダウンロード	その他のプラットフォーム。PATH に配置します

次に shoplazza --version で確認し、以下のログインフローに進みます。インストールに失敗した場合（サンドボックスにブロックされた、権限が拒否された、または sudo が必要など）は中止し、ユーザー自身のターミナルで実行する正確なコマンドを案内してください。

• インストーラーは 1 つだけ使用します。 2 回インストールすると、異なるバージョンを実行する 2 つの shoplazza バイナリが PATH 上に残ります。which -a shoplazza で確認できます。1 つだけ残してください。
• 使用したインストーラーで更新します。 shoplazza update は常に npm 経由で再インストールするため、Homebrew やスクリプトでインストールした場合は 2 つ目のコピーが追加されます。代わりに brew upgrade shoplazza-cli を使うか、スクリプトを再実行してください。

初回セットアップの全手順

shoplazza --version                                               # installed?
shoplazza auth login -s my-store.myshoplazza.com --domain products,orders   # login + bind a store
shoplazza auth status                                             # logged_in: true, the store under profiles

ログインをバックグラウンドで実行し、認証 URL をユーザーに渡してください（以下のエージェント主導のログインフローを参照）。必要なストアとモジュールをユーザーに尋ね、ストアドメインを推測しないでください。

認証（auth）

ログイン状態の事前確認

セッション中に最初のストア操作を行う前に、shoplazza auth status を実行してください（ローカルで即時に実行され、エンベロープはありません）。独立した 2 つの条件を両方満たす必要があります。

• logged_in: true — アカウントの認証情報が存在します。false の場合 → 以下のログインフローを実行します。
• profiles が空ではない — ストアが紐付けられています。logged_in: true でも profiles: [] の場合は、ストア API にアクセスできません。どのストアかを尋ね、auth login -s <store> --domain <modules> を実行します。

事前確認を省略すると、認証されていない状態でビジネスコマンドを実行した際に、validation エラーで即座に失敗します。エラーには "no profile configured" と修正方法を示す hint が含まれます。この場合も再試行せず、まずログインするようユーザーを案内してください。

ログイン

認証には 2 つのレイヤーがあります。アカウントレベル（auth login でアカウント認証情報を取得）と、ストアレベル（特定のストア用のストアトークンを交換し、プロファイルに保存）です。

# Account-level login (no store bound)
shoplazza auth login --domain products,orders        # or --scope read_product,write_product
# Store-level login (select a store; an interactive login with -s must also pass --scope or --domain)
shoplazza auth login -s my-store.myshoplazza.com --domain discounts

• --domain <module,…>：トップレベルのコマンド名で認証します。CLI が各モジュールに必要な OAuth スコープを展開します。選択肢：app, billing, checkout, customers, discounts, orders, products, shop, themes, webhook, all。推奨 — スコープのリテラルを覚える必要がありません。
• --scope <literal,…>：細かく指定する OAuth スコープ（例：read_product,write_product）で、最小権限にできます。
• 再ログインすると、許可設定は置き換えられます（実機で確認済み：22 個のスコープで許可された状態から 1 つのスコープで再認証すると、1 つのスコープのみになりました）。権限を追加する場合は、以前の許可設定を引き継ぐために --merge-scopes を渡してください（古い CLI にはこのフラグがありません。その場合は auth scopes を使って自分で統合し、1 回のログインで --domain と --scope を組み合わせてください）。ユーザーが明示的に権限を絞りたい場合に限り、省略してください。

エージェントによるログインフロー

AI エージェントとしてユーザーをログインさせる場合は、auth login をバックグラウンドで実行します（ユーザーが認可を完了するかタイムアウトするまでブロックしてポーリングします。--poll-interval／--timeout を参照してください。デフォルトは 2s／300s です）。出力から認可 URL を抽出してユーザーに渡してください。ユーザーが認可すると、コマンドは自動的に終了します。

ターミナルがある場合、指定されていないフラグは画面上の質問になります。 auth login（および app init）が不足している情報を尋ねるのは、stdin と stderr がどちらも実際のターミナルであり、 SHOPLAZZA_CLI_NO_INTERACTIVE も CI も設定されていない場合に限られます（存在し、空でない値が設定済みとみなされます）。それ以外の場合、不足しているフラグを示すエラーになります。子プロセスに pty を渡すハーネスは、この条件を満たします。その場合、コマンドは入力されないキー入力を待ち続けます。お使いの環境でこれが起きる場合は、セッション中に一度 SHOPLAZZA_CLI_NO_INTERACTIVE=1 をエクスポートしてください。

この設定で切り替えられるのは、質問の無効化のみです。--interactive フラグも、有効化を強制する環境変数もありません。ターミナルがない環境で強制すると、永久に停止するため、意図的に用意していません。

不足しているスコープに再ログインする場合は、--merge-scopes を指定してください。 スコープは統合されず、置き換えられます（上記のログインを参照してください）。不足しているスコープだけを指定すると、タスクの途中で他のすべてのスコープが失われます。フラグが不明な場合（古い CLI の場合）は、付与済みのスコープと新しいスコープをまとめてログイン時にリクエストし、統合してください。手順：auth scopes で付与済みスコープを確認し、次に付与済みスコープと新しいスコープを一緒にリクエストします。

非対話型の高速パス（UAT）

別のマシンで auth login を実行済みで、アカウント UAT がある場合は、ブラウザーを使わずにログインできます。

shoplazza auth login --uat <UAT>     # or set env SHOPLAZZA_UAT=<UAT>

--uat は、ターミナルの状態にかかわらずプロンプトを表示しません。上記の条件に加えて、コマンド全体を無効化するもう一つの方法です。pty を割り当てるハーネスからブラウザー経由でログインする場合も、SHOPLAZZA_CLI_NO_INTERACTIVE=1 が必要です。

ストアの切り替えとステータス

shoplazza auth status                                                  # auth state / identity / current store
shoplazza auth scopes                                                  # supported scopes + scopes granted to the account
shoplazza auth store use -s another-store.myshoplazza.com [--scope …]  # exchange a token for that store, set as current profile
shoplazza auth logout                                                  # log out of the current store

ストアを切り替えるコマンド：

内容	コマンド
現在使用中のストア	auth status — current: true のプロファイル（store_domain）
以前に使用したことがあるストア（プロファイルあり）	profile list → profile use --name <name>（--previous で元に戻します）
まだプロファイルがないストア	auth store use -s <store-domain> — プロファイルを作成または再利用し、現在のプロファイルに設定します
別のストアに対して実行するコマンド	そのコマンドに --profile <name> を追加します。現在のプロファイルはそのままです

auth store use と profile add を実行するには、先にアカウントへログインする必要があります。また、プロファイルのスコープはアカウントに付与されたスコープのサブセットでなければなりません。不足しているスコープがある場合は、auth login --domain <module> --merge-scopes を実行してから、もう一度切り替えてください。

権限不足への対処

書き込み時に 401／403 が返された場合、エラーエンベロープの hint に不足している権限が示されます。案内に従って付与してください。shoplazza auth login --domain <that module>（または --scope <missing scope>）を実行してから再試行します。まず auth scopes を実行すると、すでに付与されているスコープを確認できます。

プロファイル（マルチテナント）

プロファイルとは、1 つのストア実行コンテキスト（ストアトークンとスコープ）のことです。プロファイルを切り替えて、複数のストアを管理できます。

shoplazza profile add --name prod-us -s my-store.myshoplazza.com [--scope …] [--use]
shoplazza profile list
shoplazza profile use --name prod-us          # or --previous to switch back to the last one
shoplazza profile info [--name prod-us]       # defaults to the current profile
shoplazza profile rename --from old --to new
shoplazza profile remove --name prod-us
shoplazza profile update --name prod-us --scope …   # adjust a profile's scopes

呼び出しごとの上書き：グローバルフラグ --profile <name> は、環境変数 SHOPLAZZA_CLI_PROFILE と現在のプロファイルより優先されます。

更新のお知らせ

CLI の実行後に新しいバージョンを検出すると、1 行のお知らせが stderr に 出力されます（⚡ shoplazza-cli X is available …）。stdout の JSON には表示されません。黙って無視しないでください。ユーザーの現在のリクエストを完了した後、現在のバージョンと最新バージョンを伝え、更新を提案してください。

shoplazza update            # update via npm (--check only reports versions, no install)
# or: npm install -g shoplazza-cli@latest

Homebrew またはインストールスクリプトでインストールした場合は、同じ方法で更新してください（「インストール」を参照）。

（SHOPLAZZA_CLI_NO_UPDATE_CHECK を設定すると、チェックを無効にできます。）

update は 3 つの処理を実行し、それぞれを JSON 本文で報告します。

フィールド	意味
updated	バイナリが再インストールされたことを示します。false はすでに最新であることを意味し、失敗ではありません
meta_updated / meta_revision	API メタデータキャッシュが書き換えられたかどうか、および書き換えられたリビジョンを示します
skill_installed	Agent Skills が インストール済み であることを示すだけです

skill_installed が示すのは「インストール済みかどうか」であり、「直近で更新されたかどうか」ではありません。true の場合、shoplazza update は Agent Skills を更新しますが、update --check は何も更新しない場合でも同じ true を報告します。また、更新に失敗しても true のままです（stderr に警告が出力されます）。このフィールドだけを根拠に、スキルが更新されたとユーザーに伝えては いけません。その場合は stderr の行（✓ Refreshed N skill(s)）を確認してください。

スキルは オプトイン です。false は、ユーザーがスキルを一度もインストールしておらず、update はインストールせずそのままにしたことを意味します。インストールするには、次を実行してください。

npx skills add Shoplazza/shoplazza-cli -g

（SHOPLAZZA_CLI_SKIP_SKILLS=1 を設定すると、スキルの処理をスキップできます。その場合、フィールドは本文から完全に省略されます。フィールドが存在しない場合は「スキップ」、false の場合は「未インストール」を意味します。）

安全プロトコル

shoplazza-cli には、lark 形式の終了コード 10 による高リスク書き込みゲートも、--yes 確認フラグも ありません。独自の確認プロトコルを作らないでください。安全モデルは --dry-run → 内容を言い換える → ユーザーの承認を待つ です。

1. 破壊的な操作（キャンセル／削除）、一括操作、または資金を移動する操作（請求料金）では、まず --dry-run を実行 します。送信されるリクエストを表示し、その内容を言い換えたら、そこで停止してターンを終了してください。エンティティ／キャンペーンを +shortcut で作成する 場合（割引の作成など）は、対象ドメインのスキルに従ってください。+shortcuts は構造化されており、金額に関わる必須値が確認済みであれば、直接安全に実行できます（値を決して捏造しないでください）。ユーザーから求められた場合に限り、--dry-run を使用してください。
2. 同意はユーザーのメッセージでなければならず、あなた自身の判断ではありません。 ドライランを表示しただけでは同意になりません。あなた自身が内容を確認しただけでも同意にはなりません。実際のコマンドを実行できるのは、ユーザーが明示的に同意した後のターンに限られます（例：「确认」／「yes / go ahead」）。ドライランの出力が完璧でも、同じターン内でドライランと実際の書き込みを実行するのはプロトコル違反です。
3. ドライランと併せて、実行内容を言い換えてください。どのストアで、何を実行し、どの主要パラメーターを使うのかを平易な言葉で説明し、ユーザーが何に同意するのかを正確に把握できるようにします。
4. 金額を消費する値（割引額／上限額／価格）を捏造して はいけません。デフォルト値を使うか、ユーザーに尋ねてください。各ドメインのスキルにある必須値と確認事項を参照してください。
5. 書き込み操作のリハーサルは dev／stg ストアでのみ行ってください。prod では決して練習しないでください。

コマンドの確認

shoplazza --help                 # top-level modules
shoplazza <svc> --help           # a module's shortcuts + spec leaves
shoplazza <svc> <cmd> --help     # a command's flags
shoplazza schema <svc>.<cmd>     # params / body / response shape