pp-instacart

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Instacart - Printing Press CLI

Prerequisites: Install the CLI

前提条件：安装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:

Install via the Printing Press installer:

bash

npx -y @mvanhorn/printing-press install instacart --cli-only

Verify:
```
instacart-pp-cli --version
```
Ensure
```
$GOPATH/bin
```
(or
```
$HOME/go/bin
```
) is on
```
$PATH
```
.

If the

npx

install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.23+):

bash

go install github.com/mvanhorn/printing-press-library/library/commerce/instacart/cmd/instacart-pp-cli@latest

--version

reports "command not found" after install, the install step did not put the binary on

$PATH

. Do not proceed with skill commands until verification succeeds.

此技能驱动

instacart-pp-cli

二进制文件。在调用此技能的任何命令之前，您必须确认CLI已安装。如果未安装，请先进行安装：

通过Printing Press安装程序安装：

bash

npx -y @mvanhorn/printing-press install instacart --cli-only

验证安装：
```
instacart-pp-cli --version
```
确保
```
$GOPATH/bin
```
（或
```
$HOME/go/bin
```
）已添加到
```
$PATH
```
环境变量中。

如果

npx

安装失败（无Node环境、离线等情况），可改用Go直接安装（要求Go 1.23+版本）：

bash

go install github.com/mvanhorn/printing-press-library/library/commerce/instacart/cmd/instacart-pp-cli@latest

如果安装后执行

--version

提示“command not found”，说明安装步骤未将二进制文件添加到

$PATH

中。请在验证成功前不要执行技能命令。

When to Use This CLI

何时使用此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.

当用户有以下需求时，可使用此工具：

通过自然语言将商品添加到Instacart购物车（例如“add lemon sorbet to QFC”）
添加之前购买过的商品（例如“add my usual milk to Safeway”）
查看、搜索或对比跨零售商的活跃购物车
列出或搜索个人Instacart订单历史
从脚本、定时任务或Agent循环中执行Instacart流程

如果用户想要完成结账操作，则不建议使用此工具。此CLI仅负责将商品添加到购物车；结账仍需在Instacart应用或网页端完成。

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.

add

命令会首先检查本地购买历史记录，当目标零售商存在匹配度高的商品时，会完全跳过三次实时GraphQL调用流程。将“add the lemon sorbet pops I usually get”这类操作的耗时从约1.2秒缩短至约200毫秒，并且能准确匹配您实际购买过的SKU，而非当前实时搜索排名最高的商品。

匹配度判定规则：

在该零售商的本地已购商品库中通过FTS5匹配成功
购买时间在过去365天内
上次购买时商品处于在售状态

当任一条件不满足时，会自动切换为实时搜索模式。可添加

--no-history

参数强制使用实时搜索。

所有成功的「添加」操作（无论是基于历史记录还是实时搜索）都会写入

purchased_items

，无需完全同步即可优化后续匹配的准确性。

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
```
— Chrome MCP flow
```
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

for why.

输入“backfill my instacart orders”（或类似表述，详见参数解析）即可启动由Chrome-MCP驱动的流程，该流程会读取用户已登录的Instacart标签页，将订单历史提取为JSONL格式并导入本地数据库。回填完成后，

add

命令将基于真实购买历史而非实时搜索猜测来匹配商品。

主要路径：Chrome MCP。备选方案：手动将三个JS文件粘贴到DevTools中。

完整流程说明请查看下方「回填流程」章节。详细参考文档：

```
docs/backfill-walkthrough.md
```
— Chrome MCP流程
```
docs/backfill-devtools-fallback.md
```
— 手动DevTools流程

history list

history search

history stats

命令可查看已导入的历史记录。

Instacart未提供清晰的订单历史GraphQL操作接口，因此旧版

history sync

命令无法正常工作。详情请查看

docs/solutions/best-practices/instacart-orders-no-clean-graphql-op.md

。

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"

通过Instacart自身的三次GraphQL调用链（ShopCollectionScoped -> Autosuggestions -> Items）将自由文本解析为商品，并执行

UpdateCartItemsMutation

操作。无需浏览器自动化。

当Instacart返回

notFoundBasketProduct

错误（自动补全偶尔会推荐当前购物车所属店铺无法添加的商品）时，

add

命令会自动重试最多3个排名靠前的候选商品，直至成功或失败。使用

--json

输出时，成功重试会显示

retry_count > 0

，并包含

attempts

数组列出被拒绝的商品ID。当基于历史记录的匹配遇到相同错误时，

add

命令会切换为实时搜索模式，并标记

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.

carts list

命令可一次性显示所有零售商的活跃购物车。对于需要先确认商品所属店铺再添加的Agent来说非常实用。

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

认证相关：

```
instacart auth login
```
- 从Chrome中提取会话Cookie
```
instacart auth status
```
- 显示当前会话状态
```
instacart auth logout
```
- 清除已保存的Cookie
```
instacart auth paste
```
- 手动粘贴Cookie JSON（适用于新版macOS Chrome的备选方案）
```
instacart auth import-file <path>
```
- 从浏览器导出的JSON文件加载Cookie

购物车操作：

```
instacart add <retailer> <query...>
```
- 通过自然语言添加商品

instacart add <retailer> <query...> --no-history

- 跳过基于历史记录的解析

```
instacart add --item-id <id> <retailer>
```
- 通过精确的Instacart商品ID添加
```
instacart cart show <retailer>
```
- 显示指定零售商的当前购物车内容

instacart cart remove <item-id> <retailer>

- 从购物车中移除指定商品

```
instacart carts list
```
- 列出所有零售商的活跃购物车

发现功能：

instacart search <query> --store <retailer>

- 在指定零售商处搜索商品

```
instacart retailers list
```
- 列出您所在地址支持的零售商
```
instacart retailers show <slug>
```
- 将指定零售商信息缓存到本地

购买历史：

```
instacart history import <path>
```
- 将JSONL格式的订单转储文件加载到本地数据库（工作路径）
```
instacart history import - --json
```
- 从标准输入读取数据，输出JSON格式用于Agent流水线

instacart history import <path> --dry-run

- 预览导入数量但不写入数据库

```
instacart history list
```
- 按购买次数和最近度显示最常购买的商品

instacart history list --store <retailer> --limit 20

- 筛选并分页显示

```
instacart history search <query>
```
- 全文搜索购买历史

instacart history search <query> --store <retailer>

- 按零售商筛选全文搜索

```
instacart history stats
```
- 显示订单统计数据及各零售商状态

维护相关：

```
instacart doctor
```
- 健康检查：配置、店铺、操作、历史记录、会话、实时连接
```
instacart capture
```
- 更新GraphQL操作哈希缓存
```
instacart capture --remote
```
- 从社区注册表合并最新哈希值
```
instacart ops list
```
- 显示操作哈希缓存状态

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.

bash

instacart auth login                # 从Chrome提取Cookie
instacart doctor                    # 验证认证及实时连接
instacart capture                   # 初始化内置操作哈希

然后回填历史记录（可选但推荐；解锁基于历史记录的优先「添加」功能）：

告知Agent："backfill my instacart orders"

技能会引导完成后续步骤。请查看下方「回填流程」章节。

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.

bash

instacart add safeway "oat milk"    # 如果您之前购买过，会基于本地历史记录解析

输出中会显示

via history

。如果显示

via live

，说明全文搜索匹配未通过置信度检查；可执行

instacart history search "oat milk" --store safeway

查看历史记录中的实际商品。

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 which path would have fired.

bash

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

--dry-run --json

在调试时非常实用，输出会包含

resolved_via

字段，显示实际会触发的解析路径。

Daily top-up from recent history

从近期历史记录一键补货

bash

instacart history list --store safeway --limit 20 --json | jq -r '.[].name' \
  | while read item; do instacart add safeway "$item" --yes --json; done

bash

instacart history list --store safeway --limit 20 --json | jq -r '.[].name' \
  | while read item; do instacart add safeway "$item" --yes --json; done

Auth Setup

认证设置

Requires a logged-in Instacart session in Chrome. The CLI extracts cookies via kooky (no credential handling on our side). If Chrome is locked or you are on a system kooky cannot read:

bash

instacart auth paste         # paste the full cookie JSON manually
instacart auth import-file <path>

Session lives at

~/.config/instacart/session.json

(0600).

要求Chrome中已登录Instacart会话。CLI通过kooky提取Cookie（我们不处理任何凭证）。如果Chrome已锁定或kooky无法读取系统Cookie：

bash

instacart auth paste         # 手动粘贴完整的Cookie JSON
instacart auth import-file <path>

会话存储在

~/.config/instacart/session.json

（权限0600）。

Agent Mode

Agent模式

The CLI is agent-native by default. Pass

--json

on any command for machine-readable output.

--dry-run

previews

add

without firing the mutation and surfaces which resolver (

history

live

, or

item-id

) would have fired.

add

JSON envelope fields worth knowing:

```
resolved_via
```
: one of
```
history
```
,
```
live
```
,
```
history->live
```
(history pick was rejected, live retry succeeded), or
```
item-id
```
.
```
retry_count
```
: how many candidates were rejected before the winner.
```
0
```
when the first pick landed.
```
attempts
```
: present only when
```
retry_count > 0
```
, array of
```
{item_id, name, error_type}
```
for each rejected candidate.
On exhaustion (exit 5): JSON envelope with
```
error
```
,
```
retailer
```
,
```
query
```
,
```
attempts
```
, and a
```
hint
```
naming the concrete next step (
```
search
```
then
```
add --item-id
```
, or retry with
```
--no-history
```
).

CLI默认支持Agent调用。在任何命令后添加

--json

参数即可获取机器可读的输出。

--dry-run

参数可预览「添加」操作但不执行变更，并显示会触发的解析器（

history

、

live

或

item-id

）。

add

命令JSON输出中的关键字段：

```
resolved_via
```
: 取值为
```
history
```
、
```
live
```
、
```
history->live
```
（历史记录匹配被拒绝，实时搜索重试成功）或
```
item-id
```
。
```
retry_count
```
: 成功匹配前被拒绝的候选商品数量。首次匹配成功时为
```
0
```
。
```
attempts
```
: 仅当
```
retry_count > 0
```
时存在，包含每个被拒绝候选商品的
```
{item_id, name, error_type}
```
数组。
当所有候选商品都失败（退出码5）：JSON输出包含
```
error
```
、
```
retailer
```
、
```
query
```
、
```
attempts
```
字段，以及
```
hint
```
字段给出具体下一步操作建议（先
```
search
```
再
```
add --item-id
```
，或添加
```
--no-history
```
重试）。

Filtering output

输出筛选

--select

accepts dotted paths to descend into nested responses; arrays traverse element-wise:

bash

instacart-pp-cli <command> --agent --select id,name
instacart-pp-cli <command> --agent --select items.id,items.owner.name

Use this to narrow huge payloads to the fields you actually need — critical for deeply nested API responses.

--select

参数接受点分隔的路径，用于提取嵌套响应中的指定字段；数组会遍历所有元素：

bash

instacart-pp-cli <command> --agent --select id,name
instacart-pp-cli <command> --agent --select items.id,items.owner.name

使用此参数可将庞大的响应数据缩小到实际需要的字段——这对深度嵌套的API响应至关重要。

Response envelope

响应信封

Data-layer commands wrap output in

{"meta": {...}, "results": <data>}

. Parse

.results

for data and

.meta.source

to know whether it's

live

or local. The

N results (live)

summary is printed to stderr only when stdout is a TTY; piped/agent consumers see pure JSON on stdout.

数据层命令会将输出包裹在

{"meta": {...}, "results": <data>}

结构中。解析

.results

字段获取数据，

.meta.source

字段表示数据来源是

live

（实时）还是本地。当标准输出为TTY时，

N results (live)

摘要会打印到标准错误输出；管道或Agent调用时，标准输出仅显示纯JSON。

Exit Codes

退出码

Code	Meaning
0	Success
2	Usage error
3	Auth missing or rejected
4	Resource not found
5	API error / conflict
7	Rate limited or transient network

代码	含义
0	成功
2	使用错误
3	认证缺失或被拒绝
4	资源未找到
5	API错误/冲突
7	速率限制或临时网络问题

Argument Parsing

参数解析

Given a free-form natural-language request:

Empty,
```
help
```
, or
```
--help
```
-> run
```
instacart --help
```
Starts with
```
install
```
-> CLI install; ends with
```
mcp
```
-> MCP install
Matches a backfill intent -> run the Backfill Flow below. Trigger phrases include: "backfill my orders", "backfill my history", "sync my instacart history", "sync my instacart orders", "download my order history", "save my instacart history locally", "pull in my past orders", "import my recent orders".
Anything else -> map to the best subcommand and run with
```
--json
```
when invoked from an agent

对于自由格式的自然语言请求：

空请求、
```
help
```
或
```
--help
```
-> 执行
```
instacart --help
```
以
```
install
```
开头 -> 安装CLI；以
```
mcp
```
结尾 -> 安装MCP
匹配回填意图 -> 执行下方的回填流程。触发短语包括："backfill my orders"、"backfill my history"、"sync my instacart history"、"sync my instacart orders"、"download my order history"、"save my instacart history locally"、"pull in my past orders"、"import my recent orders"。
其他请求 -> 映射到最合适的子命令，当由Agent调用时自动添加
```
--json
```
参数

Backfill Flow

回填流程

Drive this when the user hits a backfill intent. Read

docs/backfill-walkthrough.md

via WebFetch for the full procedure; summary below.

Setup check:

Confirm

instacart-pp-cli

is on PATH. If not, install:

go install github.com/mvanhorn/printing-press-library/library/commerce/instacart/cmd/instacart-pp-cli@latest

Probe
```
mcp__claude-in-chrome__tabs_context_mcp
```
. If the tool is unavailable, route to the DevTools fallback: fetch
```
docs/backfill-devtools-fallback.md
```
and walk the user through it. Stop.
Run
```
instacart-pp-cli history stats --agent
```
. If orders > 0, this is a top-up run; the resume state will skip already-dumped orders automatically.

Chrome MCP loop:

WebFetch the three JS files (cache each in the current session):

https://raw.githubusercontent.com/mvanhorn/printing-press-library/main/library/commerce/instacart/docs/dumper.js

https://raw.githubusercontent.com/mvanhorn/printing-press-library/main/library/commerce/instacart/docs/extract-one.js

https://raw.githubusercontent.com/mvanhorn/printing-press-library/main/library/commerce/instacart/docs/export-jsonl.js

Open or reuse a tab at
```
https://www.instacart.com/store/account/orders
```
. If the dumper returns
```
profile_picker: true
```
, ask the user to pick a profile in the tab, then re-run.

Inject

dumper.js

via

mcp__claude-in-chrome__javascript_tool

. Read back

total_ids

and

pending_extract

For each order ID in the pending set, navigate to
```
/store/orders/<id>
```
then inject
```
extract-one.js
```
. Report progress to the user every 10 orders.
When pending reaches 0, inject
```
export-jsonl.js
```
. It downloads
```
instacart-orders.jsonl
```
to the user's default Downloads folder.

Run

instacart-pp-cli history import ~/Downloads/instacart-orders.jsonl --agent

in a Bash tool. Show the summary JSON to the user.

Verify:

instacart-pp-cli history stats --agent

. Offer a follow-up sanity check:

instacart-pp-cli add <retailer> "<something they've bought>" --dry-run --json

and flag

resolved_via: "history"

when it appears.

Error surfaces worth translating for the user:

Extractor
```
cache_key_missing
```
on every order -> Instacart rotated their web bundle. Report the observed cache keys and point at the rotation-recovery section of the walkthrough doc.
Dumper reports fewer IDs than the user expected -> probably on a multi-profile account; ensure the selected profile is the one with purchase history.
```
history import
```
shows 0 orders imported -> the JSONL is empty (only skip records). Re-run the extractor loop with fresh tabs.

当用户触发回填意图时执行此流程。通过WebFetch查看

docs/backfill-walkthrough.md

获取完整步骤；以下是摘要：

设置检查：

确认

instacart-pp-cli

已在PATH中。如果未安装，执行：

go install github.com/mvanhorn/printing-press-library/library/commerce/instacart/cmd/instacart-pp-cli@latest

。

检查
```
mcp__claude-in-chrome__tabs_context_mcp
```
工具是否可用。如果不可用，切换到DevTools备选方案：获取
```
docs/backfill-devtools-fallback.md
```
并引导用户完成手动操作。停止流程。
执行
```
instacart-pp-cli history stats --agent
```
。如果订单数>0，说明是增量回填；恢复状态会自动跳过已导出的订单。

Chrome MCP循环：

WebFetch获取三个JS文件（在当前会话中缓存）：

https://raw.githubusercontent.com/mvanhorn/printing-press-library/main/library/commerce/instacart/docs/dumper.js

https://raw.githubusercontent.com/mvanhorn/printing-press-library/main/library/commerce/instacart/docs/extract-one.js

https://raw.githubusercontent.com/mvanhorn/printing-press-library/main/library/commerce/instacart/docs/export-jsonl.js

打开或复用
```
https://www.instacart.com/store/account/orders
```
标签页。如果dumper返回
```
profile_picker: true
```
，请用户在标签页中选择一个账户，然后重新执行。

通过

mcp__claude-in-chrome__javascript_tool

注入

dumper.js

。读取返回的

total_ids

和

pending_extract

。

对于每个待提取的订单ID，导航到
```
/store/orders/<id>
```
并注入
```
extract-one.js
```
。每处理10个订单向用户报告进度。
当待提取订单数为0时，注入
```
export-jsonl.js
```
。该文件会将
```
instacart-orders.jsonl
```
下载到用户默认的下载文件夹。

在Bash工具中执行

instacart-pp-cli history import ~/Downloads/instacart-orders.jsonl --agent

。将摘要JSON显示给用户。

验证：执行

instacart-pp-cli history stats --agent

。提供后续 sanity check：

instacart-pp-cli add <retailer> "<用户常购商品>" --dry-run --json

，当出现

resolved_via: "history"

时标记成功。

需要向用户解释的错误场景：

每个订单都返回提取器
```
cache_key_missing
```
错误 -> Instacart更新了网页资源包。向用户报告检测到的缓存键，并引导查看流程文档中的资源包更新恢复章节。
Dumper返回的ID数量少于用户预期 -> 可能是多账户；确保选择的账户包含购买历史。
```
history import
```
显示0个订单导入 -> JSONL文件为空（仅包含跳过记录）。使用新标签页重新执行提取循环。

Direct Use

直接使用

Check installed:
```
which instacart-pp-cli
```
Check auth:
```
instacart doctor
```
Capture GraphQL hashes:
```
instacart capture
```
(Optional but recommended) Backfill history — run the Backfill Flow above. Unlocks history-first
```
add
```
resolution.
Run your command with
```
--json
```
if invoked from an agent

检查是否安装：
```
which instacart-pp-cli
```
检查认证状态：
```
instacart doctor
```
获取GraphQL哈希：
```
instacart capture
```
（可选但推荐）回填历史记录 — 执行上述回填流程。解锁基于历史记录的优先「添加」解析功能。
如果由Agent调用，执行命令时添加
```
--json
```
参数