pp-instacart

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/commerce/instacart/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/". -->

# Instacart - Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `instacart-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:
   ```bash
   npx -y @mvanhorn/printing-press-library install instacart --cli-only
   ```
2. Verify: `instacart-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.3 or newer):

```bash
go install github.com/mvanhorn/printing-press-library/library/commerce/instacart/cmd/instacart-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.

## When to Use This CLI

Reach for this when a user wants:

- Add a product to an Instacart cart by natural language ("add lemon sorbet to QFC")
- Add something they have bought before ("add my usual milk to Safeway")
- Show, search, or compare their active carts across retailers
- List or search their own Instacart order history
- Run an Instacart flow from a script, cron job, or agent loop

Do not reach for this if the user wants to actually check out. This CLI adds items to your cart; you still complete checkout in the Instacart app or web UI.

## Unique Capabilities

### History-first `add`

`add` checks your local purchase history FIRST and, when a confident match exists at the target retailer, skips the three-call live GraphQL chain entirely. Drops the cost of "add the lemon sorbet pops I usually get" from ~1.2s to ~200ms AND makes it resolve to the right SKU (the one you actually buy) instead of whatever live search ranks highest today.

Confidence rules:
- FTS5 match in your local purchased_items at that retailer
- Purchased within the last 365 days
- Was in stock on the last purchase

Falls through to today's live-search behavior when any condition fails. Pass `--no-history` to force live search.

Every successful `add` (history-resolved or live-resolved) writes back to `purchased_items` so the signal gets warmer without a full re-sync.

### One-command history backfill

Typing "backfill my instacart orders" (or similar, see Argument Parsing) kicks off a Chrome-MCP-driven flow that walks the user's logged-in Instacart tab, extracts their order history into JSONL, and imports it into the local DB. After backfill, `add` resolves from real purchase history instead of live-search guesses.

Primary path: Chrome MCP. Fallback: paste three JS files into DevTools by hand.

Full walkthrough below under "Backfill Flow". Reference docs with more detail:

- [`docs/backfill-walkthrough.md`](https://github.com/mvanhorn/printing-press-library/blob/main/library/commerce/instacart/docs/backfill-walkthrough.md) — Chrome MCP flow
- [`docs/backfill-devtools-fallback.md`](https://github.com/mvanhorn/printing-press-library/blob/main/library/commerce/instacart/docs/backfill-devtools-fallback.md) — manual DevTools flow

`history list` / `history search` / `history stats` inspect whatever has been loaded.

Instacart does not expose a clean order-history GraphQL op, so the legacy `history sync` command cannot work. See [`docs/solutions/best-practices/instacart-orders-no-clean-graphql-op.md`](https://github.com/mvanhorn/printing-press-library/blob/main/docs/solutions/best-practices/instacart-orders-no-clean-graphql-op.md) for why.

### Natural-language `add`

Resolves a product from free-text via Instacart's own three-call GraphQL chain (ShopCollectionScoped -> Autosuggestions -> Items) and fires `UpdateCartItemsMutation`. No browser automation.

When Instacart rejects a candidate with `notFoundBasketProduct` (autosuggest occasionally surfaces a product that is not addable at your active cart's shop), `add` automatically retries up to 3 ranked candidates before giving up. In `--json` output a successful retry sets `retry_count > 0` and includes an `attempts` array listing the rejected item ids. When history-first resolution hits the same error, `add` falls through to live search and reports `resolved_via: "history->live"`.

### Multi-retailer `carts`

`carts list` shows every active cart across retailers at once. Useful for agents that need to know where items live before adding to the right one.

## Command Reference

Authentication:

- `instacart auth login` - extract session cookies from Chrome
- `instacart auth status` - show current session state
- `instacart auth logout` - clear saved cookies
- `instacart auth paste` - paste cookie JSON manually (fallback for newer macOS Chrome)
- `instacart auth import-file <path>` - load cookies from a browser-use export JSON

Cart operations:

- `instacart add <retailer> <query...>` - add a product by natural language
- `instacart add <retailer> <query...> --no-history` - skip the history-first resolver
- `instacart add --item-id <id> <retailer>` - add by exact Instacart item id
- `instacart cart show <retailer>` - show current cart contents at a retailer
- `instacart cart remove <item-id> <retailer>` - remove an item from a cart
- `instacart carts list` - list every active cart across retailers

Discovery:

- `instacart search <query> --store <retailer>` - search products at a retailer
- `instacart retailers list` - list retailers available at your address
- `instacart retailers show <slug>` - cache one retailer locally

Purchase history:

- `instacart history import <path>` - load a JSONL order dump into the local DB (the working path)
- `instacart history import - --json` - read from stdin, JSON output for agent pipelines
- `instacart history import <path> --dry-run` - preview counts without writing
- `instacart history list` - top purchased items by count + recency
- `instacart history list --store <retailer> --limit 20` - filter + paginate
- `instacart history search <query>` - FTS search your purchase history
- `instacart history search <query> --store <retailer>` - scoped FTS search
- `instacart history stats` - counts + per-retailer state

Maintenance:

- `instacart doctor` - health check: config, store, ops, history, session, live ping
- `instacart capture` - refresh the GraphQL operation hash cache
- `instacart capture --remote` - merge fresh hashes from the community registry
- `instacart ops list` - show the operation-hash cache state

## Recipes

### First-time setup

```bash
instacart auth login                # extract cookies from Chrome
instacart doctor                    # verify auth + live ping
instacart capture                   # seed built-in op hashes
```

Then backfill history (optional but recommended; unlocks history-first `add`):

> Tell the agent: "backfill my instacart orders"

The skill drives the rest. See the "Backfill Flow" section below.

### Add something you buy all the time

```bash
instacart add safeway "oat milk"    # resolves via local history if you have bought it before
```

Look for `via history` in the output. If you see `via live`, the FTS match did not pass the confidence check; check `instacart history search "oat milk" --store safeway` to see what is actually in your history.

### Force a fresh live search

```bash
instacart add safeway "oat milk" --no-history --dry-run --json
```

`--dry-run --json` is useful when debugging - the output includes `resolved_via` so you can see w