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.
It is designed for people and AI agents to manage recurring shopping, prepare one-time purchases, and inspect order history without manually navigating every screen. Payment selection and final order confirmation stay in the authenticated Shopper browser, so the CLI never asks for or stores raw card details.
Note
This is an independent, community-built project and is not an official Shopper product. It uses the same account permissions as the authenticated user and does not bypass Shopper's checkout or payment controls.
| Workflow | What the CLI adds |
|---|---|
| Recurring shopping | Edit baskets, see charge and edit-lock dates, and compare cycles |
| One-time purchases | Check cart and payment readiness, then continue securely in Shopper's checkout |
| All storefronts | Work with Compra Programada, Fresh, Pet, Compra Única, Now, and Now Bebidas |
| Personal analytics | Keep local price history, detect basket drift, and roll up spend across stores |
| Agent workflows | Structured JSON, dry runs, MCP support, and explicit confirmation boundaries |
Learn more about the service at Shopper or install this community CLI from Printing Press.
Created by @educrvz (educrvz).
The recommended path installs both the shopper-pp-cli binary and the pp-shopper agent skill (Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, and other agents supported by the upstream skills CLI) in one shot:
npx -y @mvanhorn/printing-press-library install shopperFor CLI only (no skill):
npx -y @mvanhorn/printing-press-library install shopper --cli-onlyFor skill only — installs the skill into the same agents as the default command above, but skips the CLI binary (use this to update or reinstall just the skill):
npx -y @mvanhorn/printing-press-library install shopper --skill-onlyTo constrain the skill install to one or more specific agents (repeatable — agent names match the skills CLI):
npx -y @mvanhorn/printing-press-library install shopper --agent claude-code
npx -y @mvanhorn/printing-press-library install shopper --agent claude-code --agent codexIf npx isn't available (no Node, offline), install the CLI directly via Go (requires Go 1.26.5 or newer):
go install github.com/mvanhorn/printing-press-library/library/commerce/shopper/cmd/shopper-pp-cli@latestThis installs the CLI only — no skill.
Download a pre-built binary for your platform from the latest release. On macOS, clear the Gatekeeper quarantine: xattr -d com.apple.quarantine <binary>. On Unix, mark it executable: chmod +x <binary>.
Install the CLI binary first. The installer writes binaries to a per-user managed bin directory by default: $HOME/.local/bin on macOS/Linux and %LOCALAPPDATA%\Programs\PrintingPress\bin on Windows.
npx -y @mvanhorn/printing-press-library install shopper --cli-onlyThen install the focused Hermes skill.
From the Hermes CLI:
hermes skills install mvanhorn/printing-press-library/cli-skills/pp-shopper --forceInside a Hermes chat session:
/skills install mvanhorn/printing-press-library/cli-skills/pp-shopper --forceRestart the Hermes session or gateway if the newly installed skill is not visible immediately.
Install both the CLI binary and the focused OpenClaw skill. The installer defaults binaries to a per-user bin directory ($HOME/.local/bin on macOS/Linux, %LOCALAPPDATA%\Programs\PrintingPress\bin on Windows):
npx -y @mvanhorn/printing-press-library install shopper --agent openclawRestart the OpenClaw session or gateway if the newly installed skill is not visible immediately.
This CLI ships an MCPB bundle — Claude Desktop's standard format for one-click MCP extension installs (no JSON config required).
To install:
- Download the
.mcpbfor your platform from the latest release. - Double-click the
.mcpbfile. Claude Desktop opens and walks you through the install. - Fill in
SHOPPER_TOKENwhen Claude Desktop prompts you.
Requires Claude Desktop 1.0.0 or later. Pre-built bundles ship for macOS Apple Silicon (darwin-arm64) and Windows (amd64, arm64); for other platforms, use the manual config below.
Manual JSON config (advanced)
If you can't use the MCPB bundle (older Claude Desktop, unsupported platform), install the MCP binary and configure it manually.
go install github.com/mvanhorn/printing-press-library/library/commerce/shopper/cmd/shopper-pp-mcp@latestAdd to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"shopper": {
"command": "shopper-pp-mcp",
"env": {
"SHOPPER_TOKEN": "<your-key>"
}
}
}
}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.
# 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
These capabilities aren't available in any other tool for this API.
-
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
-
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
-
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
-
payment methods— Reports live card, boleto, and PIX availability plus store-specific minimum lead times.Use immediately before checkout to select a payment path the current storefront actually supports.
shopper-pp-cli payment methods --store unica --agent
-
checkout prepare— Validates a selected payment method and basket readiness before handing final order confirmation to Shopper's browser.Use for one-time purchases where payment must be explicit instead of silently relying on a recurring saved card.
shopper-pp-cli checkout prepare --store unica --payment card --agent
If your authenticated Shopper session is in Brave on macOS, continue with:
shopper-pp-cli checkout prepare --store unica --payment card --open --browser brave
shopper-pp-cli charge-calendar --store programada --agent --select next_delivery_date,edit_lock_date,charge_dateReturns the key dates for the next cycle; compare edit_lock_date to today to know if the basket can still be changed.
shopper-pp-cli cashback optimize --store programada --agentComputes the cheapest catalog additions to cross the next cashback threshold using your live cart and synced product data.
shopper-pp-cli orders spend --months 6 --agent --select store,month,totalQueries all 6 storefronts and returns a month-by-store spend matrix for budgeting analysis.
shopper-pp-cli price-watch --store programada --agent --select product_id,name,price_now,price_baseline,change_pctScans synced price history for products in your basket and flags meaningful price movements.
shopper-pp-cli checkout preview --store programada --agent --select total_amount,delivery_date,charge_date,min_order_met,payment_methodsAggregates cart/delivery/payment data so an agent can confirm basket readiness before directing the user to open the checkout browser.
Run shopper-pp-cli --help for the full command reference and flag list.
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, orSHOPPER_CACHE_DIR --home <dir>for this invocationSHOPPER_HOMEfor 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 doctorUnder 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.
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: 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
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 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
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
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 and social-login validation
shopper-pp-cli session- Validate social-login session status
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.
# 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 --agentThis CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--jsonoutput to stdout, errors to stderr - Filterable -
--select id,namereturns only fields you need - Previewable -
--dry-runshows the request without sending - Explicit retries - add
--idempotentto create retries when a no-op success is acceptable - Confirmable -
--yesfor 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-friendlyis set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
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.
shopper-pp-cli doctorVerifies configuration, credentials, and connectivity to the API.
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. |
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.
Authentication errors (exit code 4)
- Run
shopper-pp-cli doctorto check credentials - Verify the environment variable is set:
echo $SHOPPER_TOKENNot found errors (exit code 3) - Check the resource ID is correct
- Run the
listcommand to see available items
- 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)
Developed by Edu Cruz with AI-assisted engineering from Claude and OpenAI Codex.
This unofficial community project is provided as-is, without warranties or guarantees. Use it at your own risk. You are responsible for reviewing commands and confirming any purchase, payment, account, or data changes before they occur.