pp-amazon-orders

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/commerce/amazon-orders/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/". -->

# Amazon Orders — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `amazon-orders-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 amazon-orders --cli-only
   ```
2. Verify: `amazon-orders-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/amazon-orders/cmd/amazon-orders-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

Reach for amazon-orders-pp-cli when an agent needs to reason across the user's Amazon order history — multi-order tracking radars, recurring-purchase detection, spending rollups, FTS5 searches like 'when did I order that USB-C cable'. The local SQLite store means cross-cutting questions return instantly without re-hitting Amazon and without burning context on full HTML pages.

## When Not to Use This CLI

Do not activate this CLI for requests that require creating, updating, deleting, publishing, commenting, upvoting, inviting, ordering, sending messages, booking, purchasing, or changing remote state. This printed CLI exposes read-only commands for inspection, export, sync, and analysis.

## Unique Capabilities

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

### Local state that compounds
- **`where-is-my-stuff`** — All in-flight Amazon shipments with their current status and ETA in one view.

  _When an agent needs to answer 'is my package coming today' across many orders, this is the one-shot view._

  ```bash
  amazon-orders-pp-cli where-is-my-stuff --json --select orderId,status,etaDate,carrier
  ```
- **`delivery-slips`** — Orders whose actual delivery date slipped more than N days from the original estimate.

  _Surfaces unreliable carriers and sellers without manually scrolling through every order._

  ```bash
  amazon-orders-pp-cli delivery-slips --days 3 --since 2025-01-01 --json
  ```
- **`spend`** — Spending broken down by month, year, category, seller, or payment method.

  _Gives agents a one-shot answer for budgeting, expense reporting, and trend analysis._

  ```bash
  amazon-orders-pp-cli spend --by month --year 2025 --json
  ```
- **`top-items`** — Most-ordered items by frequency or by total spend, ASIN-grouped across all history.

  _Helps an agent reason about what the user actually consumes vs one-off purchases._

  ```bash
  amazon-orders-pp-cli top-items --by total-spend --limit 20 --json
  ```
- **`subscribe-and-save`** — Recurring purchases inferred from order history (same ASIN ordered on a regular cadence).

  _Surfaces candidates for actual S&S enrollment and detects de-facto subscriptions the user may not realize they have._

  ```bash
  amazon-orders-pp-cli subscribe-and-save --min-occurrences 3 --json
  ```
- **`arriving-soon`** — Shipments arriving in the next N days, sorted by ETA.

  _Lets an agent plan around incoming deliveries (e.g. 'is my router arriving before the meeting on Friday?')._

  ```bash
  amazon-orders-pp-cli arriving-soon --days 7 --json
  ```
- **`late`** — Active shipments past their original estimated delivery date.

  _Surfaces carrier delays the moment they happen, no manual review._

  ```bash
  amazon-orders-pp-cli late --json
  ```

### Agent-native plumbing
- **`find`** — FTS5 search across orders, items, sellers, and tracking notes.

  _Direct answer to 'when did I order that thing' without scrolling through years of order history._

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

## Discovery Signals

This CLI was generated with browser-observed traffic context.
- Capture coverage: 6 API entries from 6 total network entries
- Protocols: html_cookie (85% confidence)

## Command Reference

**gift_cards** — Gift card balance and activity history.

- `amazon-orders-pp-cli gift_cards` — Current gift card balance plus the activity log: amounts, kinds (added/applied/refund), dates, linked order IDs.

**orders** — Your buyer-side order history listings and per-order detail pages.

- `amazon-orders-pp-cli orders get` — Full detail for a single order: items, ASINs, prices, shipments, payment method, ship-to address, totals.
- `amazon-orders-pp-cli orders invoice` — Printable invoice for an order (HTML), useful for VAT/expense reconciliation.
- `amazon-orders-pp-cli orders list` — Fetch one page of your order history. Use timeFilter (year-2026, last30days, months-3) and startIndex to paginate.

**shipments** — Per-package tracking details.

- `amazon-orders-pp-cli shipments` — Tracking detail for a single shipment: carrier, tracking number, status, ETA, delivery confirmation.

**transactions** — Charges and refunds across all orders, recurring services, and Prime.

- `amazon-orders-pp-cli transactions` — First page of your transactions list, grouped by date. Each row has payment method, last-4, signed amount, and (when...


**Hand-written commands**

- `amazon-orders-pp-cli sync` — Sync order history into the local SQLite store. Use `--since 90d` for incremental, `--full` to re-walk everything.
- `amazon-orders-pp-cli orders list` — List orders with `--time-filter` (year-YYYY, last30days, months-3) and `--start-index` paging.
- `amazon-orders-pp-cli orders get <order-id>` — Show full detail for one order (items, shipments, payment, totals).
- `amazon-orders-pp-cli orders invoice <order-id>` — Print invoice for one order.
- `amazon-orders-pp-cli shipments --order-id <id>` — Tracking detail for one order's shipments.
- `amazon-orders-pp-cli track <order-id>` — Live tracking for one order: carrier, tracking number, status, ETA.
- `amazon-orders-pp-cli where-is-my-stuff` — All in-flight shipments with current status and ETA in one view.
- `amazon-orders-pp-cli arriving-soon --days 7` — Shipments arriving in the next N days, sorted by ETA.
- `amazon-orders-pp-cli late` — Shipments past their estimated delivery date.
- `amazon-orders-pp-cli delivery-slips --days 3 --since 2025-01-01` — Orders whose actual delivery slipped >N days from the original estimate. (Requires sync history.)
- `amazon-orders-pp-cli spend --by month --year 2026` — Spending rollup by month, year, ship-to, or status.
- `amazon-orders-pp-cli top-items --by count --limit 20` — Most-ordered items / ASINs across history.
- `amazon-orders-pp-cli returns` — Items returned, joined orders <-> transactions. (Requires sync history.)
- `amazon-orders-pp-cli subscribe-and-save --min-occurrences 3` — De-facto subscription detector. (Requires sync history.)
- `amazon-orders-pp-cli carriers --rank` — Per-carrier on-time percentage. (Requires sync history.)
- `amazon-orders-pp-cli find '<query>'` — Free-text search across orders, items, ASINs, sellers.
- `amazon-orders-pp-cli transactions` — Charges and refunds (transactions page parser).
- `amazon-orders-pp-cli gift-cards` — Gift card balance + activity log.


## Freshness Contract

This printed CLI owns bounded freshness only for registered store-backed read command paths. In