The first CLI for Shopper — every catalog, cart, and delivery surface plus a local price/basket history the web app throws away each cycle.
Shopper's recurring basket, fixed charge-7-days-before clock, and drifting prices produce a time series the official app discards every cycle. This CLI keeps it in a local SQLite store, unlocking charge-calendar, basket diff, price-watch, restock prediction, catalog-drift detection, and cashback optimization — none of which any Shopper interface offers.
Learn more at Shopper.
Created by @educrvz (educrvz).
Authentication
Shopper uses a Bearer JWT. Sign in at shopper.com.br in your browser, copy the token from the Authorization header of any siteapi.shopper.com.br request (DevTools > Network), and set SHOPPER_TOKEN. The CLI also sends app-os-x-version and your store context automatically.
Quick Start
# Health check; verifies token + store context without a live call.
shopper doctor --dry-run
# Search the catalog — the most common first action.
shopper catalog search arroz --agent
# See your current recurring basket total and item count.
shopper cart summary --agent
# See upcoming charge dates and edit deadlines.
shopper charge-calendar --weeks 8 --agent
Unique Features
These capabilities aren't available in any other tool for this API.
Time & Money Clock
-
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.
Reach for this before any basket edit to answer 'can I still change the order / when does money leave the account'.
shopper charge-calendar --weeks 8 --locking-soon --agent
Basket Intelligence
-
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.
Reach for this to audit what changed before confirming a cycle, or to explain why this charge differs from the last.
shopper basket diff --from last-cycle --to current --agent --select added,removed,price_changed
-
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.
Reach for this to proactively fill the next basket so the household doesn't run out of cafe/arroz/fralda mid-cycle.
shopper restock predict --horizon 14d --suggest-adds --agent
Price & Catalog Drift
-
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.
Reach for this before confirming a cycle to catch staples that quietly got pricier, or find real drops worth stocking up on.
shopper price-watch --threshold 8% --since 60d --only-basket --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.
Reach for this when the user asks 'why is my bill the same but I have less', or to auto-find replacements for staples that vanished.
shopper catalog drift --metric per-unit --kind shrinkflation,discontinued --since 90d --agent
Cashback Optimization
-
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.
Reach for this near the edit deadline to decide whether topping up the basket earns net-positive cashback without buying junk.
shopper cashback optimize --tier 2399 --reward 100 --prefer-restock --agent
Recipes
Find a staple and check your price baseline
shopper catalog search 'cafe pilao' --agent --select results.name,results.price && shopper price-watch --only-basket --threshold 5%
Search the catalog, then see whether your tracked staples drifted in price.
Pre-deadline cycle review
shopper charge-calendar --locking-soon --agent && shopper basket diff --from last-cycle --to current --agent
Check which cycle locks soon and audit what changed before it does.
Hit the cashback tier efficiently
shopper cashback optimize --tier 2399 --reward 100 --prefer-restock --agent
Decide the cheapest useful top-up to earn cashback.
Usage
Run shopper-pp-cli --help for the full command reference and flag list.
Commands
address
Operations on address
shopper-pp-cli address - GET /address/
cart
Operations on summary
shopper-pp-cli cart add - Add a product to the cart or increase its quantityshopper-pp-cli cart summary - GET /cart/summaryshopper-pp-cli cart remove - Remove a product from the cart or decrease its quantity
catalog
Operations on departments
shopper-pp-cli catalog count - POST /catalog/search/countshopper-pp-cli catalog filters - POST /catalog/search/filtersshopper-pp-cli catalog search - POST /catalog/searchshopper-pp-cli catalog banner-view - GET /catalog/banners/{banner_id}/viewshopper-pp-cli catalog banners - GET /catalog/bannersshopper-pp-cli catalog departments - GET /catalog/departmentsshopper-pp-cli catalog news - GET /catalog/products/newsshopper-pp-cli catalog suggest - GET /catalog/search/suggest
delivery
Operations on summary
shopper-pp-cli delivery calendar - GET /delivery/v2/calendarshopper-pp-cli delivery summary - GET /delivery/summary
features
Operations on toggle
shopper-pp-cli features select - POST /features/stores/selectshopper-pp-cli features start - POST /features/timer/startshopper-pp-cli features view - POST /features/toggle/viewshopper-pp-cli features stores - GET /features/storesshopper-pp-cli features tick - GET /features/timer/tickshopper-pp-cli features toggle - GET /features/toggle
session
Session and social-login validation
shopper-pp-cli session - GET /auth/validation/social
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.
Health Check
shopper-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Config file: ~/.config/shopper-pp-cli/config.toml
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 AUTH008 No Token — Set SHOPPER_TOKEN to a fresh Bearer JWT from a logged-in browser session (DevTools > Network > any siteapi request).
- Empty catalog/cart results — Select a store first: shopper features select ; the store context (x-store-id) is required for catalog and cart.