跳到主要内容

输出格式

Shoplazza CLI 支持多种输出格式和过滤选项。

--format 参数​

格式说明适用场景
json结构化 JSON 信封（stdout 被管道或重定向、在 CI 中或带 --no-input 时的默认值）脚本、AI Agent、管道
pretty人类可读的键值对（交互式终端中的默认值）快速查看
table带表头的对齐列表格终端浏览
ndjson每行一条紧凑的 JSON 记录流式处理大列表
csv表头行加每条记录一行导出到表格软件

SHOPLAZZA_CLI_FORMAT 可固定默认格式（例如在 pty 中用 SHOPLAZZA_CLI_FORMAT=json 强制输出 JSON）；显式传 --format 始终优先。只有 json 是稳定契约：其他格式直接输出响应体、不带 {"ok": true, "data": …} 信封，pretty 和 table 还可能截短嵌套数据，不要解析它们。

使用 --jq 过滤​

表达式作用于完整的 {"ok": true, "data": …} 信封，且 --jq 需要 JSON 输出：交互式终端中默认是 pretty，需加 --format json，否则命令报错 --jq requires --format json。

shell
shoplazza products list --format json --jq '.data.products[].title'
shoplazza orders list --format json --jq '.data.orders[] | {id, status, total_price}'
shoplazza products list --format json --jq '.data.products | length'

-q 是 --jq 的简写。字符串结果输出时不带引号。

--fields 字段投影​

products +search 支持 --fields，指定 API 返回哪些商品字段：

shell
shoplazza products +search --keyword "shirt" --fields "id,title,price_min" --format table

其他命令没有 --fields，请改用 --jq 裁剪。

--dry-run 预览请求​

shell
shoplazza products list --dry-run

显示将要发送的 HTTP 方法、路径、URL、查询参数和请求体，但不实际执行。

输出约定​

  • stdout — 数据输出（JSON 信封），可安全管道传输
  • stderr — 进度指示器、警告和提示

成功信封​

json
{"ok": true, "data": { ... }}

有新版本 CLI 或未安装 Agent Skills 时，JSON 信封顶层还会带一个面向智能体的 _notice 对象（update、skills）。设置 SHOPLAZZA_CLI_NO_NOTICE=1 可去掉它。

错误结构​

json
{"ok": false, "error": {"type": "api", "message": "Product not found", "detail": {"status_code": 404, "request_id": "req_abc123"}}}

在交互式终端中使用 pretty 或 table 输出时，错误改为显示易读的 Error: 行。详见 错误格式。

在此页面