Walk your Amazon order history offline — every order, item, shipment, and dollar in a local SQLite store no other tool gives you.
Sync once and ask cross-cutting questions forever. Where is my stuff right now, what did I spend last quarter, which deliveries are slipping, when did I order that thing — answered in milliseconds without re-hitting the live site or burning agent context on full HTML pages.
Learn more at Amazon Orders.
Authentication
Amazon publishes no buyer API. The CLI imports cookies from your logged-in Chrome / Firefox / Safari / Brave session via auth login --chrome. Those cookies persist locally, refresh automatically, and authenticate every subsequent fetch — no API key, no OAuth, no resident browser at runtime.
Headless agents (1Password / Vault / Bitwarden)
For CI, dev containers, and remote hosts where auth login --chrome is not viable, capture the session once on a logged-in machine and inject it on every other host via your secrets manager. The cookie value never enters an LLM's context window because the bytes flow op → stdin → CLI without a shell variable in the middle.
# Stash once (logged-in machine):
amazon-orders-pp-cli auth export | op document create - --title amazon-orders-session --vault Agent
# Inject on any other machine:
op read "op://Agent/amazon-orders-session/file" | amazon-orders-pp-cli auth import --stdin
The exported JSON shape is amazon-orders-session/v1. auth import also accepts --input <file>, the AMAZON_COOKIES env var, or a raw "k=v; k=v" cookie string with --raw-cookies. See SKILL.md ("Headless agent setup with 1Password") for the refresh recipe and substitutes for vault kv get, aws secretsmanager, pass, and bw.
Quick Start
# Import cookies from your logged-in browser session — required for any authenticated fetch.
amazon-orders-pp-cli auth login --chrome
# Walk the last 3 months of orders into the local store, including per-order item detail.
amazon-orders-pp-cli sync --since 90d --concurrency 1
# See every in-flight package with current status and ETA.
amazon-orders-pp-cli where-is-my-stuff --json
# Roll up your 2026 Amazon spending by month.
amazon-orders-pp-cli spend --by month --year 2026 --json
# Find every order containing 'usb-c cable' — FTS5-backed, instant, offline.
amazon-orders-pp-cli find 'usb-c cable' --json
Unique Features
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.
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.
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.
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.
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.
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?').
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.
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.
amazon-orders-pp-cli find 'usb-c cable' --json --select orderId,placedDate,total
Usage
Run amazon-orders-pp-cli --help for the full command reference and flag list.
Commands
gift_cards
Gift card balance and activity history.
amazon-orders-pp-cli gift_cards balance - 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 track - 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 list - First page of your transactions list, grouped by date. Each row has payment method, last-4, signed amount, and (when applicable) the linked order ID.
Output Formats
# Human-readable table (default in terminal, JSON when piped)
amazon-orders-pp-cli orders list
# JSON for scripting and agents
amazon-orders-pp-cli orders list --json
# Filter to specific fields
amazon-orders-pp-cli orders list --json --select id,name,status
# Dry run — show the request without sending
amazon-orders-pp-cli orders list --dry-run
# Agent mode — JSON + compact + no prompts in one flag
amazon-orders-pp-cli orders list --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Read-only by default - this CLI does not create, update, delete, publish, send, or mutate remote resources
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Freshness
This CLI owns bounded freshness for registered store-backed read command paths. In --data-source auto mode, covered commands check the local SQLite store before serving results; stale or missing resources trigger a bounded refresh, and refresh failures fall back to the existing local data with a warning. --data-source local never refreshes, and --data-source live reads the API without mutating the local store.
Set AMAZON_ORDERS_NO_AUTO_REFRESH=1 to disable the pre-read freshness hook while preserving the selected data source.
Covered command paths:
amazon-orders-pp-cli ordersamazon-orders-pp-cli orders getamazon-orders-pp-cli orders invoiceamazon-orders-pp-cli orders listamazon-orders-pp-cli transactions
JSON outputs that use the generated provenance envelope include freshness metadata at meta.freshness. This metadata describes the freshness decision for the covered command path; it does not claim full historical backfill or API-specific enrichment.
Health Check
amazon-orders-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Config file: ~/.config/amazon-orders-pp-cli/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
AMAZON_COOKIES | per_call | Yes | Set to your API credential. |
Troubleshooting
Authentication errors (exit code 4)
- Run
amazon-orders-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $AMAZON_COOKIES
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
auth status reports unauthenticated after auth login --chrome — Make sure you're logged in to amazon.com in Chrome, then re-run auth login --chrome --domain amazon.com.sync fails with RateLimitError after ~10 orders — Pass --rate 0.5 to slow the per-order detail fetch, or omit --full-details to fetch only the listing pages.- Order detail returns 401 even when logged in — Amazon rotated your session-id; re-run
auth login --chrome to refresh cookies.
track <id> returns empty when the order has multiple shipments — Pass --shipment-id <SID> (visible in orders get <id> --json) to disambiguate.- Foreign-locale orders parse with garbled dates — v1 supports US (.com) only. Multi-region shipping in v2; track issue.
Discovery Signals
This CLI was generated with browser-captured traffic analysis.
Sources & Inspiration
This CLI was built by studying these projects and resources:
Generated by CLI Printing Press