Shopper CLI

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 quantity
• shopper-pp-cli cart summary - GET /cart/summary
• shopper-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/count
• shopper-pp-cli catalog filters - POST /catalog/search/filters
• shopper-pp-cli catalog search - POST /catalog/search
• shopper-pp-cli catalog banner-view - GET /catalog/banners/{banner_id}/view
• shopper-pp-cli catalog banners - GET /catalog/banners
• shopper-pp-cli catalog departments - GET /catalog/departments
• shopper-pp-cli catalog news - GET /catalog/products/news
• shopper-pp-cli catalog suggest - GET /catalog/search/suggest

delivery

Operations on summary

• shopper-pp-cli delivery calendar - GET /delivery/v2/calendar
• shopper-pp-cli delivery summary - GET /delivery/summary

features

Operations on toggle

• shopper-pp-cli features select - POST /features/stores/select
• shopper-pp-cli features start - POST /features/timer/start
• shopper-pp-cli features view - POST /features/toggle/view
• shopper-pp-cli features stores - GET /features/stores
• shopper-pp-cli features tick - GET /features/timer/tick
• shopper-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.