Pp Flipp

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/food-and-dining/flipp/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

Flipp — Printing Press CLI

Prerequisites: Install the CLI

This skill drives the flipp-pp-cli binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to $HOME/.local/bin on macOS/Linux and %LOCALAPPDATA%\Programs\PrintingPress\bin on Windows:

   npx -y @mvanhorn/printing-press-library install flipp --cli-only

2. Verify: flipp-pp-cli --version
3. Ensure the reported install directory is on $PATH for the agent/runtime that will invoke this skill.

If the npx install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.4 or newer). This installs into $GOPATH/bin (default $HOME/go/bin), so add that directory to $PATH instead:

go install github.com/mvanhorn/printing-press-library/library/food-and-dining/flipp/cmd/flipp-pp-cli@latest

If --version reports "command not found" after install, the runtime cannot see the binary directory on $PATH. Do not proceed with skill commands until verification succeeds.

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.

When to Use This CLI

Use this CLI when a user asks for local grocery flyer deals, coupons, merchant coverage, price comparison, or ZIP-code savings from Flipp. It is strongest for read-only shopping research and agent workflows that need structured output.

Anti-triggers

Do not use this CLI for:

• Do not use this CLI to place grocery orders or reserve pickup slots.
• Do not use this CLI for loyalty-account-only coupons that require a retailer login.
• Do not treat Flipp's reverse-engineered endpoints as a guaranteed official API.

Unique Capabilities

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

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.

Command Reference

flyers — Browse active local flyers and flyer items

• flipp-pp-cli flyers data — Fetch the combined local flyer and coupon data payload
• flipp-pp-cli flyers items — List item clippings from a specific flyer
• flipp-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

Freshness Contract

This printed CLI owns bounded freshness only for registered store-backed read command paths. In --data-source auto mode, those paths check sync_state and may run a bounded refresh before reading local data. --data-source local never refreshes. --data-source live reads the API and does not mutate the local store. Set FLIPP_NO_AUTO_REFRESH=1 to skip the freshness hook without changing source selection.

Covered paths:

• flipp-pp-cli flyers
• flipp-pp-cli flyers get
• flipp-pp-cli flyers list
• flipp-pp-cli flyers search
• flipp-pp-cli merchants
• flipp-pp-cli merchants get
• flipp-pp-cli merchants list
• flipp-pp-cli merchants search

When JSON output uses the generated provenance envelope, freshness metadata appears at meta.freshness. Treat it as current-cache freshness for the covered command path, not a guarantee of complete historical backfill or API-specific enrichment.

Finding the right command

When you know what you want to do but not which command does it, ask the CLI directly:

flipp-pp-cli which "<capability in your own words>"

which resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code 0 means at least one match; exit code 2 means no confident match — fall back to --help or use a narrower query.

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.

Auth Setup

No authentication required.

Run flipp-pp-cli doctor to verify setup.

Agent Mode

Add --agent to any command. Expands to: --json --compact --no-input --no-color --yes.

• Pipeable — JSON on stdout, errors on stderr

• Filterable — --select keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs:

  flipp-pp-cli flyers list --agent --select id,name,status

• Previewable — --dry-run shows the request without sending

• Offline-friendly — sync/search commands can use the local SQLite store when available

• Market scoped — provide --postal-code for sync and archive, and --zip for search. Local flyer, merchant, and cached item results use that market only; older rows without a saved location require a fresh sync.

• Flyer clippings — flyers items <flyer_id> reads live only because that endpoint supplies no postal code for safe offline caching.

• Non-interactive — never prompts, every input is a flag

• Read-only — do not use this CLI for create, update, delete, publish, comment, upvote, invite, order, send, or other mutating requests