pp-fedex

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

FedEx — Printing Press CLI

Prerequisites: Install the CLI

前提条件：安装CLI

This skill drives the

fedex-pp-cli

binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:

Install via the Printing Press installer:

bash

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

Verify:
```
fedex-pp-cli --version
```
Ensure
```
$GOPATH/bin
```
(or
```
$HOME/go/bin
```
) is on
```
$PATH
```
.

If the

npx

install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.23+):

bash

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

--version

reports "command not found" after install, the install step did not put the binary on

$PATH

. Do not proceed with skill commands until verification succeeds.

本技能基于

fedex-pp-cli

二进制文件运行。在调用本技能的任何命令之前，您必须确认CLI已安装。 如果未安装，请先执行以下步骤：

通过Printing Press安装器安装：

bash

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

验证安装：
```
fedex-pp-cli --version
```
确保
```
$GOPATH/bin
```
（或
```
$HOME/go/bin
```
）已添加到
```
$PATH
```
环境变量中。

如果

npx

安装失败（无Node环境、离线等），可改用Go直接安装（要求Go 1.23+版本）：

bash

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

如果安装后执行

--version

提示“command not found”，说明安装程序未将二进制文件添加到

$PATH

中。请在验证成功前不要执行技能命令。

When to Use This CLI

何时使用此CLI

Use fedex-pp-cli when you run a small-to-medium shipping operation and want to programmatically interact with the FedEx REST API. Right fit for: e-commerce stores creating labels from order CSVs, customer-service teams generating return labels, ops teams tracking in-flight shipments, and SMB owners who want a local ledger of every shipment and rate quote for accounting. The local SQLite archive makes it the right tool for analytical queries over historical shipments. Choose this CLI over multi-carrier SaaS (ShipStation, Shippo) when you only need FedEx, want to own your data, and prefer terminal/agent automation over web UIs.

当您运营中小型物流业务，希望通过编程方式与FedEx REST API交互时，可使用fedex-pp-cli。适用于：从订单CSV生成标签的电商店铺、生成退货标签的客服团队、跟踪在途包裹的运营团队，以及需要本地账本记录所有发货和报价信息用于会计核算的中小企业主。本地SQLite归档功能使其成为对历史发货数据进行分析查询的理想工具。当您仅需使用FedEx服务、希望自主掌控数据，且偏好终端/Agent自动化而非Web界面时，选择此CLI而非多承运商SaaS工具（如ShipStation、Shippo）。

Unique Capabilities

独特功能

These capabilities aren't available in any other tool for this API.

以下功能是其他同类型API工具所不具备的。

Save money, save time

省钱又省时

rate shop
— Quote rates across every applicable service type in parallel and rank by cost, transit days, or cost-per-day.
When picking the cheapest viable service for a shipment, this collapses 6+ API calls into one ranked answer. The headline cost-saving command for SMB shippers.
bash
```
fedex rate shop --from 90210 --to 10001 --weight 5lb --json --select rates.serviceType,rates.totalNetCharge,rates.transitTime
```
ship bulk
— Create labels for a CSV of orders with adaptive rate limiting, per-row PASS/FAIL accounting, and resume-from-last-success.
The 'I ship 30 packages a day' workflow. Replaces clicking through FedEx Ship Manager one label at a time.
bash
```
fedex ship bulk --csv orders.csv --service GROUND --output labels/ --resume
```
return create
— Generate a Ground Call Tag (return label) against an existing tracking number with one command, optionally emailing it to the recipient.
E-commerce customer-service workflow. Issuing a return label is the most common post-sale interaction.
bash
```
fedex return create --tracking 794633071234 --reason damaged --email customer@example.com
```
address validate
— SHA-256-keyed local cache prevents re-billing the FedEx Address Validation API for repeat lookups.
Direct cost savings — the only feature with a quantifiable per-call $ impact.
bash
```
fedex address validate --street '1600 Amphitheatre Pkwy' --city 'Mountain View' --state CA --zip 94043 --country US --cache
```
ship etd
— Single-command Electronic Trade Documents shipping: uploads commercial invoice, captures docId, and stitches it into the shipment create call.
International shipments require ETD; this collapses an error-prone multi-step into one atomic action.
bash
```
fedex ship etd --invoice invoice.pdf --orig CN --dest US --recipient-name 'Acme' --weight 2kg --service FEDEX_INTERNATIONAL_PRIORITY
```

rate shop
— 并行查询所有适用服务类型的报价，并按成本、运输天数或日均成本排序。
为包裹选择最便宜的可行服务时，此命令将6次以上的API调用合并为一个排序后的结果。这是中小企业托运人节省成本的核心命令。
bash
```
fedex rate shop --from 90210 --to 10001 --weight 5lb --json --select rates.serviceType,rates.totalNetCharge,rates.transitTime
```
ship bulk
— 为订单CSV批量创建标签，支持自适应速率限制、逐行成功/失败统计，以及从上次成功处恢复的功能。
适用于“每天发货30个包裹”的工作流，替代在FedEx Ship Manager中逐个点击创建标签的操作。
bash
```
fedex ship bulk --csv orders.csv --service GROUND --output labels/ --resume
```
return create
— 通过一条命令针对现有运单编号生成Ground Call Tag（退货标签），可选择将其发送至收件人邮箱。
电商客服工作流必备。生成退货标签是最常见的售后交互场景。
bash
```
fedex return create --tracking 794633071234 --reason damaged --email customer@example.com
```
address validate
— 基于SHA-256的本地缓存可避免重复查询FedEx地址验证API产生的重复计费。
直接节省成本——这是唯一可量化每次调用成本影响的功能。
bash
```
fedex address validate --street '1600 Amphitheatre Pkwy' --city 'Mountain View' --state CA --zip 94043 --country US --cache
```
ship etd
— 一键式电子贸易文件（ETD）发货：上传商业发票、获取docId并将其整合到发货创建请求中。
国际发货需要ETD；此命令将易出错的多步骤操作简化为一个原子操作。
bash
```
fedex ship etd --invoice invoice.pdf --orig CN --dest US --recipient-name 'Acme' --weight 2kg --service FEDEX_INTERNATIONAL_PRIORITY
```

Local state that compounds

可累积的本地状态

address save
— Save frequently-used recipients to a local address book; reference them by name in ship commands.
Ergonomic parity with paid SaaS competitors. Eliminates retyping addresses for repeat customers.
bash
```
fedex address save acme --street '500 Main St' --city Denver --state CO --zip 80202 --country US
```
track diff
— Show only the tracking events that have appeared since the last poll for each tracking number in the local store.
Replaces tracking-poll dedupe glue agents would otherwise write.
bash
```
fedex track diff --since 1h --json
```
track watch
— Continuously poll a set of tracking numbers and emit new events to stdout, a webhook, or a file as they arrive. Polling alternative to FedEx push notifications.
Most SMBs don't have provisioned push webhooks. Polling daemon is the universal alternative.
bash
```
fedex track watch --tracking 794633071234 --interval 10m --webhook https://example.com/hook
```
archive
— SQLite FTS5 search across every shipment in the local archive — recipient name, address, reference, tracking number, service.
'Did we ship to ACME last week?' — a question SMBs ask constantly.
bash
```
fedex archive 'warehouse 47' --service GROUND --json
```
spend report
— Sum of net charges per service type, lane, or account from the local rate-quote and shipment ledger.
'How much did I spend on FedEx last month?' — the question every SMB owner asks.
bash
```
fedex spend report --since 30d --by service --json
```
export
— Dump shipments + charges + tracking events as CSV or JSON for QuickBooks/Xero reconciliation.
Closes the loop on accounting reconciliation without manual data entry.
bash
```
fedex export --format csv --since 30d --output fedex-april.csv
```
manifest
— Generate a printable PDF/text summary of every shipment created today from the local archive, optionally invoking the Ground EOD close API.
Closes the warehouse-day workflow loop in one command.
bash
```
fedex manifest --date 2026-05-02 --close --output manifest.md
```
sql
— Direct SQLite SELECT queries against shipments, rate_quotes, tracking_events, address_validations, addresses tables.
Escape hatch for arbitrary analytics over the local ledger.
bash
```
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"
```

address save
— 将常用收件人保存到本地地址簿；在发货命令中可通过名称引用他们。
达到与付费SaaS竞品相同的易用性，避免为重复客户重复输入地址。
bash
```
fedex address save acme --street '500 Main St' --city Denver --state CO --zip 80202 --country US
```
track diff
— 仅显示本地存储中每个运单编号自上次查询以来新增的跟踪事件。
替代Agent原本需要编写的跟踪查询去重逻辑。
bash
```
fedex track diff --since 1h --json
```
track watch
— 持续轮询一组运单编号，并在有新事件到达时将其输出到标准输出、Webhook或文件。作为FedEx推送通知的轮询替代方案。
大多数中小企业没有配置推送Webhook，轮询守护进程是通用的替代方案。
bash
```
fedex track watch --tracking 794633071234 --interval 10m --webhook https://example.com/hook
```
archive
— 通过SQLite FTS5搜索本地归档中的所有发货记录，包括收件人姓名、地址、参考编号、运单编号、服务类型。
解决中小企业常问的问题：“我们上周给ACME发货了吗？”
bash
```
fedex archive 'warehouse 47' --service GROUND --json
```
spend report
— 从本地报价和发货账本中按服务类型、运输路线或账户汇总净费用。
解决每个中小企业主都会问的问题：“我上个月在FedEx上花了多少钱？”
bash
```
fedex spend report --since 30d --by service --json
```
export
— 将发货记录+费用+跟踪事件导出为CSV或JSON格式，用于QuickBooks/Xero对账。
无需手动录入数据即可完成会计对账闭环。
bash
```
fedex export --format csv --since 30d --output fedex-april.csv
```
manifest
— 从本地归档生成当日所有发货记录的可打印PDF/文本摘要，可选择调用Ground EOD关闭API。
一键完成仓库每日工作流闭环。
bash
```
fedex manifest --date 2026-05-02 --close --output manifest.md
```
sql
— 直接对shipments、rate_quotes、tracking_events、address_validations、addresses表执行SQLite SELECT查询。
为本地账本的任意分析提供灵活出口。
bash
```
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"
```

Setup smoothness

流畅的设置体验

doctor
— Verifies OAuth auth, sandbox/prod routing, account-number format, label-format compatibility, and surfaces BAG (Bar Code Analysis Group) approval status.
Avoids the most common 'why won't my labels print' failure mode for first-time users.
bash
```
fedex doctor
```

doctor
— 验证OAuth授权、沙箱/生产环境路由、账户编号格式、标签格式兼容性，并显示BAG（条码分析组）审批状态。
避免首次用户最常见的“为什么我的标签无法打印”问题。
bash
```
fedex doctor
```

Command Reference

命令参考

addresses — Address validation

```
fedex-pp-cli addresses
```
— Validate one or more addresses (resolved/standardized form, classification, optional resolved coordinates)

availability — Service availability, special-service options, and transit times

```
fedex-pp-cli availability services
```
— Get available services for an origin/destination pair
```
fedex-pp-cli availability special_services
```
— Get available special-service options (alcohol, dangerous goods, signature requirements, etc.)
```
fedex-pp-cli availability transit_times
```
— Get transit times for an origin/destination pair across services

consolidations — Consolidate multiple shipments into one fulfillment (advanced; for high-volume 3PLs)

fedex-pp-cli consolidations add_shipment

— Add shipments to a consolidation

```
fedex-pp-cli consolidations confirm
```
— Confirm a consolidation (locks rates and triggers shipping)
```
fedex-pp-cli consolidations confirm_results
```
— Get results of a consolidation confirmation
```
fedex-pp-cli consolidations create
```
— Create a consolidation
```
fedex-pp-cli consolidations delete
```
— Delete a consolidation

fedex-pp-cli consolidations delete_shipment

— Remove a shipment from a consolidation

```
fedex-pp-cli consolidations modify
```
— Modify a consolidation
```
fedex-pp-cli consolidations results
```
— Get consolidation results
```
fedex-pp-cli consolidations retrieve
```
— Retrieve a consolidation

endofday — Submit and modify Ground end-of-day close (daily manifest)

```
fedex-pp-cli endofday close
```
— Submit Ground end-of-day close (manifest packages shipped today)
```
fedex-pp-cli endofday modify
```
— Re-submit or modify a previous end-of-day close

freight_pickups — Schedule, check, and cancel freight (LTL) pickups

fedex-pp-cli freight_pickups availability

— Check freight pickup availability

```
fedex-pp-cli freight_pickups cancel
```
— Cancel a freight pickup
```
fedex-pp-cli freight_pickups create
```
— Schedule a freight (LTL) pickup

freight_shipments — Create freight (LTL) shipments (for industrial shippers)

```
fedex-pp-cli freight_shipments
```
— Create a freight (LTL) shipment

globaltrade — Global trade regulatory details (HS codes, restrictions)

```
fedex-pp-cli globaltrade
```
— Get regulatory details (HS codes, harmonized system, country restrictions)

locations — Find FedEx Office, dropoff, and pickup locations

```
fedex-pp-cli locations
```
— Find FedEx locations near an address or postal code

openship — Build multi-piece shipments progressively before confirming (advanced; not needed for typical SMB workflows)

```
fedex-pp-cli openship add_package
```
— Add a package to an open shipment
```
fedex-pp-cli openship create
```
— Create an open (uncommitted) multi-piece shipment
```
fedex-pp-cli openship delete
```
— Delete an open shipment
```
fedex-pp-cli openship delete_package
```
— Delete a package from an open shipment
```
fedex-pp-cli openship modify
```
— Modify an open shipment
```
fedex-pp-cli openship modify_package
```
— Modify a package in an open shipment
```
fedex-pp-cli openship results
```
— Get results of a confirmed open shipment
```
fedex-pp-cli openship retrieve
```
— Retrieve an open shipment by index
```
fedex-pp-cli openship retrieve_package
```
— Retrieve a specific package from an open shipment

pickups — Schedule, check availability, and cancel Express/Ground pickups

```
fedex-pp-cli pickups availability
```
— Check whether pickup is available for a postal code on a date
```
fedex-pp-cli pickups cancel
```
— Cancel a previously-scheduled Express/Ground pickup
```
fedex-pp-cli pickups create
```
— Schedule an Express or Ground pickup at a specified address

postal — Postal code validation and country servicing

```
fedex-pp-cli postal
```
— Validate that FedEx services a postal code in a country

rates — Rate quotes for Express, Ground, Home, Ground Economy, and freight

```
fedex-pp-cli rates quote
```
— Quote rates for a shipment (Express/Ground/Home/Ground Economy)
```
fedex-pp-cli rates quote_freight
```
— Quote rates for freight (LTL) shipments

shipments — Create, validate, cancel, and retrieve shipments

```
fedex-pp-cli shipments cancel
```
— Cancel a shipment by tracking number
```
fedex-pp-cli shipments create
```
— Create a shipment and generate label(s)
```
fedex-pp-cli shipments results
```
— Retrieve results of an asynchronous shipment job
```
fedex-pp-cli shipments tag
```
— Create a Ground Call Tag (return label) for an existing shipment
```
fedex-pp-cli shipments tag_cancel
```
— Cancel a Ground Call Tag
```
fedex-pp-cli shipments validate
```
— Validate a shipment package without creating a label (catches rejections before billing)

track — Track shipments by tracking number, reference, TCN, or associated shipment; retrieve documents and configure notifications

```
fedex-pp-cli track associated
```
— Track shipments associated with a master tracking number (multi-piece)
```
fedex-pp-cli track documents
```
— Retrieve tracking documents (signature proof of delivery, etc.)
```
fedex-pp-cli track notifications
```
— Configure tracking notifications (email/SMS) for a shipment
```
fedex-pp-cli track number
```
— Track up to 30 tracking numbers in one call (returns full event timeline per shipment)
```
fedex-pp-cli track reference
```
— Track by reference number (PO/customer ref/RMA)
```
fedex-pp-cli track tcn
```
— Track by Transportation Control Number (military/government use)

Hand-written commands

fedex-pp-cli auth login [--client-id <id>] [--client-secret <secret>] [--env sandbox|prod]

— Mint an OAuth2 bearer token via client_credentials and cache it on disk

```
fedex-pp-cli auth logout
```
— Clear the cached bearer token
```
fedex-pp-cli auth status
```
— Show the cached token's expiry and which env vars were detected
```
fedex-pp-cli rate shop --from <zip> --to <zip> --weight <n>[lb|kg]
```
— Quote rates across every applicable service type in parallel and rank by cost or transit

fedex-pp-cli ship bulk --csv <path> --service <type> [--output <dir>] [--resume] [--concurrency N]

— Create labels for a CSV of orders with adaptive rate limiting and resumable on partial failure

```
fedex-pp-cli ship etd --invoice <pdf> --orig <country> --dest <country> ...
```
— Single-command Electronic Trade Documents shipping (upload + reference + ship in one call)

fedex-pp-cli address save <name> --street <s> --city <c> --state <s> --zip <z> --country <c>

— Save a recipient to the local address book

```
fedex-pp-cli address list
```
— List saved recipients in the local address book
```
fedex-pp-cli address delete <name>
```
— Delete a saved recipient from the local address book
```
fedex-pp-cli track diff [--since <duration>] [--tracking <num>...]
```
— Show only tracking events that have appeared since the last poll

fedex-pp-cli track watch --tracking <num> [--interval <duration>] [--webhook <url>]

— Long-poll daemon: continuously poll tracking and emit new events

fedex-pp-cli return create --tracking <orig-tracking> [--reason <reason>] [--email <addr>]

— Generate a return label (Ground Call Tag) for an existing shipment

fedex-pp-cli spend report [--since <duration>] [--by service|account|lane]

— Sum net charges per service type from the local shipment ledger

```
fedex-pp-cli archive <query>
```
— FTS5 search across shipments in the local archive

fedex-pp-cli export [--format csv|json] [--since <duration>] [--output <file>]

— Export shipment history for accounting reconciliation

```
fedex-pp-cli manifest [--date YYYY-MM-DD] [--close] [--output <file>]
```
— Generate end-of-day manifest report from local archive; optionally fire Ground EOD close
```
fedex-pp-cli doctor
```
— Verify auth, sandbox/prod routing, account-number format, label-format compatibility, BAG approval status

addresses — 地址验证

```
fedex-pp-cli addresses
```
— 验证一个或多个地址（返回解析/标准化格式、分类、可选的解析坐标）

availability — 服务可用性、特殊服务选项和运输时间

```
fedex-pp-cli availability services
```
— 获取指定起运地/目的地对的可用服务
```
fedex-pp-cli availability special_services
```
— 获取可用的特殊服务选项（酒类、危险品、签名要求等）
```
fedex-pp-cli availability transit_times
```
— 获取指定起运地/目的地对在不同服务下的运输时间

consolidations — 将多个发货合并为一个履行单（高级功能；适用于高容量第三方物流商）

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
```
— 一次跟踪最多30个运单编号（返回每个发货单的完整事件 timeline）
```
fedex-pp-cli track reference
```
— 通过参考编号跟踪（PO/客户参考/RMA）
```
fedex-pp-cli track tcn
```
— 通过运输控制编号跟踪（军事/政府用途）

手写命令

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）发货（上传+引用+发货一步完成）

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
```
— 验证授权、沙箱/生产环境路由、账户编号格式、标签格式兼容性、BAG审批状态

Finding the right command

查找合适的命令

When you know what you want to do but not which command does it, ask the CLI directly:

bash

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

which

resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code

means at least one match; exit code

means no confident match — fall back to

--help

or use a narrower query.

当您知道要做什么但不知道对应命令时，可直接询问CLI：

bash

fedex-pp-cli which "<用您自己的语言描述功能>"

which

命令会将自然语言功能查询解析为CLI精选功能索引中最匹配的命令。退出码

表示至少有一个匹配项；退出码

表示没有确定的匹配项——此时可使用

--help

或更精确的查询。

Recipes

使用示例

Rate-shop and select cheapest service

比价并选择最便宜的服务

bash

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

Returns every applicable service type with cost and transit time so the agent (or human) picks the right balance.

bash

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

返回所有适用服务类型的成本和运输时间，以便Agent或人工选择最合适的方案。

Bulk ship with resume

批量发货并支持恢复

bash

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

Creates labels for every row in orders.csv, respects the FedEx 1 req/s burst limit via cliutil.AdaptiveLimiter, and resumes from the last successful row if interrupted.

bash

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

为orders.csv中的每一行创建标签，通过cliutil.AdaptiveLimiter遵守FedEx每秒1次请求的突发限制，并在中断时从上次成功的行恢复。

Save a recipient and ship to them

保存收件人并向其发货

bash

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

Address book lookup avoids retyping recipient details across every shipment.

bash

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

地址簿查询功能避免为重复客户重复输入收件人信息。

Issue a return label

生成退货标签

bash

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

Generates a Ground Call Tag against the original tracking; PDF/ZPL label is emitted for the customer.

bash

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

针对原始运单编号生成Ground Call Tag；为客户输出PDF/ZPL标签。

Monthly spend report by service

按服务类型统计月度支出

bash

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

Joins shipments + rate quotes from the local ledger; answers 'where did I spend money on FedEx this month'.

bash

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

关联本地账本中的发货记录和报价；回答“我这个月在FedEx的哪些服务上花了钱”。

Auth Setup

授权设置

FedEx uses OAuth2 client_credentials. Run

fedex auth login

once with your sandbox or production Client ID and Client Secret; the CLI mints a 1-hour bearer token, caches it on disk, and refreshes proactively before expiry. Production label printing requires per-project Bar Code Analysis Group (BAG) approval from FedEx —

fedex doctor

surfaces approval status before you hit it.

Run

fedex-pp-cli doctor

to verify setup.

FedEx使用OAuth2 client_credentials认证。使用您的沙箱或生产环境Client ID和Client Secret运行一次

fedex auth login

；CLI会生成一个1小时有效期的令牌，缓存到磁盘，并在过期前主动刷新。生产环境标签打印需要FedEx的每个项目条码分析组（BAG）审批——

fedex doctor

会在您遇到问题前显示审批状态。

运行

fedex-pp-cli doctor

验证设置。

Agent Mode

Agent模式

Add

--agent

to any command. Expands to:

--json --compact --no-input --no-color --yes

Pipeable — JSON on stdout, errors on stderr
Filterable —
```
--select
```
keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs:
bash
```
fedex-pp-cli addresses --agent --select id,name,status
```
Previewable —
```
--dry-run
```
shows the request without sending
Non-interactive — never prompts, every input is a flag

在任何命令后添加

--agent

参数。等效于：

--json --compact --no-input --no-color --yes

。

可管道化 — JSON输出到标准输出，错误输出到标准错误
可过滤 —
```
--select
```
参数保留字段子集。点路径可深入嵌套结构；数组可遍历每个元素。对于冗长的API，这是保持上下文简洁的关键：
bash
```
fedex-pp-cli addresses --agent --select id,name,status
```
可预览 —
```
--dry-run
```
参数显示请求但不发送
非交互式 — 从不提示，所有输入均通过标志参数提供

Agent Feedback

Agent反馈

When you (or the agent) notice something off about this CLI, record it:

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

Entries are stored locally at

~/.fedex-pp-cli/feedback.jsonl

. They are never POSTed unless

FEDEX_FEEDBACK_ENDPOINT

is set AND either

--send

is passed or

FEDEX_FEEDBACK_AUTO_SEND=true

. Default behavior is local-only.

Write what surprised you, not a bug report. Short, specific, one line: that is the part that compounds.

当您（或Agent）发现此CLI存在问题时，可记录反馈：

fedex-pp-cli feedback "--since标志是包含性的，但文档说是排他性的"
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

，否则不会自动发送。默认行为仅存储在本地。

记录您感到意外的内容，而非正式的错误报告。简短、具体、单行描述：这样的反馈才能不断积累价值。

Output Delivery

输出交付

Every command accepts

--deliver <sink>

. The output goes to the named sink in addition to (or instead of) stdout, so agents can route command results without hand-piping. Three sinks are supported:

Sink	Effect
`stdout`	Default; write to stdout only
`file:<path>`	Atomically write output to `<path>` (tmp + rename)
`webhook:<url>`	POST the output body to the URL ( `application/json` or `application/x-ndjson` when `--compact` )

Unknown schemes are refused with a structured error naming the supported set. Webhook failures return non-zero and log the URL + HTTP status on stderr.

每个命令都支持

--deliver <sink>

参数。输出将发送到指定目标，同时（或替代）输出到标准输出，以便Agent无需手动管道即可路由命令结果。支持三种目标：

输出目标	效果
`stdout`	默认值；仅输出到标准输出
`file:<path>`	原子性地将输出写入 `<path>` （先写入临时文件再重命名）
`webhook:<url>`	将输出内容POST到指定URL（ `application/json` 格式，使用 `--compact` 时为 `application/x-ndjson` 格式）

不支持的协议会返回结构化错误，并列出支持的类型。Webhook失败时返回非零退出码，并在标准错误中记录URL和HTTP状态码。

Named Profiles

命名配置文件

A profile is a saved set of flag values, reused across invocations. Use it when a scheduled agent calls the same command every run with the same configuration - HeyGen's "Beacon" pattern.

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

Explicit flags always win over profile values; profile values win over defaults.

agent-context

lists all available profiles under

available_profiles

so introspecting agents discover them at runtime.

配置文件是一组保存的标志值，可在多次调用中复用。适用于定时Agent每次运行相同命令且配置相同的场景——即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

下列出所有可用配置文件，以便自省Agent在运行时发现它们。

Exit Codes

退出码

Code	Meaning
0	Success
2	Usage error (wrong arguments)
3	Resource not found
4	Authentication required
5	API error (upstream issue)
7	Rate limited (wait and retry)
10	Config error

代码	含义
0	成功
2	使用错误（参数错误）
3	资源未找到
4	需要认证
5	API错误（上游问题）
7	速率限制（请等待并重试）
10	配置错误

Argument Parsing

参数解析

Parse

$ARGUMENTS

Empty,
help
, or
--help
→ show
```
fedex-pp-cli --help
```
output
Starts with
install
→ ends with
```
mcp
```
→ MCP installation; otherwise → see Prerequisites above
Anything else → Direct Use (execute as CLI command with
```
--agent
```
)

解析

$ARGUMENTS

的规则：

为空、
help
或
--help
→ 显示
```
fedex-pp-cli --help
```
输出
以
install
开头 → 若结尾为
```
mcp
```
→ 安装MCP；否则 → 参见顶部的前提条件
其他情况 → 直接使用（添加
```
--agent
```
参数执行CLI命令）

MCP Server Installation

MCP服务器安装

Install the MCP server:

bash

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

bash

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

Verify:
```
claude mcp list
```

安装MCP服务器：

bash

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

在Claude Code中注册：

bash

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

验证：
```
claude mcp list
```

Direct Use

直接使用

Check if installed:
```
which fedex-pp-cli
```
If not found, offer to install (see Prerequisites at the top of this skill).
Match the user query to the best command from the Unique Capabilities and Command Reference above.

Execute with the

--agent

flag:

bash

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

If ambiguous, drill into subcommand help:
```
fedex-pp-cli <command> --help
```
.

检查是否安装：
```
which fedex-pp-cli
```
如果未找到，提供安装选项（参见顶部的前提条件）。
将用户查询与上述独特功能和命令参考中的最佳命令匹配。

添加

--agent

参数执行：

bash

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

如果存在歧义，查看子命令帮助：
```
fedex-pp-cli <command> --help
```
。