pp-fedex

FedEx — Printing Press CLI

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

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

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

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

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

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

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

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

この CLI を使用する場面

小〜中規模の配送業務を運営していて、FedEx REST API をプログラムから利用したい場合は fedex-pp-cli を使用してください。適した用途：注文 CSV からラベルを作成する EC ストア、返品ラベルを発行するカスタマーサービスチーム、配送中の荷物を追跡する運用チーム、会計用にすべての配送記録と運賃見積もりをローカルに保存したい中小企業のオーナーなどです。ローカルの SQLite アーカイブがあるため、過去の配送に関する分析クエリにも適しています。FedEx だけを利用し、データを自分で管理したい場合や、ウェブ UI よりもターミナル／エージェントによる自動化を好む場合は、複数の配送業者に対応した SaaS（ShipStation、Shippo）よりこの CLI を選んでください。

独自の機能

これらの機能は、この API を扱う他のツールでは利用できません。

コストと時間を節約

• rate shop — 該当するすべてのサービスタイプの運賃を並行して見積もり、コスト、輸送日数、またはコスト／日数で順位付けします。

  荷物に適した最安のサービスを選ぶ際、6 回以上の API 呼び出しを、順位付きの回答 1 つにまとめます。中小規模の配送業者にとって、最も大きなコスト削減につながるコマンドです。

  fedex rate shop --from 90210 --to 10001 --weight 5lb --json --select rates.serviceType,rates.totalNetCharge,rates.transitTime
  

• ship bulk — 適応型レート制限、行ごとの PASS／FAIL 記録、直近の成功地点からの再開機能を備え、注文 CSV のラベルを作成します。

  「1 日に 30 個の荷物を発送する」ためのワークフローです。FedEx Ship Manager でラベルを 1 枚ずつ作成する操作に代わります。

  fedex ship bulk --csv orders.csv --service GROUND --output labels/ --resume
  

• return create — 既存の追跡番号に対する Ground Call Tag（返品ラベル）を 1 つのコマンドで作成します。オプションで受取人にメール送信できます。

  EC のカスタマーサービス向けワークフローです。返品ラベルの発行は、販売後に最もよく行われる対応です。

  fedex return create --tracking 794633071234 --reason damaged --email [email protected]
  

• address validate — SHA-256 キーを使ったローカルキャッシュにより、同じ住所を再検索した際に FedEx Address Validation API への再課金を防ぎます。

  直接的なコスト削減につながります。1 回の呼び出しあたりの金額を定量化できる唯一の機能です。

  fedex address validate --street '1600 Amphitheatre Pkwy' --city 'Mountain View' --state CA --zip 94043 --country US --cache
  

• ship etd — 電子貿易書類を使った配送を 1 つのコマンドで実行します。コマーシャルインボイスをアップロードし、docId を取得して、出荷作成の呼び出しに組み込みます。

  国際配送には ETD が必要です。エラーが起きやすい複数の手順を、1 回の一括操作にまとめます。

  fedex ship etd --invoice invoice.pdf --orig CN --dest US --recipient-name 'Acme' --weight 2kg --service FEDEX_INTERNATIONAL_PRIORITY
  

ローカル状態の蓄積

• address save — よく使う宛先をローカルのアドレス帳に保存し、発送コマンドで名前を指定して参照します。

  有料 SaaS の競合製品と同等の使いやすさを実現します。リピーターの住所を何度も入力する手間を省きます。

  fedex address save acme --street '500 Main St' --city Denver --state CO --zip 80202 --country US
  

• track diff — ローカルストア内の各追跡番号について、前回のポーリング以降に発生した追跡イベントのみを表示します。

  エージェントが本来作成する必要のある、追跡ポーリングの重複排除処理を不要にします。

  fedex track diff --since 1h --json
  

• track watch — 一連の追跡番号を継続的にポーリングし、新しいイベントが発生したら標準出力、Webhook、またはファイルに出力します。FedEx のプッシュ通知に代わるポーリング方式です。

  ほとんどの中小企業には、設定済みのプッシュ Webhook がありません。ポーリングデーモンは、あらゆる企業で使える代替手段です。

  fedex track watch --tracking 794633071234 --interval 10m --webhook https://example.com/hook
  

• archive — ローカルアーカイブ内のすべての発送について、SQLite FTS5 で検索します。検索対象は、受取人名、住所、参照情報、追跡番号、サービスです。

  「先週、ACME に発送したか？」は、中小企業が頻繁に尋ねる質問です。

  fedex archive 'warehouse 47' --service GROUND --json
  

• spend report — ローカルの料金見積もりと発送台帳から、サービス種別、配送レーン、またはアカウントごとの正味料金の合計を算出します。

  「先月、FedEx にいくら使ったか？」は、中小企業の経営者なら誰もが尋ねる質問です。

  fedex spend report --since 30d --by service --json
  

• export — 発送、料金、追跡イベントを CSV または JSON 形式で出力し、QuickBooks／Xero との照合に使用します。

  手作業でデータを入力せずに、会計上の照合作業を完結できます。

  fedex export --format csv --since 30d --output fedex-april.csv
  

• manifest — ローカルアーカイブから、当日作成されたすべての発送の印刷可能な PDF／テキスト概要を生成します。必要に応じて Ground EOD クローズ API を呼び出します。

  1 つのコマンドで、倉庫の一日のワークフローを完結できます。

  fedex manifest --date 2026-05-02 --close --output manifest.md
  

• sql — shipments、rate_quotes、tracking_events、address_validations、addresses テーブルに対して、SQLite の SELECT クエリを直接実行します。

  ローカル台帳に対する任意の分析を可能にする最終手段です。

  fedex sql "select serviceType, count(*) as n, sum(net_charge) as spend from shipments where created_at > date('now','-30 days') group by serviceType order by spend desc"
  

スムーズなセットアップ

• doctor — OAuth 認証、サンドボックス／本番環境のルーティング、アカウント番号の形式、ラベル形式の互換性を検証し、BAG（バーコード分析グループ）の承認状況を表示します。

  初めて使うユーザーによくある「ラベルが印刷できない」という問題を防ぎます。

  fedex doctor
  

コマンドリファレンス

addresses — 住所の検証

• fedex-pp-cli addresses — 1 件以上の住所を検証します（解決／標準化された形式、分類、必要に応じて解決済みの座標）

availability — サービスの利用可否、特別サービスのオプション、配送所要時間

• fedex-pp-cli availability services — 発地／着地の組み合わせで利用可能なサービスを取得します
• fedex-pp-cli availability special_services — 特別サービスの利用可能なオプションを取得します（アルコール、危険物、署名要件など）
• fedex-pp-cli availability transit_times — 発地／着地の組み合わせについて、サービスごとの配送所要時間を取得します

consolidations — 複数の発送を 1 つのフルフィルメントにまとめます（上級者向け。大量の発送を扱う 3PL 向け）

• fedex-pp-cli consolidations add_shipment — 発送を混載に追加します
• fedex-pp-cli consolidations confirm — 混載を確定します（料金を固定し、発送を開始します）
• fedex-pp-cli consolidations confirm_results — 混載確定の結果を取得します
• fedex-pp-cli consolidations create — 混載を作成します
• fedex-pp-cli consolidations delete — 混載を削除します
• fedex-pp-cli consolidations delete_shipment — 混載から発送を削除します
• fedex-pp-cli consolidations modify — 混載を変更します
• fedex-pp-cli consolidations results — 混載の結果を取得します
• fedex-pp-cli consolidations retrieve — 混載を取得します

endofday — Ground の一日の業務終了処理（デイリーマニフェスト）を送信・変更します

• fedex-pp-cli endofday close — Ground の一日の業務終了処理を送信します（当日発送した荷物のマニフェスト）
• fedex-pp-cli endofday modify — 以前の一日の業務終了処理を再送信または変更します

freight_pickups — 貨物（LTL）の集荷を予約、確認、キャンセルします

• fedex-pp-cli freight_pickups availability — 貨物集荷の可否を確認します
• fedex-pp-cli freight_pickups cancel — 貨物集荷をキャンセルします
• fedex-pp-cli freight_pickups create — 貨物 (LTL) 集荷を予約します

freight_shipments — 貨物 (LTL) 発送を作成します (産業向け荷主用)

• fedex-pp-cli freight_shipments — 貨物 (LTL) 発送を作成します

globaltrade — グローバル貿易の規制詳細 (HS コード、制限)

• fedex-pp-cli globaltrade — 規制詳細 (HS コード、統一システム、国別制限) を取得します

locations — FedEx Office、ドロップオフ、集荷場所を検索します

• fedex-pp-cli locations — 住所または郵便番号の近くにある FedEx 拠点を検索します

openship — 確定前に複数個口の発送を段階的に構築します (上級者向け。一般的な中小企業のワークフローでは不要です)

• fedex-pp-cli openship add_package — オープンな発送に荷物を追加します
• fedex-pp-cli openship create — オープンな (未確定の) 複数個口の発送を作成します
• fedex-pp-cli openship delete — オープンな発送を削除します
• fedex-pp-cli openship delete_package — オープンな発送から荷物を削除します
• fedex-pp-cli openship modify — オープンな発送を変更します
• fedex-pp-cli openship modify_package — オープンな発送の荷物を変更します
• fedex-pp-cli openship results — 確定したオープンな発送の結果を取得します
• fedex-pp-cli openship retrieve — インデックスでオープンな発送を取得します
• fedex-pp-cli openship retrieve_package — オープンな発送から特定の荷物を取得します

pickups — Express/Ground の集荷を予約し、可否を確認し、キャンセルします

• fedex-pp-cli pickups availability — 指定した日付に郵便番号で集荷が可能かどうかを確認します
• fedex-pp-cli pickups cancel — 以前に予約した Express/Ground の集荷をキャンセルします
• fedex-pp-cli pickups create — 指定した住所で Express または Ground の集荷を予約します

postal — 郵便番号の検証と国別のサービス提供状況

• fedex-pp-cli postal — FedEx がその国の郵便番号にサービスを提供しているかを検証します

rates — Express、Ground、Home、Ground Economy、貨物の運賃見積もり

• fedex-pp-cli rates quote — 発送の運賃を見積もります (Express/Ground/Home/Ground Economy)
• fedex-pp-cli rates quote_freight — 貨物 (LTL) 発送の運賃を見積もります

shipments — 発送の作成、検証、キャンセル、取得

• fedex-pp-cli shipments cancel — 追跡番号で発送をキャンセルします
• fedex-pp-cli shipments create — 発送を作成し、ラベルを生成します
• fedex-pp-cli shipments results — 非同期の発送ジョブの結果を取得します
• fedex-pp-cli shipments tag — 既存の発送に対して Ground Call Tag (返送ラベル) を作成します
• fedex-pp-cli shipments tag_cancel — Ground Call Tag をキャンセルします
• fedex-pp-cli shipments validate — ラベルを作成せずに発送荷物を検証します (請求前に拒否を検出します)

track — 追跡番号、参照番号、TCN、または関連する発送で発送を追跡します。書類の取得と通知の設定も行います

• fedex-pp-cli track associated — マスター追跡番号に関連する発送を追跡します (複数個口)
• fedex-pp-cli track documents — 追跡書類 (署名による配達証明など) を取得します
• fedex-pp-cli track notifications — 発送の追跡通知 (メール/SMS) を設定します
• fedex-pp-cli track number — 1 回の呼び出しで最大 30 件の追跡番号を追跡します (発送ごとに完全なイベントタイムラインを返します)
• fedex-pp-cli track reference — 参照番号 (PO/顧客参照/RMA) で追跡します
• fedex-pp-cli track tcn — Transportation Control Number で追跡します (軍/政府用途)

手書きのコマンド

• fedex-pp-cli auth login [--client-id <id>] [--client-secret <secret>] [--env sandbox|prod] — client_credentials 経由で OAuth2 ベアラートークンを発行し、ディスクにキャッシュします
• fedex-pp-cli auth logout — キャッシュされたベアラートークンをクリアします
• fedex-pp-cli auth status — キャッシュされたトークンの有効期限と、検出された環境変数を表示します
• fedex-pp-cli rate shop --from <zip> --to <zip> --weight <n>[lb|kg] — 該当するすべてのサービスタイプの運賃を並列で見積もり、コストまたは輸送日数でランク付けします
• fedex-pp-cli ship bulk --csv <path> --service <type> [--output <dir>] [--resume] [--concurrency N] — 適応型レート制限と部分失敗時の再開機能を備え、注文の CSV に対してラベルを作成します
• fedex-pp-cli ship etd --invoice <pdf> --orig <country> --dest <country> ... — 単一コマンドでの電子取引書類（ETD）発送（アップロード + 参照 + 発送を 1 回の呼び出しで実行）
• fedex-pp-cli address save <name> --street <s> --city <c> --state <s> --zip <z> --country <c> — 受取人をローカルアドレス帳に保存します
• fedex-pp-cli address list — ローカルアドレス帳に保存された受取人を一覧表示します
• fedex-pp-cli address delete <name> — ローカルアドレス帳から保存された受取人を削除します
• fedex-pp-cli track diff [--since <duration>] [--tracking <num>...] — 前回のポーリング以降に発生した追跡イベントのみを表示します
• fedex-pp-cli track watch --tracking <num> [--interval <duration>] [--webhook <url>] — ロングポーリングデーモン: 追跡を継続的にポーリングし、新しいイベントを発行します
• fedex-pp-cli return create --tracking <orig-tracking> [--reason <reason>] [--email <addr>] — 既存の配送に対する返品ラベル（Ground Call Tag）を生成します
• fedex-pp-cli spend report [--since <duration>] [--by service|account|lane] — ローカルの発送台帳からサービスタイプごとの純請求額を集計します
• fedex-pp-cli archive <query> — ローカルアーカイブ内の配送を対象とした FTS5 検索
• fedex-pp-cli export [--format csv|json] [--since <duration>] [--output <file>] — 会計照合のために配送履歴をエクスポートします
• fedex-pp-cli manifest [--date YYYY-MM-DD] [--close] [--output <file>] — ローカルアーカイブから日次締めマニフェストレポートを生成します。任意で Ground EOD クローズを実行します
• fedex-pp-cli doctor — 認証、sandbox/prod のルーティング、アカウント番号の形式、ラベル形式の互換性、BAG 承認ステータスを検証します

適切なコマンドの見つけ方

やりたいことはわかっているが、どのコマンドがそれを実行するかわからない場合は、CLI に直接尋ねてください:

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

which は自然言語による機能クエリを、この CLI の厳選された機能インデックスから最も一致するコマンドに解決します。終了コード 0 は少なくとも 1 件の一致を意味し、終了コード 2 は確実な一致がないことを意味します。その場合は --help にフォールバックするか、より絞り込んだクエリを使用してください。

レシピ

運賃を比較して最も安いサービスを選択する

fedex rate shop --from 90210 --to 10001 --weight 5lb --json --select rates.serviceType,rates.totalNetCharge,rates.transitTime

該当するすべてのサービスタイプをコストと輸送時間とともに返すので、エージェント（または人間）が適切なバランスを選択できます。

再開機能付きの一括発送

fedex ship bulk --csv orders.csv --service GROUND --output labels/ --resume --concurrency 2

orders.csv のすべての行に対してラベルを作成し、cliutil.AdaptiveLimiter を介して FedEx の 1 req/s のバースト制限を遵守し、中断された場合は最後に成功した行から再開します。

受取人を保存してその宛先へ発送する

fedex address save acme --street '500 Main St' --city Denver --state CO --zip 80202 --country US

アドレス帳の参照により、発送のたびに受取人の詳細を入力し直す必要がなくなります。

返品ラベルを発行する

fedex return create --tracking 794633071234 --reason damaged --json

元の追跡番号に対して Ground Call Tag を生成します。お客様向けに PDF/ZPL ラベルが出力されます。

サービス別の月次支出レポート

fedex spend report --since 30d --by service --json --select service,total_net_charge,shipment_count

ローカル台帳から配送と運賃見積もりを結合します。今月 FedEx でどこにお金を使ったかを明らかにします。

認証のセットアップ

FedEx は OAuth2 client_credentials を使用します。sandbox または本番の Client ID と Client Secret を指定して fedex auth login を一度実行してください。CLI は 1 時間有効のベアラートークンを発行し、ディスクにキャッシュして、有効期限前にプロアクティブに更新します。本番のラベル印刷には、FedEx によるプロジェクトごとの Bar Code Analysis Group（BAG）承認が必要です。fedex doctor は、実際に問題に直面する前に承認ステータスを表示します。

fedex-pp-cli doctor を実行してセットアップを検証してください。

エージェントモード

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

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

• フィルタリング可能 — --select でフィールドの一部を保持します。ドット区切りのパスでネストされた構造をたどり、配列では要素ごとに処理します。冗長な API でコンテキストを小さく保つうえで重要です：

  fedex-pp-cli addresses --agent --select id,name,status
  

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

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

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

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

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

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

バグ報告ではなく、意外だったことを書いてください。短く、具体的に、1 行で記述します。それが積み重なっていきます。

出力の配信

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

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

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

名前付きプロファイル

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

fedex-pp-cli profile save briefing --json
fedex-pp-cli --profile briefing addresses
fedex-pp-cli profile list --json
fedex-pp-cli profile show briefing
fedex-pp-cli profile delete briefing --yes

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

終了コード

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

引数の解析

$ARGUMENTS を解析します：

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

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

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

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

2. Claude Code に登録します：

   claude mcp add fedex-pp-mcp -- fedex-pp-mcp
   

3. 確認します：claude mcp list

直接使用

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

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

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