Costco CLI

Your complete Costco receipt history as data — past the website's 2-year wall, in a local database the site never gives you.

Costco's site shows receipts in 6-month chunks up to 2 years, but the backend serves more. This CLI pulls in-warehouse, gas, and online purchase history over any date range, probes how far back your account actually goes with history-depth, computes spend and item-price-history analytics on the fly, and builds a local SQLite archive (sync) for offline SQL and search.

Learn more at Costco.

Created by @richie305 (David Richie).

Authentication

Costco's receipts API uses a short-lived bearer token (idToken) that your browser stores in localStorage after login. Capture it once from DevTools (localStorage.idToken and localStorage.clientID) and set it with auth set-token; the token expires in minutes, so doctor decodes its expiry and tells you when to refresh. No cookies or password are stored.

Quick Start

# Check token presence and JWT expiry before anything else
costco-pp-cli doctor

# Find how far back the API actually serves your receipts
costco-pp-cli history-depth

# Pull in-warehouse receipts for a date range
costco-pp-cli receipts --since 2024-01-01

# Build the local SQLite archive for offline search and analytics
costco-pp-cli sync

# Roll up spend the website never computes
costco-pp-cli spend --by month

Unique Features

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

Reach past the UI

• history-depth — Discover how far back your Costco receipts actually go, past the website's 2-year UI cap.

  Reach for this to answer 'can I get receipts older than two years' — it probes the live API boundary instead of trusting the UI.

  costco-pp-cli history-depth --json
  

Local state that compounds

• spend — Roll up your spend by month, warehouse, or department over a date range.

  Use when an agent needs spend totals or trends the website never computes.

  costco-pp-cli spend --by month --json
  

• savings — Total the instant savings and coupons you captured over a date range.

  Use to quantify how much Costco deals actually saved you.

  costco-pp-cli savings --since 2024-01-01 --json
  

• returns-window — Flag recently purchased items still inside a return window you set.

  Reach for this to find what you can still return before a deadline.

  costco-pp-cli returns-window --days 90 --json
  

Spend insight

• item-history — Track one item's unit price across every receipt over time.

  Pick this to see whether a recurring buy has crept up in price.

  costco-pp-cli item-history "rotisserie chicken" --json
  

Recipes

Find your true history floor

costco-pp-cli history-depth --json

Steps startDate backward and reports the earliest receipt the API will serve for your account.

Export receipts to a spreadsheet

costco-pp-cli receipts --since 2024-01-01 --csv

Flat line-item CSV ready for budgeting tools.

Narrow a verbose receipt payload for an agent

costco-pp-cli receipts --since 2025-01-01 --agent --select transactionDate,warehouseName,total

Receipts list output is a flat array; --select trims each row to just the fields an agent needs.

See spend by warehouse

costco-pp-cli spend --by warehouse --json

Aggregates local receipts into per-warehouse spend totals.

What can I still return?

costco-pp-cli returns-window --days 90 --json

Lists recently bought items still inside a 90-day window from their receipt date.

Usage

Run costco-pp-cli --help for the full command reference and flag list.

Paths & environment variables

This CLI separates local files into four path kinds:

Kind	Contents
config	User-editable settings such as config.toml and saved profiles
data	Durable local data: credentials.toml, data.db, cookies, browser-session proof files, and other auth sidecars
state	Runtime state such as persisted queries, jobs, and teach.log
cache	Regenerable HTTP/cache files

Each kind resolves independently. The ladder is:

1. Per-kind env var: COSTCO_CONFIG_DIR, COSTCO_DATA_DIR, COSTCO_STATE_DIR, or COSTCO_CACHE_DIR
2. --home <dir> for this invocation
3. COSTCO_HOME for a flat relocated root
4. XDG env vars: XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME, XDG_CACHE_HOME
5. Platform defaults matching existing installs

For containers and agent sandboxes, prefer a single relocated root:

export COSTCO_HOME=/srv/costco
costco-pp-cli doctor

Under COSTCO_HOME=/srv/costco, the four dirs resolve to /srv/costco/config, /srv/costco/data, /srv/costco/state, and /srv/costco/cache.

MCP servers do not receive CLI flags from the host. Put relocation in the host env block:

{
  "mcpServers": {
    "costco": {
      "command": "costco-pp-mcp",
      "env": {
        "COSTCO_HOME": "/srv/costco"
      }
    }
  }
}

Precedence matters in fleets: an ambient per-kind variable such as COSTCO_DATA_DIR overrides an explicit --home for that kind. Use COSTCO_HOME or the per-kind variables for durable fleet relocation; treat --home as the weaker per-invocation lever.

Relocation is one-way. Unsetting COSTCO_HOME does not move files back to platform defaults, and doctor cannot find credentials left under a former root. Move the files manually before unsetting relocation variables.

Existing installs keep working because the platform-default rung matches the legacy layout. On the first auth write, stored secrets leave config.toml and are consolidated into credentials.toml under the data directory. Run costco-pp-cli doctor --fail-on warn to check path and credential-location warnings in automation.

Commands

Receipt data

• costco-pp-cli receipts — List in-warehouse, gas, and carwash receipts for a date range. Supports --since, --until, --years, --type (warehouse/gas/carwash), --csv.
• costco-pp-cli receipt get <barcode> — Show full line-item detail for one receipt by transaction barcode.
• costco-pp-cli orders — List online costco.com orders (requires --warehouse).
• costco-pp-cli counts — Summarize receipt counts and spend by channel.

Analytics (novel)

• costco-pp-cli history-depth — Discover how far back your receipts actually go.
• costco-pp-cli spend — Roll up spend by month, warehouse, or department (--by).
• costco-pp-cli item-history <query> — Track one item's unit price across receipts over time.
• costco-pp-cli savings — Total instant savings and coupons captured.
• costco-pp-cli returns-window — Flag items still inside a return window (--days).

Local archive

• costco-pp-cli sync — Fetch receipts into a local SQLite archive (idempotent).
• costco-pp-cli search <term> — Search synced line items by description or UPC.
• costco-pp-cli sql <query> — Run a read-only SQL SELECT against the archive. Tables: receipts, items.
• costco-pp-cli export — Export receipts to JSONL or CSV (--format, --output).

Utilities

• costco-pp-cli doctor — Check CLI health, token expiry, and path resolution.
• costco-pp-cli auth set-token — Store a Costco idToken for API calls.
• costco-pp-cli raw — Raw GraphQL passthrough (advanced).
• costco-pp-cli which <query> — Find the command for a capability in natural language.
• costco-pp-cli profile — Save and reuse named sets of flags.

Output Formats

# Human-readable table (default in terminal, JSON when piped)
costco-pp-cli receipts --years 1

# JSON for scripting and agents
costco-pp-cli receipts --years 1 --json

# CSV for spreadsheets
costco-pp-cli receipts --years 1 --csv

# Filter to specific fields
costco-pp-cli receipts --years 1 --json --select transactionDate,warehouseName,total

# Dry run — show the request without sending
costco-pp-cli receipts --years 1 --dry-run

# Agent mode — JSON + compact + no prompts in one flag
costco-pp-cli receipts --years 1 --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
• 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.

Health Check

costco-pp-cli doctor

Verifies configuration, credentials, and connectivity to the API.

Configuration

Run costco-pp-cli doctor to see the resolved config, data, state, and cache directories. The platform-default config path is ~/.config/costco-pp-cli/config.toml; --home, COSTCO_HOME, and per-kind env vars can relocate it.

Static request headers can be configured under headers; per-command header overrides take precedence.

Environment variables:

Name	Kind	Required	Description
COSTCO_ID_TOKEN	per_call	Yes	Set to your API credential.

agentcookie (optional)

If you use agentcookie to sync secrets across machines, this CLI auto-adopts agentcookie-managed credentials with no extra setup. When the daemon writes to this CLI's config, costco-pp-cli doctor reports agentcookie: detected and auth-status labels the source as agentcookie. Skip this section if you don't use agentcookie - the CLI works the same as any other.

Troubleshooting

Authentication errors (exit code 4)

• Run costco-pp-cli doctor to check credentials
• Verify the environment variable is set: echo $COSTCO_ID_TOKEN Not found errors (exit code 3)
• Check the resource ID is correct
• Run the list command to see available items

API-specific

• 401 Invalid credentials — Token expired (idToken lives ~15 min). Re-copy localStorage.idToken from DevTools and run 'auth set-token'.
• Empty receipts for a known period — Confirm the date range with --since/--until; the API returns the full account history, so widen the range with history-depth.
• doctor says token expired — Refresh the idToken from a logged-in costco.com tab and re-run auth set-token.

HTTP Transport

This CLI uses Chrome-compatible HTTP transport for browser-facing endpoints. It does not require a resident browser process for normal API calls.

---

Sources & Inspiration

This CLI was built by studying these projects and resources:

• TCRDD — JavaScript
• Costco_Scraping — Python
• costco-importer — JavaScript
• CostcoWrapped — Python

Generated by CLI Printing Press