pp-fedex

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/commerce/fedex/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# FedEx — Printing Press CLI

## Prerequisites: Install the 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:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install fedex --cli-only
   ```
2. Verify: `fedex-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill.

If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):

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

If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds.

## When to Use This 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.

## Unique Capabilities

These capabilities aren't available in any other tool for this 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 [email protected]
  ```
- **`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
  ```

### 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"
  ```

### 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
  ```

## 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
- `fed