pp-instacart

Instacart - Printing Press CLI

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

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

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

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

2. 確認します：instacart-pp-cli --version
3. このスキルを実行するエージェント／ランタイムから参照できるよう、報告されたインストール先が $PATH に含まれていることを確認します。

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

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

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

この CLI を使う場面

次のような要望がある場合に使用してください。

• 自然言語で Instacart のカートに商品を追加する（「QFC にレモンソルベを追加して」）
• 以前購入した商品を追加する（「Safeway にいつもの牛乳を追加して」）
• 各小売店の現在のカートを表示、検索、比較する
• Instacart の注文履歴を一覧表示または検索する
• スクリプト、cron ジョブ、エージェントループから Instacart のワークフローを実行する

実際にチェックアウトしたい場合は使用しないでください。この CLI でできるのはカートへの商品追加までです。チェックアウトは Instacart アプリまたは Web UI で完了する必要があります。

独自の機能

履歴を優先する add

add は、まずローカルの購入履歴を確認し、対象の小売店で確度の高い一致が見つかった場合は、3 回の呼び出しが必要なライブ GraphQL チェーンを完全に省略します。「いつも買うレモンソルベのポップを追加して」の処理時間が約 1.2 秒から約 200 ミリ秒に短縮され、さらに、今日のライブ検索で最上位に表示される商品ではなく、実際に購入している適切な SKU が選択されます。

一致の確度に関する条件：

• その小売店で、ローカルの purchased_items に対する FTS5 検索で一致する
• 過去 365 日以内に購入している
• 前回の購入時に在庫があった

いずれかの条件を満たさない場合は、現在のライブ検索の動作に切り替わります。ライブ検索を強制するには --no-history を渡してください。

成功した add は、履歴から解決した場合もライブ検索から解決した場合も、購入履歴のシグナルを完全な再同期なしで強化できるよう、purchased_items に書き戻します。

1 コマンドで履歴をバックフィル

「Instacart の注文をバックフィルして」（または同様の表現。「Argument Parsing」を参照）と入力すると、Chrome-MCP を使用するフローが開始され、ユーザーがログインしている Instacart のタブをたどって注文履歴を JSONL に抽出し、ローカル DB にインポートします。バックフィル後、add はライブ検索による推測ではなく、実際の購入履歴に基づいて商品を解決します。

主な方法は Chrome MCP です。代替方法として、3 つの JS ファイルを手動で DevTools に貼り付けます。

詳細な手順は、以下の「Backfill Flow」を参照してください。詳しいリファレンス：

• docs/backfill-walkthrough.md — Chrome MCP フロー
• docs/backfill-devtools-fallback.md — 手動の DevTools フロー

history list／history search／history stats で、読み込み済みのデータを確認できます。

Instacart は注文履歴用のクリーンな GraphQL オペレーションを公開していないため、従来の history sync コマンドは機能しません。その理由については、docs/solutions/best-practices/instacart-orders-no-clean-graphql-op.md を参照してください。

自然言語による add

Instacart 独自の3回呼び出しの GraphQL チェーン（ShopCollectionScoped -> Autosuggestions -> Items）を介して自由テキストから商品を解決し、UpdateCartItemsMutation を発火します。ブラウザ自動化は使用しません。

Instacart が候補を notFoundBasketProduct で拒否した場合（オートサジェストは、現在アクティブなカートの店舗では追加できない商品を稀に表示することがあります）、add は諦める前に最大3件のランク付けされた候補を自動的に再試行します。--json 出力では、再試行が成功すると retry_count > 0 が設定され、拒否された商品 ID を列挙した attempts 配列が含まれます。履歴優先の解決で同じエラーが発生した場合、add はライブ検索にフォールスルーし、resolved_via: "history->live" を報告します。

マルチリテイラーの carts

carts list は、リテイラー全体にわたるすべてのアクティブなカートを一度に表示します。商品がどこにあるかを把握してから適切なカートに追加する必要があるエージェントに便利です。

コマンドリファレンス

認証:

• instacart auth login - Chrome からセッション Cookie を抽出します
• instacart auth status - 現在のセッション状態を表示します
• instacart auth logout - 保存された Cookie をクリアします
• instacart auth paste - Cookie JSON を手動で貼り付けます（新しい macOS Chrome 向けのフォールバック）
• instacart auth import-file <path> - browser-use エクスポート JSON から Cookie を読み込みます

カート操作:

• instacart add <retailer> <query...> - 自然言語で商品を追加します
• instacart add <retailer> <query...> --no-history - 履歴優先のリゾルバーをスキップします
• instacart add --item-id <id> <retailer> - 正確な Instacart 商品 ID で追加します
• instacart cart show <retailer> - リテイラーでの現在のカート内容を表示します
• instacart cart remove <item-id> <retailer> - カートから商品を削除します
• instacart carts list - リテイラー全体のすべてのアクティブなカートを一覧表示します

検索:

• instacart search <query> --store <retailer> - リテイラーで商品を検索します
• instacart retailers list - お客様の住所で利用可能なリテイラーを一覧表示します
• instacart retailers show <slug> - 1つのリテイラーをローカルにキャッシュします

購入履歴:

• instacart history import <path> - JSONL の注文ダンプをローカル DB に読み込みます（動作するパス）
• instacart history import - --json - stdin から読み取り、エージェントパイプライン向けに JSON を出力します
• instacart history import <path> --dry-run - 書き込まずに件数をプレビューします
• instacart history list - 購入回数 + 最近度による上位の購入商品
• instacart history list --store <retailer> --limit 20 - フィルタ + ページネーション
• instacart history search <query> - 購入履歴を FTS 検索します
• instacart history search <query> --store <retailer> - スコープ付き FTS 検索
• instacart history stats - 件数 + リテイラーごとの状態

メンテナンス:

• instacart doctor - ヘルスチェック: config、store、ops、history、session、live ping
• instacart capture - GraphQL オペレーションハッシュキャッシュを更新します
• instacart capture --remote - コミュニティレジストリから最新のハッシュをマージします
• instacart ops list - オペレーションハッシュキャッシュの状態を表示します

レシピ

初回セットアップ

instacart auth login                # extract cookies from Chrome
instacart doctor                    # verify auth + live ping
instacart capture                   # seed built-in op hashes

次に履歴をバックフィルします（任意ですが推奨。履歴優先の add が使えるようになります）:

エージェントに伝えてください: 「backfill my instacart orders」

残りはスキルが実行します。以下の「バックフィルフロー」セクションを参照してください。

いつも買うものを追加する

instacart add safeway "oat milk"    # resolves via local history if you have bought it before

出力に via history があるか確認してください。via live と表示されている場合、FTS の一致が信頼度チェックを通過しませんでした。instacart history search "oat milk" --store safeway を実行して、履歴に実際に何が入っているかを確認してください。

強制的に新規のライブ検索を実行する

instacart add safeway "oat milk" --no-history --dry-run --json

--dry-run --json はデバッグ時に便利です。出力に resolved_via が含まれるため、どのパスが発火したはずかを確認できます。

最近の履歴からの毎日の補充

instacart history list --store safeway --limit 20 --json | jq -r '.[].name' \
  | while read item; do instacart add safeway "$item" --yes --json; done

認証セットアップ

Chrome でログイン済みの Instacart セッションが必要です。CLI は kooky を介して Cookie を抽出します（当方側での認証情報の取り扱いはありません）。Chrome がロックされている場合、または kooky が読み取れないシステムを使用している場合:

instacart auth paste         # paste the full cookie JSON manually
instacart auth import-file <path>

セッションは ~/.config/instacart/session.json に保存されます（0600）。

場所の設定

Instacart の GraphQL API では、すべての小売業者検索で場所データ（latitude／longitude または address_id）が必要です。これがないと、search、add、cart show は ShopCollectionScoped のブートストラップ段階で失敗します。

auth login の後の手順では、Instacart のデフォルトの住所から address_id、postal_code、latitude、longitude が自動入力されます。うまくいかない場合、エージェントは次のいずれかを使います。

• instacart config set-address --id <uuid> — キャッシュされた GetAddressById op を使い、既知の Instacart の住所 ID から座標を取得します。ID は https://www.instacart.com/store/account/your-account の URL または graphql の変数で確認できます（DevTools の Network タブ）。
• instacart config set-coords --lat <N> --lon <N> [--postal <zip>] — 座標を直接渡します（Google Maps で右クリックして「ここは何ですか？」を選ぶと、緯度／経度が表示されます）。
• instacart config show — 現在の設定を確認します。

instacart doctor は、場所の情報がない場合に location: fail のチェック結果を表示します。そのため、CLI を操作するエージェントは実際のコマンドを実行する前に、問題のある状態を検出できます。

複数の住所（名前付きプロファイル）

config profiles は、単一のアクティブな場所設定に重ねて使う、名前付き住所の保存機能です。ユーザーに複数の配達先住所（自宅、職場、別荘など）があり、毎回 config set-address を再実行せずに切り替えたい場合に使用します。

• instacart config profiles list — 保存済みのプロファイルを表示します。アクティブなプロファイルには * が付きます。
• instacart config profiles add <name> --id <address_id> [--label "..."] [--use] — Instacart の住所 ID を使ってプロファイルを保存します（GetAddressById を使って座標を入力します）。同時にアクティブにするには --use を渡します。
• instacart config profiles add <name> --lat <N> --lon <N> [--postal <zip>] [--label "..."] — 生の座標を使ってプロファイルを保存します。ネットワーク呼び出しは行いません。
• instacart config profiles use <name> — アクティブなプロファイルを切り替えます（その場所をトップレベルの設定キーにコピーするため、それ以降のすべての呼び出しで使用されます）。
• instacart config profiles show <name> — 1 つのプロファイルを表示します。
• instacart config profiles rm <name> — プロファイルを削除します。アクティブなプロファイルを削除した場合、アクティブなプロファイルは解除され、既存のトップレベル設定が引き続き適用されます。
• instacart config profiles import [--prefix <p>] [--overwrite] [--use <name>] — ユーザーの Instacart アカウントから保存済みの住所をすべて取得し（CurrentUserAddresses 経由）、住所ごとにプロファイルとして保存します。プロファイル名には、番地をスラッグ化した名前を使います。

呼び出し単位の上書き：場所が必要な任意のコマンドに --profile <name> を渡します（例：instacart --profile work add safeway "cold brew"）。これにより、アクティブなプロファイルを変更せず、その呼び出しに限って名前付きプロファイルを適用します。

プロファイルが定義されていない場合、CLI は従来どおりに動作します。config set-coords／set-address／show は引き続き、トップレベルの場所キーを直接操作します。

エージェントモード

CLI はデフォルトでエージェントネイティブです。任意のコマンドに --json を渡すと、機械可読形式で出力されます。--dry-run は変更を実行せずに add のプレビューを表示し、どのリゾルバー（history、live、item-id）が使われるかを示します。

add の JSON エンベロープで把握しておくとよいフィールド：

• resolved_via：history、live、history->live（履歴から選んだ項目が拒否され、再試行した live で成功）、または item-id のいずれかです。
• retry_count：採用された候補の前に拒否された候補の数です。最初に選んだ項目が採用された場合は 0 です。
• attempts：retry_count > 0 の場合のみ含まれます。拒否された候補ごとの {item_id, name, error_type} の配列です。
• 候補を使い切った場合（終了コード 5）：error、retailer、query、attempts、および具体的な次の手順（search の後に add --item-id、または --no-history を付けて再試行）を示す hint を含む JSON エンベロープが返されます。

出力のフィルタリング

--select は、ネストされたレスポンスをたどるためのドット区切りパスを受け付けます。配列の場合は各要素をたどります。

instacart-pp-cli <command> --agent --select id,name
instacart-pp-cli <command> --agent --select items.id,items.owner.name

これを使うと、必要なフィールドだけに大きなペイロードを絞り込めます。深くネストされた API レスポンスでは特に重要です。

レスポンスエンベロープ

データレイヤーのコマンドは、出力を {"meta": {...}, "results": <data>} でラップします。データには .results を、ソースが live とローカルのどちらかを確認するには .meta.source を解析してください。N results (live) の概要は、標準出力が TTY の場合にのみ標準エラー出力に表示されます。パイプ経由の利用者やエージェントには、標準出力に純粋な JSON が表示されます。

終了コード

コード	意味
0	成功
2	使用方法のエラー
3	認証情報がない、または拒否された
4	リソースが見つからない
5	API エラー／競合
7	レート制限、または一時的なネットワークエラー

引数の解析

自由形式の自然言語によるリクエストを受け取った場合：

1. 空、help、または --help -> instacart --help を実行します
2. install で始まる -> CLI をインストールします。mcp で終わる -> MCP をインストールします
3. バックフィルの意図に該当する -> 以下のバックフィルフローを実行します。該当するフレーズの例：「注文をバックフィルして」「購入履歴をバックフィルして」「Instacart の履歴を同期して」「Instacart の注文を同期して」「注文履歴をダウンロードして」「Instacart の履歴をローカルに保存して」「過去の注文を取り込んで」「最近の注文をインポートして」。
4. それ以外 -> 最適なサブコマンドに対応付け、エージェントから実行された場合は --json を付けて実行します

バックフィルフロー

ユーザーがバックフィルの意図を示した場合は、このフローを実行します。完全な手順については、WebFetch で docs/backfill-walkthrough.md を読み込んでください。以下に概要を示します。

セットアップの確認：

1. instacart-pp-cli が PATH にあることを確認します。ない場合は、インストールします：go install github.com/mvanhorn/printing-press-library/library/commerce/instacart/cmd/instacart-pp-cli@latest。
2. mcp__claude-in-chrome__tabs_context_mcp を確認します。ツールを利用できない場合は、DevTools の代替手順に進みます：docs/backfill-devtools-fallback.md を取得し、ユーザーに手順を案内します。そこで終了します。
3. instacart-pp-cli history stats --agent を実行します。注文数が 0 より大きい場合は追加分の実行となり、再開状態によって、すでにダンプされた注文は自動的にスキップされます。

Chrome MCP ループ：

1. WebFetch で 3 つの JS ファイルを取得します（それぞれ現在のセッションにキャッシュします）：
   • https://raw.githubusercontent.com/mvanhorn/printing-press-library/main/library/commerce/instacart/docs/dumper.js
   • https://raw.githubusercontent.com/mvanhorn/printing-press-library/main/library/commerce/instacart/docs/extract-one.js
   • https://raw.githubusercontent.com/mvanhorn/printing-press-library/main/library/commerce/instacart/docs/export-jsonl.js
2. https://www.instacart.com/store/account/orders のタブを開くか、既存のタブを再利用します。ダンパーが profile_picker: true を返した場合は、タブでプロフィールを選択するようユーザーに依頼してから、再実行します。
3. mcp__claude-in-chrome__javascript_tool を使って dumper.js を挿入します。total_ids と pending_extract を読み取ります。
4. 保留中のセットにある各注文 ID について、/store/orders/<id> に移動してから extract-one.js を挿入します。10 件ごとにユーザーへ進捗を報告します。
5. 保留件数が 0 になったら、export-jsonl.js を挿入します。ユーザーの既定の Downloads フォルダーに instacart-orders.jsonl がダウンロードされます。
6. Bash ツールで instacart-pp-cli history import ~/Downloads/instacart-orders.jsonl --agent を実行します。概要 JSON をユーザーに表示します。
7. 検証として、instacart-pp-cli history stats --agent を実行します。続けて、instacart-pp-cli add <retailer> "<something they've bought>" --dry-run --json による簡易チェックを提案し、resolved_via: "history" が表示された場合はその旨を伝えます。

ユーザーに伝える価値のあるエラー：

• すべての注文で抽出ツールが cache_key_missing を返す -> Instacart がウェブバンドルを更新しています。確認できたキャッシュキーを報告し、ウォークスルードキュメントのローテーションからの復旧セクションを案内します。
• ダンパーがユーザーの予想より少ない ID を報告する -> 複数プロフィールのアカウントである可能性があります。購入履歴のあるプロフィールが選択されていることを確認します。
• history import でインポートされた注文数が 0 と表示される -> JSONL が空です（スキップレコードのみ）。新しいタブを使って抽出ループを再実行します。

直接使用

1. インストール済みか確認します：which instacart-pp-cli
2. 認証を確認します：instacart doctor
3. GraphQL のハッシュをキャプチャします：instacart capture
4. （任意ですが推奨）履歴をバックフィルします — 上記のバックフィルフローを実行します。履歴を優先する add の解決が可能になります。
5. エージェントから呼び出す場合は、コマンドに --json を付けて実行します。