1688-cli 0.1.27 → 0.1.28

package/AGENTS.md

@@ -199,6 +199,33 @@ To get the cartId reliably in a pipeline:
 id=$(1688 cart add <offerId> --sku <skuId> --qty 1 | jq -r '.added.cartId')
 ```
 
+## Output flags (every command)
+
+In addition to `BB1688_JSON=1`, every command accepts:
+
+```
+--json            Force JSON output even in a TTY.
+--pretty          Indent JSON by 2 spaces.
+--get <path>      Print one field by dot-path. Scalar → raw line,
+                  object/array → JSON. Wildcards stream one element per line.
+                  Syntax: field.sub, arr[N].field, arr[*].field
+--pick <paths>    Comma-separated dot-paths → emit a JSON object with each
+                  path as a key. Useful for trimming output for downstream agents.
+```
+
+Examples:
+```bash
+1688 offer X --get supplier.name              # 深圳... (raw)
+1688 offer X --get supplier                   # {"name":"...","loginId":"..."}
+1688 offer X --get 'skus[*].price'            # 49 \n 68 \n 98.75 ...
+1688 offer X --pick price,supplier.name       # {"price":1.25,"supplier.name":"..."}
+1688 offer X --json --pretty                  # full payload, indented
+```
+
+When `--get`/`--pick` is given, the human renderer is skipped; the resolved
+value(s) go to stdout. The full payload still flows through when neither
+flag is set, so existing `| jq` pipelines keep working.
+
 ## Discovery
 
 Run `1688 --help` and `1688 <command> --help` for the latest flags.

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 All notable changes to this project are documented here.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.1.28] - 2026-05-13
+
+### Documentation
+- README: document the `--json` / `--pretty` / `--get` / `--pick` flags in
+  the "JSON for agents" section with copy-pasteable examples.
+- AGENTS.md: add an "Output flags" section so agents can discover the
+  zero-`jq` workflows.
+
 ## [0.1.27] - 2026-05-13
 
 ### Added

package/README.md

@@ -249,7 +249,31 @@ Every command auto-switches to JSON when stdout is piped:
 1688 search 雨伞                       | jq '.offers[0:5]'
 ```
 
-Force JSON on a TTY:
+### Built-in JSON flags (no `jq` required)
+
+Every command supports four output-shaping flags. Useful on Windows or any
+environment where `jq` isn't installed — and for agents that want concise
+output without parsing the full payload.
+
+```bash
+1688 offer <id> --json                       # force JSON even in a TTY
+1688 offer <id> --json --pretty              # JSON with 2-space indent
+
+1688 offer <id> --get supplier.name          # one scalar field, raw line
+1688 offer <id> --get supplier               # sub-object as JSON
+1688 offer <id> --get 'skus[0].skuId'        # array index
+1688 offer <id> --get 'skus[*].price'        # wildcard — one line per element
+
+1688 offer <id> --pick price,supplier.name,'skus[0].skuId'
+# {"price":1.25,"supplier.name":"...","skus[0].skuId":"..."}
+```
+
+Path syntax: `field.sub`, `arr[N].field`, `arr[*].field`. Wildcards stream
+one line per element; scalars print as a raw line (no quotes), objects and
+arrays as JSON. The full payload still goes through when no `--get`/`--pick`
+is given, so existing `| jq` pipelines keep working unchanged.
+
+Force JSON in a TTY (alternative to `--json`):
 
 ```bash
 BB1688_JSON=1 1688 doctor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "1688-cli",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "description": "1688.com CLI for humans, Codex, and Claude Code. Sourcing (search / image-search / offer / inquire) and orders (list / detail / logistics / seller chat).",
   "license": "MIT",
   "author": "nobodyjack",