Back to Details

pp-shopify

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Shopify — Printing Press CLI

Shopify — Printing Press CLI

Prerequisites: Install the CLI

前提条件：安装CLI

This skill drives the 
shopify-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:
    bash
    npx -y @mvanhorn/printing-press install shopify --cli-only
  2. Verify: 
    shopify-pp-cli --version
  3. 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/shopify/cmd/shopify-pp-cli@latest
If 
--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.
本技能基于
shopify-pp-cli
二进制文件运行。调用本技能的任何命令前，必须先确认CLI已安装。若未安装，请按以下步骤进行安装：
  1. 通过Printing Press安装器安装：
    bash
    npx -y @mvanhorn/printing-press install shopify --cli-only
  2. 验证安装：
    shopify-pp-cli --version
  3. 确保
    $GOPATH/bin
    （或
    $HOME/go/bin
    ）已添加到
    $PATH
    环境变量中。
若
npx
安装失败（如无Node环境、离线等），可回退到直接通过Go安装（要求Go 1.23+版本）：
bash
go install github.com/mvanhorn/printing-press-library/library/commerce/shopify/cmd/shopify-pp-cli@latest
若安装后执行
--version
提示“command not found”，说明安装程序未将二进制文件添加到
$PATH
中。请在验证成功前不要执行本技能的命令。

When Not to Use This CLI

本CLI的禁用场景

Do not use resource commands for requests that require creating, updating, deleting, publishing, commenting, upvoting, inviting, ordering, sending messages, booking, purchasing, or changing remote state. The exception is 
bulk-operations run-query
, which intentionally starts a Shopify bulk export job when the user explicitly asks for it.
请勿使用资源命令执行以下操作：创建、更新、删除、发布、评论、点赞、邀请、下单、发送消息、预订、购买或修改远程状态。唯一例外是
bulk-operations run-query
，当用户明确要求时，该命令会启动Shopify批量导出任务。

Command Reference

命令参考

customers — Shopify customers with lifetime order count, lifetime spend, and contact fields.
  • shopify-pp-cli customers get
    — Get one Shopify customer by GraphQL ID.
  • shopify-pp-cli customers list
    — List customers from the Shopify Admin GraphQL API.
fulfillment-orders — Shopify fulfillment orders for lag, routing, and fulfillment-state analysis.
  • shopify-pp-cli fulfillment-orders get
    — Get one Shopify fulfillment order by GraphQL ID.
  • shopify-pp-cli fulfillment-orders list
    — List fulfillment orders from the Shopify Admin GraphQL API.
inventory-items — Shopify inventory items with tracked status and available quantities by location.
  • shopify-pp-cli inventory-items get
    — Get one Shopify inventory item by GraphQL ID.
  • shopify-pp-cli inventory-items list
    — List inventory items from the Shopify Admin GraphQL API.
orders — Shopify orders with money totals, financial state, and fulfillment state.
  • shopify-pp-cli orders get
    — Get one Shopify order by GraphQL ID.
  • shopify-pp-cli orders list
    — List orders from the Shopify Admin GraphQL API.
products — Shopify products with product status, catalog metadata, and a compact variant inventory projection.
  • shopify-pp-cli products get
    — Get one Shopify product by GraphQL ID.
  • shopify-pp-cli products list
    — List products from the Shopify Admin GraphQL API.
Hand-written commands
  • shopify-pp-cli bulk-operations current
    — Show the current or most recent Shopify bulk operation.
  • shopify-pp-cli bulk-operations run-query --query-file <path>
    — Start a Shopify bulk GraphQL export job from a query file.
customers — 包含终身订单数、终身消费金额及联系字段的Shopify客户信息。
  • shopify-pp-cli customers get
    — 通过GraphQL ID获取单个Shopify客户信息。
  • shopify-pp-cli customers list
    — 从Shopify Admin GraphQL API列出客户信息。
fulfillment-orders — 用于延迟分析、路由分析及履约状态分析的Shopify履约订单。
  • shopify-pp-cli fulfillment-orders get
    — 通过GraphQL ID获取单个Shopify履约订单信息。
  • shopify-pp-cli fulfillment-orders list
    — 从Shopify Admin GraphQL API列出履约订单信息。
inventory-items — 包含追踪状态及各位置可用数量的Shopify库存商品。
  • shopify-pp-cli inventory-items get
    — 通过GraphQL ID获取单个Shopify库存商品信息。
  • shopify-pp-cli inventory-items list
    — 从Shopify Admin GraphQL API列出库存商品信息。
orders — 包含金额总计、财务状态及履约状态的Shopify订单。
  • shopify-pp-cli orders get
    — 通过GraphQL ID获取单个Shopify订单信息。
  • shopify-pp-cli orders list
    — 从Shopify Admin GraphQL API列出订单信息。
products — 包含商品状态、目录元数据及精简变体库存投影的Shopify商品。
  • shopify-pp-cli products get
    — 通过GraphQL ID获取单个Shopify商品信息。
  • shopify-pp-cli products list
    — 从Shopify Admin GraphQL API列出商品信息。
手动编写的命令
  • shopify-pp-cli bulk-operations current
    — 显示当前或最近的Shopify批量操作。
  • shopify-pp-cli bulk-operations run-query --query-file <path>
    — 通过查询文件启动Shopify批量GraphQL导出任务。

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 
SHOPIFY_NO_AUTO_REFRESH=1
to skip the freshness hook without changing source selection.
Covered paths:
  • shopify-pp-cli customers
  • shopify-pp-cli customers get
  • shopify-pp-cli customers list
  • shopify-pp-cli fulfillment-orders
  • shopify-pp-cli fulfillment-orders get
  • shopify-pp-cli fulfillment-orders list
  • shopify-pp-cli inventory-items
  • shopify-pp-cli inventory-items get
  • shopify-pp-cli inventory-items list
  • shopify-pp-cli orders
  • shopify-pp-cli orders get
  • shopify-pp-cli orders list
  • shopify-pp-cli products
  • shopify-pp-cli products get
  • shopify-pp-cli products list
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.
本CLI仅对已注册的商店支持的读取命令路径提供有限的新鲜度保证。在
--data-source auto
模式下，这些路径会检查
sync_state
，并可能在读取本地数据前执行有限的刷新操作。
--data-source local
模式从不刷新数据。
--data-source live
模式直接读取API且不修改本地存储。设置
SHOPIFY_NO_AUTO_REFRESH=1
可跳过新鲜度检查，无需更改数据源选择。
覆盖的命令路径：
  • shopify-pp-cli customers
  • shopify-pp-cli customers get
  • shopify-pp-cli customers list
  • shopify-pp-cli fulfillment-orders
  • shopify-pp-cli fulfillment-orders get
  • shopify-pp-cli fulfillment-orders list
  • shopify-pp-cli inventory-items
  • shopify-pp-cli inventory-items get
  • shopify-pp-cli inventory-items list
  • shopify-pp-cli orders
  • shopify-pp-cli orders get
  • shopify-pp-cli orders list
  • shopify-pp-cli products
  • shopify-pp-cli products get
  • shopify-pp-cli products list
当JSON输出使用生成的来源信封时，新鲜度元数据会显示在
meta.freshness
字段中。该字段表示对应命令路径的当前缓存新鲜度，不保证完整的历史回填或特定API的增强数据。

Finding the right command

查找合适的命令

When you know what you want to do but not which command does it, ask the CLI directly:
bash
shopify-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.
当你知道要执行的操作但不确定对应的命令时，可直接询问CLI：
bash
shopify-pp-cli which "<用你自己的语言描述功能>"
which
命令会将自然语言的功能查询解析为与CLI精选功能索引最匹配的命令。退出码
0
表示至少找到一个匹配项；退出码
2
表示没有找到可信匹配项，请回退到
--help
或使用更精确的查询。

Auth Setup

认证设置

Set the store host, Admin API version, and access token via environment variables:
bash
export SHOPIFY_SHOP="<your-store>.myshopify.com"
export SHOPIFY_API_VERSION="2026-04"
export SHOPIFY_ACCESS_TOKEN="<your-key>"
Or persist it in 
~/.config/shopify-pp-cli/config.toml
.
Run 
shopify-pp-cli doctor
to verify setup.
通过环境变量设置商店主机、Admin API版本及访问令牌：
bash
export SHOPIFY_SHOP="<你的商店>.myshopify.com"
export SHOPIFY_API_VERSION="2026-04"
export SHOPIFY_ACCESS_TOKEN="<你的密钥>"
也可将配置持久化到
~/.config/shopify-pp-cli/config.toml
文件中。
执行
shopify-pp-cli doctor
验证配置是否正确。

Agent Mode

Agent模式

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:
    bash
    shopify-pp-cli customers 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
  • Non-interactive — never prompts, every input is a flag
  • Read-mostly — resource commands are read-only; 
    bulk-operations run-query
    mutates remote state by starting an export job and should only be used on explicit request
在任何命令后添加
--agent
参数，该参数等价于：
--json --compact --no-input --no-color --yes
。
  • 可管道化 — 标准输出为JSON格式，错误信息输出到标准错误
  • 可过滤 — 
    --select
    参数保留指定字段子集。点路径可深入嵌套结构；数组会遍历每个元素。这在处理冗长API时对缩小上下文范围至关重要：
    bash
    shopify-pp-cli customers list --agent --select id,name,status
  • 可预览 — 
    --dry-run
    参数显示请求内容但不发送
  • 离线友好 — 同步/搜索命令在可用时可使用本地SQLite存储
  • 非交互式 — 从不提示用户，所有输入均通过标志参数提供
  • 只读优先 — 资源命令为只读；
    bulk-operations run-query
    会通过启动导出任务修改远程状态，仅应在用户明确请求时使用

Response envelope

响应信封

Commands that read from the local store or the API wrap output in a provenance envelope:
json
{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}
Parse 
.results
for data and 
.meta.source
to know whether it's live or local. A human-readable 
N results (live)
summary is printed to stderr only when stdout is a terminal — piped/agent consumers get pure JSON on stdout.
从本地存储或API读取数据的命令会将输出包装在来源信封中：
json
{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <数据>
}
解析
.results
字段获取数据，
.meta.source
字段表示数据来源是实时API还是本地存储。仅当标准输出为终端时，才会将人类可读的
N results (live)
摘要输出到标准错误；管道/Agent消费者仅会在标准输出获取纯JSON数据。

Agent Feedback

Agent反馈

When you (or the agent) notice something off about this CLI, record it:
shopify-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
shopify-pp-cli feedback --stdin < notes.txt
shopify-pp-cli feedback list --json --limit 10
Entries are stored locally at 
~/.shopify-pp-cli/feedback.jsonl
. They are never POSTed unless 
SHOPIFY_FEEDBACK_ENDPOINT
is set AND either 
--send
is passed or 
SHOPIFY_FEEDBACK_AUTO_SEND=true
. Default behavior is local-only.
Write what surprised you, not a bug report. Short, specific, one line: that is the part that compounds.
当你（或Agent）发现本CLI存在问题时，可记录反馈：
shopify-pp-cli feedback "--since标志是包含性的，但文档说是排他性的"
shopify-pp-cli feedback --stdin < notes.txt
shopify-pp-cli feedback list --json --limit 10
反馈条目会本地存储在
~/.shopify-pp-cli/feedback.jsonl
文件中。仅当设置了
SHOPIFY_FEEDBACK_ENDPOINT
且传递了
--send
参数或设置了
SHOPIFY_FEEDBACK_AUTO_SEND=true
时，反馈才会被POST到指定端点。默认行为仅本地存储反馈。
请记录让你感到意外的内容，而非正式的Bug报告。简短、具体、单条记录：这样的反馈才更有价值。

Output Delivery

输出交付

Every command accepts 
--deliver <sink>
. The output goes to the named sink in addition to (or instead of) stdout, so agents can route command results without hand-piping. Three sinks are supported:
SinkEffect
stdout
Default; write to stdout only
file:<path>
Atomically write output to 
<path>
(tmp + rename)
webhook:<url>
POST the output body to the URL (
application/json
or 
application/x-ndjson
when 
--compact
)
Unknown schemes are refused with a structured error naming the supported set. Webhook failures return non-zero and log the URL + HTTP status on stderr.
每个命令都支持
--deliver <sink>
参数。输出会发送到指定的sink，同时（或替代）输出到标准输出，以便Agent无需手动管道即可路由命令结果。支持三种sink：
Sink效果
stdout
默认值；仅输出到标准输出
file:<path>
原子性地将输出写入
<path>
（先写入临时文件再重命名）
webhook:<url>
将输出体POST到指定URL（
application/json
格式，若使用
--compact
则为
application/x-ndjson
格式）
若使用不支持的协议，会返回结构化错误并列出支持的协议集合。Webhook失败时会返回非零退出码，并将URL及HTTP状态记录到标准错误。

Named Profiles

命名配置文件

A profile is a saved set of flag values, reused across invocations. Use it when a scheduled agent calls the same command every run with the same configuration - HeyGen's "Beacon" pattern.
shopify-pp-cli profile save briefing --json
shopify-pp-cli --profile briefing customers list
shopify-pp-cli profile list --json
shopify-pp-cli profile show briefing
shopify-pp-cli profile delete briefing --yes
Explicit flags always win over profile values; profile values win over defaults. 
agent-context
lists all available profiles under 
available_profiles
so introspecting agents discover them at runtime.
配置文件是一组保存的标志值，可在多次调用中复用。当定时Agent每次运行都使用相同配置调用同一命令时，可使用此功能（即HeyGen的“Beacon”模式）。
shopify-pp-cli profile save briefing --json
shopify-pp-cli --profile briefing customers list
shopify-pp-cli profile list --json
shopify-pp-cli profile show briefing
shopify-pp-cli profile delete briefing --yes
显式标志参数优先级始终高于配置文件中的值；配置文件中的值优先级高于默认值。
agent-context
命令会在
available_profiles
字段下列出所有可用配置文件，以便Agent在运行时自动发现。

Exit Codes

退出码

CodeMeaning
0Success
2Usage error (wrong arguments)
3Resource not found
4Authentication required
5API error (upstream issue)
7Rate limited (wait and retry)
10Config error
代码含义
0成功
2使用错误（参数错误）
3资源未找到
4需要认证
5API错误（上游问题）
7请求受限（请等待后重试）
10配置错误

Argument Parsing

参数解析

Parse 
$ARGUMENTS
:
  1. Empty, 
    help
    , or 
    --help
     → show 
    shopify-pp-cli --help
    output
  2. Starts with 
    install
     → ends with 
    mcp
    → MCP installation; otherwise → see Prerequisites above
  3. Anything else → Direct Use (execute as CLI command with 
    --agent
    )
解析
$ARGUMENTS
的规则：
  1. 为空、
    help
    或
    --help
     → 显示
    shopify-pp-cli --help
    的输出
  2. 以
    install
    开头     → 若结尾为
    mcp
    → 安装MCP服务器；否则 → 参考上方前提条件中的安装步骤
  3. 其他情况 → 直接使用（添加
    --agent
    参数执行CLI命令）

MCP Server Installation

MCP服务器安装

  1. Install the MCP server:
    bash
    go install github.com/mvanhorn/printing-press-library/library/commerce/shopify/cmd/shopify-pp-mcp@latest
  2. Register with Claude Code:
    bash
    claude mcp add shopify-pp-mcp -- shopify-pp-mcp
  3. Verify: 
    claude mcp list
  1. 安装MCP服务器：
    bash
    go install github.com/mvanhorn/printing-press-library/library/commerce/shopify/cmd/shopify-pp-mcp@latest
  2. 在Claude Code中注册：
    bash
    claude mcp add shopify-pp-mcp -- shopify-pp-mcp
  3. 验证安装：
    claude mcp list

Direct Use

直接使用

  1. Check if installed: 
    which shopify-pp-cli
    If not found, offer to install (see Prerequisites at the top of this skill).
  2. Match the user query to the best command from the Unique Capabilities and Command Reference above.
  3. Execute with the 
    --agent
    flag:
    bash
    shopify-pp-cli <command> [subcommand] [args] --agent
  4. If ambiguous, drill into subcommand help: 
    shopify-pp-cli <command> --help
    .
  1. 检查是否已安装：
    which shopify-pp-cli
    若未找到，可提供安装选项（参考本文档顶部前提条件中的安装步骤）。
  2. 将用户查询与上方“独特功能”和“命令参考”中最匹配的命令对应。
  3. 添加
    --agent
    参数执行命令：
    bash
    shopify-pp-cli <command> [subcommand] [args] --agent
  4. 若存在歧义，可查看子命令帮助：
    shopify-pp-cli <command> --help
    。