pp-amazon-orders

Amazon Orders — Printing Press CLI

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

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

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

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

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

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

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

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

この CLI を使用する場面

エージェントがユーザーの Amazon 注文履歴を横断して調べる必要がある場合は、amazon-orders-pp-cli を使用してください。複数注文の追跡レーダー、定期購入の検出、支出の集計、「あの USB-C ケーブルはいつ注文した？」といった FTS5 検索に適しています。ローカルの SQLite ストアを使うため、Amazon に再アクセスしたり、HTML ページ全体でコンテキストを消費したりせずに、複数の注文にまたがる質問へすぐに回答できます。

この CLI を使用しない場面

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

独自の機能

この API 向けのほかのツールでは、次の機能を利用できません。

積み重なるローカルの状態

• where-is-my-stuff — 配送中のすべての Amazon 注文について、現在のステータスと到着予定日を一度に表示します。

  複数の注文を対象に「荷物は今日届く？」という質問にエージェントが答える必要がある場合、このコマンドを使えば一度で確認できます。

  amazon-orders-pp-cli where-is-my-stuff --json --select orderId,status,etaDate,carrier
  

• delivery-slips — 実際の配達日が当初の予定日より N 日以上遅れた注文を表示します。

  注文を一つずつ手動で確認しなくても、信頼性の低い配送業者や販売者を見つけられます。

  amazon-orders-pp-cli delivery-slips --days 3 --since 2025-01-01 --json
  

• spend — 月、年、カテゴリー、販売者、または支払い方法別に支出を集計します。

  予算管理、経費報告、傾向分析について、エージェントが一度で回答できます。

  amazon-orders-pp-cli spend --by month --year 2025 --json
  

• top-items — 注文履歴全体を対象に、ASIN ごとにまとめた注文頻度または合計支出別の上位商品を表示します。

  ユーザーが実際に繰り返し購入している商品と、一度限りの購入品をエージェントが判断するのに役立ちます。

  amazon-orders-pp-cli top-items --by total-spend --limit 20 --json
  

• subscribe-and-save — 注文履歴から推定した定期購入を表示します（同じ ASIN が一定の間隔で注文されている場合）。

  実際に S&S に登録する候補を見つけ、ユーザーが気付いていない事実上の定期購入を検出します。

  amazon-orders-pp-cli subscribe-and-save --min-occurrences 3 --json
  

• arriving-soon — 今後 N 日以内に到着する配送を、到着予定日順に表示します。

  エージェントが到着予定の荷物を考慮して計画を立てられます（例：「金曜日の会議までにルーターは届く？」）。

  amazon-orders-pp-cli arriving-soon --days 7 --json
  

• late — 当初の配達予定日を過ぎた配送中の荷物を表示します。

  手動で確認しなくても、配送の遅延を発生時に把握できます。

  amazon-orders-pp-cli late --json
  

エージェント向けのネイティブな連携機能

• find — 注文、商品、販売者、追跡メモを対象に FTS5 検索を行います。

  何年分もの注文履歴をスクロールしなくても、「あの商品はいつ注文した？」に直接回答できます。

  amazon-orders-pp-cli find 'usb-c cable' --json --select orderId,placedDate,total
  

検出シグナル

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

• キャプチャ範囲：全ネットワークエントリー 6 件中、API エントリー 6 件
• プロトコル：html_cookie（確信度 85％）

コマンドリファレンス

gift_cards — ギフトカードの残高と利用履歴です。

• amazon-orders-pp-cli gift_cards — 現在のギフトカード残高と利用履歴を表示します。金額、種類（追加／適用／返金）、日付、関連する注文 ID が含まれます。

orders — 購入者側の注文履歴一覧と、注文ごとの詳細ページです。

• amazon-orders-pp-cli orders get — 1 件の注文の詳細をすべて表示します。商品、ASIN、価格、配送、支払い方法、配送先住所、合計金額が含まれます。
• amazon-orders-pp-cli orders invoice — 注文の印刷可能な請求書（HTML）を表示します。VAT／経費の照合に役立ちます。
• amazon-orders-pp-cli orders list — 注文履歴の 1 ページを取得します。timeFilter（year-2026、last30days、months-3）と startIndex を使ってページを切り替えます。

shipments — 荷物ごとの追跡詳細です。

• amazon-orders-pp-cli shipments — 1 件の荷物の追跡詳細を表示します。配送業者、追跡番号、ステータス、到着予定時刻、配達確認が含まれます。

transactions — すべての注文、定期サービス、Prime の請求と返金です。

• amazon-orders-pp-cli transactions — 日付ごとにグループ化された取引一覧の最初のページを表示します。各行には支払い方法、末尾 4 桁、符号付きの金額、および（場合によっては...

手書きコマンド

• amazon-orders-pp-cli sync — 注文履歴をローカルの SQLite ストアに同期します。差分同期には --since 90d を、すべてを再取得するには --full を使用します。
• amazon-orders-pp-cli orders list — --time-filter（year-YYYY、last30days、months-3）と --start-index を使って、注文一覧のページを切り替えます。
• amazon-orders-pp-cli orders get <order-id> — 1 件の注文の詳細（商品、配送、支払い、合計金額）をすべて表示します。
• amazon-orders-pp-cli orders invoice <order-id> — 1 件の注文の請求書を印刷します。
• amazon-orders-pp-cli shipments --order-id <id> — 1 件の注文の荷物の追跡詳細を表示します。
• amazon-orders-pp-cli track <order-id> — 1 件の注文のリアルタイム追跡情報を表示します。配送業者、追跡番号、ステータス、到着予定時刻が含まれます。
• amazon-orders-pp-cli where-is-my-stuff — 配送中のすべての荷物の現在のステータスと到着予定時刻を一覧で表示します。
• amazon-orders-pp-cli arriving-soon --days 7 — 今後 N 日以内に到着する荷物を、到着予定時刻順に表示します。
• amazon-orders-pp-cli late — 配達予定日を過ぎた荷物を表示します。
• amazon-orders-pp-cli delivery-slips --days 3 --since 2025-01-01 — 実際の配達日が当初の予定日より N 日以上遅れた注文を表示します。（同期履歴が必要です。）
• amazon-orders-pp-cli spend --by month --year 2026 — 月、年、配送先、またはステータスごとの支出を集計します。
• amazon-orders-pp-cli top-items --by count --limit 20 — 注文履歴全体で注文数が最も多い商品／ASINを表示します。
• amazon-orders-pp-cli returns — 返品された商品を、注文と取引を結合して表示します。（同期履歴が必要です。）
• amazon-orders-pp-cli subscribe-and-save --min-occurrences 3 — 実質的な定期購入を検出します。（同期履歴が必要です。）
• amazon-orders-pp-cli carriers --rank — 配送業者ごとの定時配達率を表示します。（同期履歴が必要です。）
• amazon-orders-pp-cli find '<query>' — 注文、商品、ASIN、販売者を対象にフリーテキスト検索を行います。
• amazon-orders-pp-cli transactions — 請求と返金を表示します（取引ページのパーサー）。
• amazon-orders-pp-cli gift-cards — ギフトカードの残高と利用履歴を表示します。

Freshness Contract

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

対象となるパス：

• amazon-orders-pp-cli orders
• amazon-orders-pp-cli orders get
• amazon-orders-pp-cli orders invoice
• amazon-orders-pp-cli orders list
• amazon-orders-pp-cli transactions

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

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

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

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

which は、自然言語による機能の問い合わせを、この CLI の厳選された機能インデックスから最適なコマンドに解決します。終了コード 0 は少なくとも 1 つ一致したことを意味し、終了コード 2 は確信の持てる一致がなかったことを意味します。その場合は --help を使うか、より絞り込んだ問い合わせをしてください。

レシピ

待っている荷物はどこにありますか？

amazon-orders-pp-cli where-is-my-stuff --json --select orderId,status,etaDate,carrier

配送中のすべての注文について、現在のステータスと到着予定時刻を一覧表示します。これは、配送中の Amazon 注文をまとめて確認できるレーダーです。

今年はいくら使いましたか？

amazon-orders-pp-cli spend --by month --year 2026 --json

ローカルストアから Amazon の月ごとの支出を集計します。ライブ呼び出しは行わず、1 秒未満で完了します。

買ったあの商品の注文を探す

amazon-orders-pp-cli find 'usb-c hub' --json --select orderId,placedDate,total,items.title

注文と商品を FTS5 で検索します。ドット区切りの --select を使って、エージェントが必要とするフィールドだけを抽出します。

まだ届いていないのに、どの荷物の料金が請求されていますか？

amazon-orders-pp-cli late --json

当初の到着予定日を過ぎた配送中の荷物を表示するので、エージェントが配送業者の遅延を検知できます。

実際には何を買っていますか？

amazon-orders-pp-cli top-items --by total-spend --limit 20 --json

過去の注文履歴にある購入済みの ASIN を、支出総額ごとにグループ化し、繰り返し購入している商品を見つけやすくします。

認証の設定

Amazon は購入者向け API を公開していません。この CLI は、ログイン済みの Chrome／Firefox／Safari／Brave セッションから auth login --chrome で Cookie をインポートします。Cookie はローカルに保存され、自動的に更新されるため、以降のすべての取得で認証に使われます。API キーも OAuth も不要で、実行時にブラウザーを常駐させる必要もありません。

米国以外のマーケットプレイスを利用する場合は、ログイン時にマーケットプレイスのドメインを指定してください。インドの場合の例：

amazon-orders-pp-cli auth login --chrome --domain amazon.in

auth login --chrome の実行前に AMAZON_ORDERS_BASE_URL=https://www.amazon.in を設定することもできます。

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

1Password を使ったヘッドレスエージェントのセットアップ（LLM を介さない受け渡し）

auth login --chrome を実行できないヘッドレスホスト（CI、開発コンテナー、リモートエージェント）では、ログイン済みのマシンで一度だけセッションを取得し、1Password（またはその他のシークレットマネージャー）に保存して、ヘッドレスホストに渡します。Cookie の値が LLM のコンテキストウィンドウに入ることはありません。データはシェル変数を介さず、op → stdin → CLI と流れるため、LLM が読み取ることはできません。

一度だけ保存します（ログイン済みのマシンで）：

TMP=$(mktemp -t amazon-orders-session.XXXXXX.json)
chmod 600 "$TMP"
amazon-orders-pp-cli auth export --output "$TMP" --note "captured $(date -u +%FT%TZ) from $(hostname)"
op document create "$TMP" \
  --title 'amazon-orders-session' \
  --vault Agent \
  --tags 'cli-session,amazon-orders,printing-press'
shred -u "$TMP" 2>/dev/null || rm -f "$TMP"

ほかのすべてのマシンで渡します：

# Long form (separate fetch + import):
op document get 'amazon-orders-session' --vault Agent \
  | amazon-orders-pp-cli auth import --stdin

# Short form via op:// URI (works in direnv, agent configs, K8s init containers):
op read "op://Agent/amazon-orders-session/file" \
  | amazon-orders-pp-cli auth import --stdin

どちらの方法でも、Cookie の内容は ~/.config/amazon-orders-pp-cli/config.toml に保存され、認証済みになります。次の両方で検証してください。

amazon-orders-pp-cli auth status
amazon-orders-pp-cli doctor --agent

auth status で確認できるのは、Cookie の内容が設定されていることだけです。Authenticated と表示されても、doctor で browser_session_proof が欠落または古いと報告される場合があります。この状態では、ライブコマンドが注文の代わりに空または null の結果を返すことがあります。ヘッドレス環境への 1Password からのインポートでは、エンドツーエンドの検証手順として doctor を使用してください。

doctor でブラウザーセッションの証明が古い、または欠落していると報告された場合は、現在ログイン中の Chrome プロファイルから更新して、doctor を再実行してください。

python3 -m pip install --user pycookiecheat  # if doctor says cookie_tool not found
export PATH="$PATH:$HOME/go/bin:$(python3 -m site --user-base)/bin"
amazon-orders-pp-cli auth login --chrome --no-input --yes
amazon-orders-pp-cli doctor --agent

Chrome から新しい Cookie を取得し、ほかのヘッドレスエージェントにも使わせる場合は、Cookie の内容を表示せずに 1Password のドキュメントを更新してください。

TMP=$(mktemp "${TMPDIR:-/tmp}/amazon-orders-session.XXXXXX")
chmod 600 "$TMP"
amazon-orders-pp-cli auth export --output "$TMP" --note "captured $(date -u +%FT%TZ) from $(hostname)" &&
  op document edit 'amazon-orders-session' --vault Agent "$TMP"
shred -u "$TMP" 2>/dev/null || rm -f "$TMP"

Amazon が session-id をローテーションした場合に更新します（通常は数週間ごとです。orders list が 401 を返すことで判別できます）。

amazon-orders-pp-cli auth login --chrome           # on the logged-in machine
amazon-orders-pp-cli auth export --output /tmp/s.json
op document edit 'amazon-orders-session' --vault Agent /tmp/s.json
shred -u /tmp/s.json 2>/dev/null || rm -f /tmp/s.json

代替手段： stdout にパイプ出力できるシークレットマネージャーなら、どれでも同じように使えます。vault kv get、aws secretsmanager get-secret-value --query SecretString --output text、pass show amazon-orders-session、bw get item amazon-orders-session | jq -r .notes は、いずれも amazon-orders-pp-cli auth import --stdin に連結できます。

AMAZON_COOKIES 環境変数を使う方法： CLI はこの環境変数からも自動的にインポートします。1 回限りのコンテナーの場合：

export AMAZON_COOKIES="$(op read 'op://Agent/amazon-orders-session/file')"
amazon-orders-pp-cli auth import   # reads $AMAZON_COOKIES, then exits
amazon-orders-pp-cli orders list --json

エージェントモード

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

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

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

  amazon-orders-pp-cli orders 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 がターミナルの場合に限り stderr に出力されます。パイプやエージェントで使用する場合、stdout には純粋な JSON が出力されます。

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

あなた（またはエージェント）がこの CLI に問題を見つけたら、記録してください。

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

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

バグ報告ではなく、意外に感じたことを書いてください。短く、具体的に、一行で。それが積み重なっていく部分です。

出力の配信

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

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

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

名前付きプロファイル

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

amazon-orders-pp-cli profile save briefing --json
amazon-orders-pp-cli --profile briefing orders list
amazon-orders-pp-cli profile list --json
amazon-orders-pp-cli profile show briefing
amazon-orders-pp-cli profile delete briefing --yes

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

終了コード

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

引数の解析

$ARGUMENTS を解析します。

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

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

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

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

2. Claude Code に登録します。

   claude mcp add amazon-orders-pp-mcp -- amazon-orders-pp-mcp
   

3. 確認します：claude mcp list

直接使用

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

   amazon-orders-pp-cli <command> [subcommand] [args] --agent
   

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