Find local Flipp flyer deals, coupons, and grocery savings by ZIP or postal code.
Search local weekly flyers, coupons, merchants, and item clippings from Flipp's unauthenticated web endpoints. The CLI adds agent-native JSON, local SQLite, basket comparison, expiring-deal views, and unit-price helpers for grocery planning.
Quick Start
# Verify the CLI and local configuration without calling Flipp.
flipp-pp-cli doctor --dry-run
# Resolve the default ZIP or postal code from the current public IP.
flipp-pp-cli location --json
# Search local flyer and ecommerce deals for a staple item.
flipp-pp-cli items milk --zip 85001 --json --select items.name,items.current_price,ecom_items.name,ecom_items.current_price
# Find active local flyers and IDs to inspect.
flipp-pp-cli flyers list --zip 85001 --json --select flyers.id,flyers.merchant,flyers.valid_to
# Compare a simple shopping basket across local merchants.
flipp-pp-cli basket price --items milk,eggs,bread --zip 85001 --agent
Unique Features
These capabilities aren't available in any other tool for this API.
Local savings workflows
-
basket price — Compare a grocery list across nearby merchants and see the cheapest practical basket.
Use this when an agent needs to choose where to shop for a list rather than find one item.
flipp-pp-cli basket price --items milk,eggs,bread --zip 85001 --agent
-
deals scan — Scan curated staple categories and rank local deals by discount, urgency, and merchant.
Use this when the user asks for the best grocery savings nearby without naming exact products.
flipp-pp-cli deals scan --category groceries --zip 85001 --min-discount 25 --agent
Local snapshots
-
expiring — Find local flyer and coupon savings that expire within a chosen window.
Use this when timing matters and the agent needs to prioritize deals before they disappear.
flipp-pp-cli expiring --days 3 --zip 85001 --agent
-
coverage — Show which nearby merchants have active food flyers, searchable items, and coupon coverage.
Use this before shopping-plan work to understand which stores have enough data to compare.
flipp-pp-cli coverage --zip 85001 --agent
-
watchlist add — Persist target prices for recurring staples and compare them against future synced snapshots.
Use this when the user wants recurring savings alerts rather than a one-time search.
flipp-pp-cli watchlist add milk --target-price 3.50 --zip 85001 --agent
Deal quality
-
unit-price — Normalize item prices by package size when Flipp listings include parseable quantities.
Use this when raw prices are misleading because package sizes differ.
flipp-pp-cli unit-price milk --zip 85001 --agent
Recipes
Compare a short grocery basket
flipp-pp-cli basket price --items milk,eggs,bread --zip 85001 --agent --select merchant,total,items.name,items.price
Groups matching deals by merchant so an agent can pick the cheapest local trip.
Find expiring food savings
flipp-pp-cli expiring --days 3 --zip 85001 --agent
Prioritizes local deals whose flyer validity window is closing.
Inspect one flyer clipping list
flipp-pp-cli flyers items 8005907 --sid 1234567890123456 --json --select name,price,cutout_image_url
Returns flyer item text plus image URLs for ambiguous listings.
Scan grocery category deals
flipp-pp-cli deals scan --category groceries --zip 85001 --min-discount 25 --agent
Fans out staple searches and ranks the best local discounts.
Usage
Run flipp-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 such as data.db |
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:
FLIPP_CONFIG_DIR, FLIPP_DATA_DIR, FLIPP_STATE_DIR, or FLIPP_CACHE_DIR
--home <dir> for this invocationFLIPP_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 FLIPP_HOME=/srv/flipp
flipp-pp-cli doctor
Under FLIPP_HOME=/srv/flipp, the four dirs resolve to /srv/flipp/config, /srv/flipp/data, /srv/flipp/state, and /srv/flipp/cache.
MCP servers do not receive CLI flags from the host. Put relocation in the host env block:
{
"mcpServers": {
"flipp": {
"command": "flipp-pp-mcp",
"env": {
"FLIPP_HOME": "/srv/flipp"
}
}
}
}
Precedence matters in fleets: an ambient per-kind variable such as FLIPP_DATA_DIR overrides an explicit --home for that kind. Use FLIPP_HOME or the per-kind variables for durable fleet relocation; treat --home as the weaker per-invocation lever.
Relocation is one-way. Unsetting FLIPP_HOME does not move files back to platform defaults, and doctor cannot find files 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. Run flipp-pp-cli doctor --fail-on warn to check path warnings in automation.
Commands
flyers
Browse active local flyers and flyer items
flipp-pp-cli flyers data - Fetch the combined local flyer and coupon data payloadflipp-pp-cli flyers items - List item clippings from a specific flyerflipp-pp-cli flyers list - List active flyers for a ZIP or postal code
items
Search Flipp flyer and ecommerce deal items
flipp-pp-cli items <q> - Search local flyer and ecommerce deals by keyword
location
Resolve a default Flipp location
flipp-pp-cli location - Detect the current public IP location as a Flipp postal code
merchants
List merchants Flipp tracks
flipp-pp-cli merchants - List Flipp merchants available for a ZIP or postal code
Output Formats
# Human-readable table (default in terminal, JSON when piped)
flipp-pp-cli flyers list
# JSON for scripting and agents
flipp-pp-cli flyers list --json
# Filter to specific fields
flipp-pp-cli flyers list --json --select id,name,status
# Dry run — show the request without sending
flipp-pp-cli flyers list --dry-run
# Agent mode — JSON + compact + no prompts in one flag
flipp-pp-cli flyers list --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
- Read-only by default - this CLI does not create, update, delete, publish, send, or mutate remote resources
- 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, 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 FLIPP_NO_AUTO_REFRESH=1 to disable the pre-read freshness hook while preserving the selected data source.
Covered command paths:
flipp-pp-cli flyersflipp-pp-cli flyers getflipp-pp-cli flyers listflipp-pp-cli flyers searchflipp-pp-cli merchantsflipp-pp-cli merchants getflipp-pp-cli merchants listflipp-pp-cli merchants 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
flipp-pp-cli doctor
Verifies configuration and connectivity to the API.
Configuration
Run flipp-pp-cli doctor to see the resolved config, data, state, and cache directories. The platform-default config path is ~/.config/flipp-pp-cli/config.toml; --home, FLIPP_HOME, and per-kind env vars can relocate it.
Static request headers can be configured under headers; per-command header overrides take precedence.
Troubleshooting
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- Search results include irrelevant keyword matches. — Use a phrase query such as
flipp-pp-cli items "whole milk" --zip 85001 --json, then filter with --select or downstream jq.
- A flyer item has an empty or ambiguous price. — Run
flipp-pp-cli flyers items <flyer-id> --json --select name,price,cutout_image_url and inspect the clipping image.
- A ZIP code returns sparse food results. — Run
flipp-pp-cli coverage --zip 85001 to see which merchants and flyer categories are available locally.
HTTP Transport
This CLI uses Chrome-compatible HTTP transport for browser-facing endpoints. It does not require a resident browser process for normal API calls.
Sources & Inspiration
This CLI was built by studying these projects and resources:
Generated by CLI Printing Press