---
name: pp-anylist
description: "Every AnyList feature in your terminal — plus offline search, store routing, and cron-safe automations no mobile... Trigger phrases: `add to my grocery list`, `what recipes can I make with`, `build my shopping list from meal plan`, `check off items on anylist`, `use anylist`, `run anylist`."
author: "user"
license: "Apache-2.0"
argument-hint: "<command> [args] | install cli|mcp"
allowed-tools: "Read Bash"
metadata:
  openclaw:
    requires:
      bins:
        - anylist-pp-cli
---

# AnyList — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `anylist-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 anylist --cli-only
   ```
2. Verify: `anylist-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.5 or newer). This installs into `$GOPATH/bin` (default `$HOME/go/bin`), so add that directory to `$PATH` instead:

```bash
go install github.com/mvanhorn/printing-press-library/library/food-and-dining/anylist/cmd/anylist-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

Use anylist-pp-cli when you need to automate grocery and meal planning workflows from the shell or in agent pipelines. It excels at cron-based shopping list generation from meal plans, offline recipe search by ingredient or metadata, and store-optimized shopping output. It is the right choice when you need JSON output from AnyList operations for downstream processing with jq, or when you want to build Home Assistant / n8n automations beyond what the basic hacs-anylist integration supports.

## Unique Capabilities

These capabilities aren't available in any other tool for this API.

### Local state that compounds

- **`recipes search --ingredient`** — Find every recipe that uses a given ingredient instantly — no scrolling, no guessing.

  _Use this when an agent needs to suggest meals from available pantry items without making multiple API calls._

  ```bash
  anylist-pp-cli recipes search --query chicken --ingredient --agent
  ```
- **`recipes filter`** — Filter your entire recipe library by prep time, rating, serving count, and collection simultaneously.

  _Use this when an agent needs to find recipes that fit a time or quality constraint for meal planning._

  ```bash
  anylist-pp-cli recipes filter --max-prep 30 --min-rating 4 --collection Weeknight --agent
  ```
- **`lists by-store`** — Split a shopping list into per-store groups sorted by store aisle order — ready for multi-store shopping trips.

  _Use this when an agent needs to generate a structured shopping route across multiple stores._

  ```bash
  anylist-pp-cli lists by-store --name Groceries --agent
  ```
- **`recipes missing`** — Show which recipe ingredients are not already on a shopping list.

  _Use this as a read-only audit before adding ingredients — it reports what is missing so the AI can make the right reuse/create/ask decisions._

  ```bash
  anylist-pp-cli recipes missing --recipe "Pasta Bake" --list Groceries --agent
  ```
- **`meal summary`** — Render a Mon–Sun meal plan grid with Breakfast/Lunch/Dinner labels — pasteable into messages or scripts.

  _Use this when an agent needs to present the week's meal plan in a human-readable format for sharing or review._

  ```bash
  anylist-pp-cli meal summary --week | pbcopy
  ```
- **`items search`** — Find any item across all your shopping lists at once — shows which list it's on and whether it's checked.

  _Use this when an agent needs to locate an item without knowing which list it was added to._

  ```bash
  anylist-pp-cli items search --query "almond milk" --agent
  ```
- **`items lookup`** — Resolve a UPC/EAN barcode through AnyList's product catalog and return the canonical name, structured package size, UPC, prices, and thumbnail URL.

  _Use this before adding a packaged product. Passing the returned barcode to `items add` lets AnyList receive the identifier first and enrich the item when its catalog has a match._

  ```bash
  anylist-pp-cli items lookup --barcode 049000028904 --json
  anylist-pp-cli items add --list Groceries --item "Coca-Cola" --barcode 049000028904 --package-size "12 count, 12 fl oz" --apply
  ```

- **`items update`** — Rename an item or update its quantity, notes, verified barcode, package size, category match, store assignments, or price. Preview is the default and `--apply` is required for every live write; fresh list metadata resolves names, browser-confirmed protobuf handlers perform the write, the live item is verified by ID, and the cache is synced only after verification. Use `--clear-category`, `--store`, `--remove-store`, `--price`, or `--clear-price` for metadata CRUD. Aisle/category-assignment subrecords beyond the captured path and recipe photos remain unsupported. Stdin accepts `category`, `clear_category`, `store`, `remove_store`, `price`, `price_store`, `price_details`, `clear_price`, and `apply` in addition to the scalar fields.

  ```bash
anylist-pp-cli items update --list Groceries --item "Milk" --package-size "12 oz carton" --apply --json
printf '%s\n' '{"list":"Groceries","item":"Milk","package_size":"12 oz carton","apply":true}' | anylist-pp-cli items update --stdin --json
anylist-pp-cli items update --list Groceries --item "Milk" --name "Whole Milk" --apply --json
printf '%s\n' '{"list":"Groceries","item":"Whole Milk","name":"Milk","apply":true}' | anylist-pp-cli items update --stdin --json
anylist-pp-cli items update --list Groceries --item "Milk" --category Produce --apply --json
anylist-pp-cli items update --list Groceries --item "Milk" --store "Paris Walmart" --apply --json
anylist-pp-cli items update --list Groceries --item "Milk" --remove-store "Paris Walmart" --apply --json
anylist-pp-cli items update --list Groceries --item "Milk" --price 3.49 --apply --json
anylist-pp-cli items update --list Groceries --item "Milk" --clear-price --apply --json
  ```

`--clear-price` without `--price-store` clears every store-specific price returned for the live item and verifies that no positive price remains. Use `--price-store <id>` to clear only one store's price while preserving prices for other stores.

- **`items photo attach`** — Upload and attach a photo to a shopping-list item. Local dry-run validates the file without network access; `--apply` is required for the live upload and typed attachment. The command fresh-reads the item, verifies the returned 32-hex photo ID, and persists it in the local cache before reporting success (`cache_updated:true`).

  ```bash
  anylist-pp-cli items photo attach --list Groceries --item "Milk" --file milk.jpg --dry-run --json
  anylist-pp-cli items photo attach --list Groceries --item "Milk" --file milk.jpg --apply --json
  ```

### Agent-native plumbing

- **`meal add-to-list`** — Preview meal-plan ingredients only; live bulk writes are disabled. Use the raw ingredient packet and explicit item operations.

  _Use this in a cron job or agent workflow to pre-populate the shopping list before a weekly grocery trip._

  ```bash
  anylist-pp-cli meal add-to-list --week --list Groceries --dry-run
  ```
- **`recipes ingredients`** — Return raw recipe ingredient rows plus a fresh read of target-list candidates and stored-price facts. This is the read-only fact packet for the AI meal-planning workflow; it preserves source wording and does not choose or write an item.

  ```bash
  anylist-pp-cli recipes ingredients --name "Pasta Bake" --list Groceries --scale 4 --agent
  ```
- **`recipes add-to-list`** — Deprecated bulk path; it fails closed. Use `recipes ingredients`, then explicit `items add`/`items update --item-id` operations selected by the AI.
- **`lists reset`** — Clear all checked items from a list in one command — idempotent and safe for cron to run after every shopping trip.

  _Use this in a post-trip automation to reset the list for the next week without manually unchecking each item._

  ```bash
  anylist-pp-cli lists reset --name Groceries --keep-unchecked
  ```
- **`sync status`** — Report how fresh your local cache is per entity type, with exit code 1 if any data is stale.

  _Use this as a cron preflight check to ensure agent operations run against up-to-date local data._

  ```bash
  anylist-pp-cli sync status --stale-after 24h || anylist-pp-cli sync
  ```

Use the global `--db <path>` option for an isolated per-run SQLite cache. AnyList returns one complete user-data envelope, so `sync --resources <hint>` is an automation hint rather than a server-side filter; `--full` explicitly requests the normal complete refresh.

## AnyList Meal Planning Workflow

Use this skill as the coordinator and the press as its factual execution layer. The workflow is intentionally approval-gated: recipe selection and ingredient identity are AI decisions; AnyList writes are explicit stable-ID operations.

### Preferences

On the first run, conduct the complete interview and ask which answers should become defaults: purpose and cadence; number of meals, dates, servings and leftovers; budget and nutrition goals; dietary restrictions, allergies and disliked foods; preferred, limited and excluded proteins; cuisine, difficulty, time and equipment; freezer and pantry/fridge inventory; target AnyList list, store, ZIP code and aisle/category preferences; review/debug mode; and whether calendar events should be scheduled after approval. Save only non-secret preferences.

On later runs, print the saved profile and ask whether to use it unchanged, customize this run only, or edit and save the defaults. One-run overrides do not silently change the saved profile. The companion skill stores the profile at `~/.config/anylist-meal-planning/preferences.json` with mode `0600`.

### Curate, approve, then resolve

Read recipes, collections, servings, preparation time, nutrition and available item metadata. Prefer economical recipes that share staples, avoid recent repeats, and provide variety. Return the proposed recipes and a raw combined ingredient list for approval; do not write recipes, calendar events or shopping-list items before approval. After approval, ask what is already in the pantry/fridge.

The `recipes ingredients` packet preserves each source ingredient separately, including wording, quantity, note, recipe and form context, and returns fresh candidate facts such as stable IDs, checked state, quantity, notes, UPC, package size, photos, stores, categories and stored prices. The AI then chooses `reuse`, `recycle`, `create`, `skip` (pantry), or `ask` (ambiguous). It must not infer block, sliced or shredded cheese when the recipe does not specify the form.

### Review table before writes

When review/debug mode is enabled, show the following table before any shopping-list mutation:

| Ingredient needed | Form/package | Proposed AnyList item | Source | Metadata comparison | UPC action | Stored price | Proposed action | Confidence/notes |
|---|---|---|---|---|---|---:|---|---|
| ½ cup cheddar | unresolved | — | — | block/sliced/shredded differ | ask | — | ask | recipe does not specify form |
| 1 gallon milk | gallon | Milk - Gallon | historical | package and barcode agree | reuse | $3.48 | recycle | previous item has best metadata |
| 8 oz shredded cheese | shredded, 8 oz | Shredded Sharp Cheddar Cheese | current | strongest metadata among candidates | keep | $2.97 | reuse | selected stable ID |
| jarred garlic | jar | — | new | no suitable candidate | attempt lookup | — | create | UPC pending |

The table distinguishes current exact items, historical items, metadata mismatches, new items and unresolved ambiguity. With review/debug off, the same AI resolution is still required; the table is simply omitted.

### Pricing and UPC enrichment

For now, report only prices already stored on AnyList, with a known-price subtotal and missing-price count. Always disclose: **Prices come from stored AnyList item data. They may be outdated, incomplete, or missing; this is not a live Walmart price or availability quote.** ZIP-aware live store pricing and aisle lookup require a future Walmart press.

When creating a new item, the AI may propose a UPC only when product form and package are specific. Use `items lookup --barcode` or barcode-first creation, then read the item back and compare the returned name, brand, package size, photo, price, store and category. Never attach a guessed UPC to a generic ingredient; ask when multiple products are plausible. If AnyList does not enrich programmatic writes as the app does, leave uncertain metadata unset and report that limitation.

### Partial-Quantity Accounting Rule

Every partial amount — regardless of whether it comes from a bag, jar, box, bottle, or loose unit — is compared against each scaled recipe requirement and resolved as **skip** (pantry), **buy-shortfall/remainder** (recycle an existing item or create a new one with the right stable ID), or **ask** (ambiguous). This rule applies per-run and must hold on repeated runs: if a previous run recycled a gallon of milk, the next run compares against the remaining gallon quantity, not the original full quantity.

### Apply and verify

Remain read-only until recipe approval, pantry adjustments, ingredient decisions and the review gate are complete. Preview by default; pass `--apply` for live mutations on commands that support writes. **Bulk paths fail closed:** `meal add-to-list` and `recipes add-to-list`/`recipes batch-add` do not support `--apply` — they preview or fail closed. Live writes use explicit stable-ID operations (`items add` / `items update --item-id`) with `--apply`, followed by fresh read-after-write verification. Reuse or recycle only the selected stable ID, preserve quantity and package size, protect checked items, perform fresh reads, and report partial failures without silently retrying as new items. Calendar create/update/delete is supported behind the same explicit `--apply` and fresh read-back gate; a disposable live round-trip has been verified.

## Command Reference

**categories** — View item categories, and create, rename, delete, or reorder custom categories

- `anylist-pp-cli categories` — List all item categories (read-only)
- `anylist-pp-cli categories create --list <list> --name <name>` — Preview or create a custom category with explicit `--apply`; the list and category group are resolved by a fresh live read (the list must have exactly one group unless `--category-group` selects one), the new category gets a non-conflicting stable ID and a valid sort index, and the create is verified by stable ID before success
- `anylist-pp-cli categories rename --list <list> --category <id-or-name> --new-name <name>` — Preview or rename one custom category by stable ID or exact name with explicit `--apply`; ambiguous or missing names fail closed, the stable identifier/group/list/sort index are preserved, and the new name is verified by stable ID before success
- `anylist-pp-cli categories delete --list <list> --category <id-or-name>` — Preview or delete one custom category by stable ID or exact name with explicit `--apply`; ambiguous or missing names fail closed, system categories cannot be deleted, and the deletion is verified by confirming the stable ID is absent from a fresh read before success
- `anylist-pp-cli categories reorder --list <list> --order <id-or-name,id-or-name,…>` — Preview or reorder a category group's categories with explicit `--apply`; the list must have exactly one group unless `--category-group` selects one, `--order` must name every category in the group exactly once (duplicates, unknown entries, and silently appended or dropped categories fail closed), and the exact stable-ID order is verified from a fresh read before success
- Custom category writes use the verified multipart `/data/shopping-lists/update-v2` wire contract (the non-persistent v1 route and the old non-persistent `remove-category` handler are never used). Category-group create, rename, and delete (group CRUD) remain unsupported.

**collections** — List recipe collections and preview collection writes. Create/add/remove/delete previews are available, but live writes currently fail closed because a disposable AnyList create acknowledged HTTP success without persisting on fresh read-back. Do not use `--apply` until a future live probe proves the exact collection contract.

- `anylist-pp-cli collections add` — Preview an add; live mutation is fail-closed pending persistence proof
- `anylist-pp-cli collections create` — Preview a create; live mutation is fail-closed pending persistence proof
- `anylist-pp-cli collections delete` — Preview a delete; live mutation is fail-closed pending persistence proof
- `anylist-pp-cli collections list` — List all recipe collections
- `anylist-pp-cli collections remove` — Preview a removal; live mutation is fail-closed pending persistence proof

**favorites** — Manage favorite items with explicit apply gates and fresh read-after-write verification. Photo and price mutation remain separate capabilities.

- `anylist-pp-cli favorites` — List favorite items across all lists
- `anylist-pp-cli favorites add --list LIST --name NAME` — Preview or add an item to a favorite list; pass `--apply` to write
- `anylist-pp-cli favorites remove --list LIST --item ITEM` — Preview or remove an item from a favorite list; pass `--apply` to write

**folders** — View and safely organize shopping-list folders. Preview is the default and `--apply` is required for live mutations; enabled mutations require fresh read-back before cache sync.

- `anylist-pp-cli folders create` — Create a folder with `--name`
- `anylist-pp-cli folders delete` — Delete an empty folder with `--name`; non-empty folders are refused
- `anylist-pp-cli folders list` — List all list folders
- `anylist-pp-cli folders update` — Rename with `--new-name`, move with `--parent`, or reorder children with `--order`; pass `--apply` for live mutation and fresh verification. An explicit disposable ordering probe is available with `ANYLIST_FOLDER_ORDERING_PROBE=1`.

Create/delete, rename, parent movement, and child ordering use handlers verified against live fresh read-back; the APK-equivalent `set-ordered-folder-items` payload is recorded in `.printing-press-patches/review-folder-ordering-live-probe.json`.

**items** — Manage items within a shopping list

- `anylist-pp-cli items add` — Add an explicitly selected item to a shopping list. The AI must choose the stable item ID or explicitly request creation. Preview is the default and `--apply` is required for every live write; fresh live and cache read-back verification must succeed before the command reports success. Use `--store` for a store assignment and `--price`, `--price-store`, or `--price-details` for price metadata. Store removal remains an `items update --remove-store` operation.
- `anylist-pp-cli items check` — Mark one or more items as checked (bought)
- `anylist-pp-cli items list` — List items in a shopping list; JSON output includes cached package size, photo IDs, prices, store IDs, category match ID, and category assignments when available
- `anylist-pp-cli items lookup` — Look up product details by UPC/EAN barcode
- `anylist-pp-cli items recent` — Show recently added items across all lists
- `anylist-pp-cli items recent remove` — Preview or remove an entry from the Recent Items store (the sharded autocomplete backing store). The selector must