# 输出格式

> 控制 Shoplazza CLI 的输出：用 --format 选择 json、pretty、table、ndjson 或 csv，用 --jq 过滤、--fields 裁剪字段、--dry-run 预览请求。

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:` 行。详见 [错误格式](../reference/error-format)。