Every Shopper storefront in one CLI — catalog, cart, delivery schedule, charge calendar, and spend analytics no web UI surfaces.
shopper-pp-cli covers all six Shopper storefronts (Compra Programada, Fresh, Pet, Compra Única, Now, Now Bebidas) with correct store/cluster scoping, full siteapi REST surface, browser-deep-link helpers for subscription mutations, and a local SQLite layer for offline product search, basket diffs, price tracking, and cross-store spend rollup.
Learn more at Shopper.
Created by @educrvz (educrvz).
Authentication
Set SHOPPER_TOKEN to your Shopper JWT (from the siteapi Authorization header in browser DevTools). Run 'shopper-pp-cli doctor' to verify. The token is long-lived for the subscription cycle. Never store raw card numbers or CPF in config; card management always opens the browser.
Quick Start
# Verify CLI is installed and config path is set before auth
shopper-pp-cli doctor --dry-run
# Discover all six storefronts with IDs and payment parameters
shopper-pp-cli stores
# See current basket total, cashback tier, and minimum-order status
shopper-pp-cli cart list-summary --store programada
# See charge date, edit-lock deadline, and delivery date for the next cycle
shopper-pp-cli charge-calendar --store programada
# Month-over-month actual spend rolled up across all storefronts
shopper-pp-cli orders spend
# Full pre-checkout summary before opening browser to confirm payment
shopper-pp-cli checkout preview --store programada
Unique Features
These capabilities aren't available in any other tool for this API.
Subscription intelligence
-
charge-calendar — Every upcoming cycle's charge date, edit-lock deadline, and delivery date in one timeline so you never miss an edit window or get surprised by a charge.
Use when an agent needs to know whether the edit window is still open before modifying a recurring basket.
shopper-pp-cli charge-calendar --store programada --agent
-
basket diff — Compares your current recurring basket against a previous cycle's snapshot to show exactly what was added, dropped, or re-quantified before the template locks.
Use when an agent needs to verify what changed in the basket since the last confirmed delivery cycle.
shopper-pp-cli basket diff --store programada --agent
-
cashback optimize — Computes the cheapest set of items to add (or whether to wait) to cross the next cashback tier, favoring things you'll need anyway.
Use when an agent is finalising a basket and wants to maximise cashback return before the edit window closes.
shopper-pp-cli cashback optimize --tier 2399 --store programada --agent
Local state that compounds
-
price-watch — Tracks the price history of the SKUs you actually buy and alerts when one rises or drops meaningfully versus your own purchase baseline.
Use when an agent needs to know if a subscribed product has changed price significantly since the last order.
shopper-pp-cli price-watch --store programada --agent
-
restock predict — Predicts when you'll run out of each staple from your historical buying cadence and suggests what to add to the upcoming basket.
Use when an agent needs to pre-populate a recurring basket with items likely running low before the next cycle.
shopper-pp-cli restock predict --store programada --agent
-
catalog drift — Flags products you buy that were discontinued, silently swapped, or kept their price while shrinking the pack, surfacing the real R$/kg or R$/L change.
Use when an agent needs to audit whether the recurring basket still contains the same products as originally added.
shopper-pp-cli catalog drift --store programada --agent
Customer journey plumbing
-
checkout preview — Aggregates cart totals, next delivery date, charge date, minimum-order status, and accepted payment types into one pre-checkout view before you open the browser.
Use when an agent needs to confirm basket readiness and charge schedule before directing the user to open the browser for final payment.
shopper-pp-cli checkout preview --store programada --agent
Recipes
Check if the edit window is still open
shopper-pp-cli charge-calendar --store programada --agent --select next_delivery_date,edit_lock_date,charge_date
Returns the key dates for the next cycle; compare edit_lock_date to today to know if the basket can still be changed.
Find items to add for next cashback tier
shopper-pp-cli cashback optimize --store programada --agent
Computes the cheapest catalog additions to cross the next cashback threshold using your live cart and synced product data.
Cross-store spend rollup for last 12 months
shopper-pp-cli orders spend --agent --select store,month,total
Queries all 6 storefronts and returns a month-by-store spend matrix for budgeting analysis.
Detect if a subscribed product changed price
shopper-pp-cli price-watch --store programada --agent --select product_id,name,price_now,price_baseline,change_pct
Scans synced price history for products in your basket and flags meaningful price movements.
Pre-checkout summary with charge date
shopper-pp-cli checkout preview --store programada --agent --select total_amount,delivery_date,charge_date,min_order_met,payment_methods
Aggregates cart/delivery/payment data so an agent can confirm basket readiness before directing the user to open the checkout browser.
Usage
Run shopper-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:
- Per-kind env var:
SHOPPER_CONFIG_DIR, SHOPPER_DATA_DIR, SHOPPER_STATE_DIR, or SHOPPER_CACHE_DIR
--home <dir> for this invocationSHOPPER_HOME for a flat relocated root- XDG env vars:
XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME, XDG_CACHE_HOME
- Platform defaults matching existing installs
For containers and agent sandboxes, prefer a single relocated root:
export SHOPPER_HOME=/srv/shopper
shopper-pp-cli doctor
Under SHOPPER_HOME=/srv/shopper, the four dirs resolve to /srv/shopper/config, /srv/shopper/data, /srv/shopper/state, and /srv/shopper/cache.
MCP servers do not receive CLI flags from the host. Put relocation in the host env block:
{
"mcpServers": {
"shopper": {
"command": "shopper-pp-mcp",
"env": {
"SHOPPER_HOME": "/srv/shopper"
}
}
}
}
Precedence matters in fleets: an ambient per-kind variable such as SHOPPER_DATA_DIR overrides an explicit --home for that kind. Use SHOPPER_HOME or the per-kind variables for durable fleet relocation; treat --home as the weaker per-invocation lever.
Relocation is one-way. Unsetting SHOPPER_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 shopper-pp-cli doctor --fail-on warn to check path and credential-location warnings in automation.
Commands
address
Saved delivery addresses with per-address available-store information
shopper-pp-cli address - List delivery addresses and which stores are available at each address
cart
Cart: view summary, add products, remove products
shopper-pp-cli cart add - Add a product to the cart or increase its quantityshopper-pp-cli cart list-summary - Show current basket: items, quantities, totals, cashback, and minimum-order statusshopper-pp-cli cart remove - Remove a product from the cart or decrease its quantity
catalog
Product catalog: search, departments, banners, suggestions
shopper-pp-cli catalog create-count - Count products matching a search query and optional filtersshopper-pp-cli catalog create-filters - Get available filter options for a search queryshopper-pp-cli catalog create-search - Search the product catalog by query with optional brand/type/metadata filtersshopper-pp-cli catalog get-view - Get details for a specific catalog bannershopper-pp-cli catalog list-banners - List promotional banners for the current storeshopper-pp-cli catalog list-departments - List product departments/categories for the current storeshopper-pp-cli catalog list-news - List new product arrivals for the current storeshopper-pp-cli catalog list-suggest - Get search suggestions for a query prefix
delivery
Delivery schedule: upcoming delivery date, edit-lock window, and reschedule calendar
shopper-pp-cli delivery list-calendar - Get delivery reschedule calendar — allowed date range and disabled daysshopper-pp-cli delivery list-summary - Show scheduled delivery date, current delivery status, and store message
features
Storefront configuration, feature toggles, and timer state
shopper-pp-cli features create-select - Select active store (sets session context; no-op for header-scoped reads)shopper-pp-cli features create-start - Start a named feature timershopper-pp-cli features create-view - Mark a feature toggle as viewedshopper-pp-cli features list-stores - List all available storefronts with store IDs, cluster IDs, payment parameters, and feature flagsshopper-pp-cli features list-tick - Get current timer stateshopper-pp-cli features list-toggle - Get active feature toggles for the current store
orders
Purchase history and spend — reads from GET /orders/orders (web 'Histórico de compras')
shopper-pp-cli orders - List past orders for the active store (newest-first, paginated by size)
session
Session and social-login validation
shopper-pp-cli session - Validate social-login session status
Self-learning loop
This CLI caches per-question discovery so repeat queries skip the walk and structurally similar queries get answered via entity substitution. The loop also self-captures: every invocation is journaled locally, and failed-flag corrections plus fresh teaches surface as candidates on the next recall for confirm/reject judgment. Agents call recall before discovery and fire teach & after answering. See the ## Automatic learning section in SKILL.md for the full protocol.
shopper-pp-cli recall <query> - Look up cached resources for a query before running discoveryshopper-pp-cli teach - Record a query -> resource mapping (silent on success, safe to background with &)shopper-pp-cli learnings list - Inspect taught rowsshopper-pp-cli learnings forget <query> - Undo a teachshopper-pp-cli learnings candidates - List auto-captured candidates awaiting confirm/rejectshopper-pp-cli learnings stats - Local loop metrics: recall hit rate, teach-to-reuse, playbook resolution, candidate countsshopper-pp-cli teach-pattern - Install a query/resource template up frontshopper-pp-cli teach-lookup - Add an entity mapping (e.g. country code, team alias) for pattern substitution
Pass --no-learn or set SHOPPER_NO_LEARN=true to disable the loop for deterministic flows.
The local store's schema version stamp is one-way: once this version of shopper-pp-cli opens the database, older binaries refuse it with a version error — upgrade the binary rather than downgrading.
Output Formats
# Human-readable table (default in terminal, JSON when piped)
shopper-pp-cli address
# JSON for scripting and agents
shopper-pp-cli address --json
# Filter to specific fields
shopper-pp-cli address --json --select id,name,status
# Dry run — show the request without sending
shopper-pp-cli address --dry-run
# Agent mode — JSON + compact + no prompts in one flag
shopper-pp-cli address --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
- Explicit retries - add
--idempotent to create retries when a no-op success is acceptable
- Confirmable -
--yes for explicit confirmation of destructive actions
- Piped input - write commands can accept structured input when their help lists
--stdin
- 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 SHOPPER_NO_AUTO_REFRESH=1 to disable the pre-read freshness hook while preserving the selected data source.
Covered command paths:
shopper-pp-cli addressshopper-pp-cli address getshopper-pp-cli address listshopper-pp-cli address searchshopper-pp-cli cartshopper-pp-cli cart getshopper-pp-cli cart listshopper-pp-cli cart searchshopper-pp-cli catalogshopper-pp-cli catalog getshopper-pp-cli catalog listshopper-pp-cli catalog searchshopper-pp-cli catalog-departmentsshopper-pp-cli catalog-departments getshopper-pp-cli catalog-departments listshopper-pp-cli catalog-departments searchshopper-pp-cli catalog-products-newsshopper-pp-cli catalog-products-news getshopper-pp-cli catalog-products-news listshopper-pp-cli catalog-products-news searchshopper-pp-cli catalog-search-suggestshopper-pp-cli catalog-search-suggest getshopper-pp-cli catalog-search-suggest listshopper-pp-cli catalog-search-suggest searchshopper-pp-cli deliveryshopper-pp-cli delivery getshopper-pp-cli delivery listshopper-pp-cli delivery searchshopper-pp-cli delivery-v2-calendarshopper-pp-cli delivery-v2-calendar getshopper-pp-cli delivery-v2-calendar listshopper-pp-cli delivery-v2-calendar searchshopper-pp-cli featuresshopper-pp-cli features getshopper-pp-cli features listshopper-pp-cli features searchshopper-pp-cli features-timer-tickshopper-pp-cli features-timer-tick getshopper-pp-cli features-timer-tick listshopper-pp-cli features-timer-tick searchshopper-pp-cli features-toggleshopper-pp-cli features-toggle getshopper-pp-cli features-toggle listshopper-pp-cli features-toggle searchshopper-pp-cli ordersshopper-pp-cli orders getshopper-pp-cli orders listshopper-pp-cli orders searchshopper-pp-cli sessionshopper-pp-cli session getshopper-pp-cli session listshopper-pp-cli session search
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
shopper-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Run shopper-pp-cli doctor to see the resolved config, data, state, and cache directories. The platform-default config path is ~/.config/shopper-pp-cli/config.toml; --home, SHOPPER_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 |
|---|
SHOPPER_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, shopper-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
shopper-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $SHOPPER_TOKEN
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- 401 Unauthorized on any command — Run 'shopper-pp-cli auth set-token ' with a fresh JWT from browser DevTools → Network → Authorization header
- cart list-summary returns wrong store data — Pass --store explicitly: programada, fresh, unica, pet, now, or now-bebidas. The default is programada.
- unica/pet orders missing from 'orders spend' — orders spend queries all stores by default; if a store shows no data, your account has no orders there
- delivery calendar shows no available dates — Run --store with a subscription store (programada/fresh/pet). now/now-bebidas use a different ultra-fast delivery flow.
- checkout open or delivery reschedule shows wrong store URL — Pass --store explicitly to get the correct storefront URL (e.g. --store fresh opens fresh.shopper.com.br)