PAK'nSAVE NZ

Goal

Query live PAK'nSAVE NZ store and grocery product data, optionally retrieve the authenticated user's own account history, and perform explicit shopping-list or cart changes through a small deterministic CLI.

Use this when

• A user asks for PAK'nSAVE NZ product prices or specials
• A user wants to search PAK'nSAVE products by keyword
• A user needs store IDs, store lookup, or category browsing
• A user has PAK'nSAVE product IDs and wants store-specific price/details
• A workflow needs machine-readable PAK'nSAVE product data
• A user explicitly wants their own previous PAK'nSAVE orders or purchases
• A user explicitly wants to retrieve their own saved PAK'nSAVE shopping lists
• A user explicitly asks to create, rename, delete, or change products in one of their own shopping lists
• A user explicitly asks to inspect their cart or add, update, or remove one of its products

Do not use this for

• New World, Four Square, Woolworths, or non-PAK'nSAVE retailers
• Historical pricing or price-change claims unless another dataset provides history
• Checkout, ordering, payment, timeslot, fulfilment, or account/profile changes
• List or cart mutation that the user has not explicitly requested
• Reading another person's account or using credentials not supplied by the account holder

Preferred workflow

1. Run scripts/cli.py with the narrowest subcommand that answers the task
2. Use stores first when the requested location is not the default store
3. Use search for keyword price/product lookup and specials for promotional products
4. Use product when exact product IDs are known
5. Use authenticated commands only after the user has supplied their own credentials through environment variables
6. Run list or cart mutation commands only when the user has explicitly requested that exact change
7. Preserve the --yes guard on list deletion and list/cart product removal; never infer confirmation from unrelated work
8. Use --json for agent chaining, comparisons, or structured reports
9. Treat authenticated JSON as personal data and mention that the integration is unofficial

Authentication and privacy

Public catalogue commands need no account. Personal commands require the user's own Club+ credentials:

export PAKNSAVE_USERNAME='member@example.nz'
export PAKNSAVE_PASSWORD='...'
paknsave auth login

• The CLI registers and displays account, order, list, and cart commands only when both PAKNSAVE_USERNAME (or PAKNSAVE_EMAIL) and PAKNSAVE_PASSWORD are present in its environment.
• Without that credential pair, --help and command parsing expose only the guest catalogue commands.
• The password is read only from the environment and is never written to disk.
• Rotating access and refresh tokens are cached at ~/.cache/paknsave-cli/auth.json with file mode 0600.
• Override the cache location with PAKNSAVE_AUTH_FILE.
• If Club+ requires MFA, set PAKNSAVE_MFA_CODE to the six-digit code and run auth mfa.
• auth status never prints token values. auth logout removes only the local token cache; it does not mutate the PAK'nSAVE account.
• PAKNSAVE_ACCESS_TOKEN and PAKNSAVE_REFRESH_TOKEN may be used as runtime overrides.
• Orders, list names, item history, addresses, and raw JSON are personal data. Do not paste them into shared logs, issues, or pull requests.

CLI

Run with:

python3 skills/paknsave-nz/scripts/cli.py <command> [flags]

Default store is PAK'nSAVE Papakura: a7d09522-bee2-41e4-8fe0-0b82b7f342f5. Override with --store-id <id> or PAKNSAVE_STORE_ID.

Commands

The first six guest commands are always available. The remaining account commands appear only when the Club+ username/email and password environment variables are set.

• stores [--query text] [--limit N] [--json] — list or filter PAK'nSAVE stores
• categories [--store-id id] [--depth N] [--json] — browse a store category tree
• search <query> [--store-id id] [--limit N] [--page N] [--promo] [--json] — product search with prices
• specials [query] [--store-id id] [--limit N] [--page N] [--json] — promotional products
• product <product-id...> [--store-id id] [--json] — decorate exact product IDs with details
• token [--refresh] [--json] — fetch/cache a short-lived guest token without emitting its value
• auth login [--json] — log in with environment-provided Club+ credentials
• auth mfa [--json] — finish an MFA login using PAKNSAVE_MFA_CODE
• auth refresh [--json] — rotate the cached PAK'nSAVE access token
• auth status [--json] — report token availability without revealing tokens
• auth logout [--json] — remove only the local authenticated-token cache
• store-select [--store-id id] [--json] — select the store used for authenticated list and cart writes
• orders [--page N] [--limit N] [--source ALL|ONLINE|IN_STORE] [--json] — retrieve previous orders
• order <order-id> [--source ONLINE|IN_STORE] — retrieve one previous order
• previous-purchases [--limit N] [--include-cart] [--json] — retrieve previously purchased products
• lists [--json] — retrieve saved shopping lists
• list <list-id> — retrieve one saved shopping list
• list-create <name> [--json] — create an empty shopping list
• list-rename <list-id> <name> [--json] — rename a shopping list
• list-delete <list-id> --yes [--json] — permanently delete a shopping list
• list-add <list-id> <product-id> [--quantity N] [--sale-type UNITS|WEIGHT] [--json] — add a product
• list-update <list-id> <product-id> --quantity N [--sale-type UNITS|WEIGHT] [--json] — change quantity
• list-remove <list-id> <product-id> --yes [--sale-type UNITS|WEIGHT] [--json] — remove a product
• cart [--json] — retrieve the current cart
• cart-add <product-id> [--quantity N] [--sale-type UNITS|WEIGHT] [--json] — increment a cart product quantity
• cart-update <product-id> --quantity N [--sale-type UNITS|WEIGHT] [--json] — set a cart product quantity
• cart-remove <product-id> --yes [--sale-type UNITS|WEIGHT] [--json] — remove a cart product

Examples:

python3 skills/paknsave-nz/scripts/cli.py stores --query auckland --limit 5
python3 skills/paknsave-nz/scripts/cli.py search milk --limit 10
python3 skills/paknsave-nz/scripts/cli.py specials cheese --limit 10 --json
python3 skills/paknsave-nz/scripts/cli.py product 5201479 --json
paknsave auth status
paknsave store-select
paknsave orders --limit 20 --json
paknsave lists --json
paknsave list-create "Weekly shop"
paknsave list-add <list-id> 5201479 --quantity 2
paknsave cart
paknsave cart-add 5201479 --quantity 2

Resources

• CLI entrypoint: scripts/cli.py
• Live smoke test: scripts/smoke_test.py
• API and stability notes: references/api-notes.md

Notes

• Public commands use the guest-token flow and cache tokens under ~/.cache/paknsave-cli/guest-token.json
• Personal commands mirror the Club+ login, secure-code exchange, and rotating PAK'nSAVE refresh flow used by the website
• If a fresh authenticated session has no store, the CLI selects PAKNSAVE_STORE_ID (or the Papakura default) once and retries the request; store-select can change it explicitly
• List writes use the same endpoints as the website and are intentionally exposed only as explicit subcommands
• list-delete and list-remove require --yes; they cannot be invoked accidentally through a zero quantity
• Cart writes use target quantities internally: cart-add reads and increments, while cart-update sets the target directly
• cart-remove requires --yes; use grams for WEIGHT quantities and units for UNITS
• Email verification must be completed in the normal PAK'nSAVE login page before CLI login
• Endpoint shapes can change; retry with a fresh token before assuming data is unavailable
• --json output is intended for exact matching and private agent workflows