1688-cli 0.1.7 → 0.1.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +15 -0
- package/README.md +185 -30
- package/package.json +27 -2
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,21 @@
|
|
|
3
3
|
All notable changes to this project are documented here.
|
|
4
4
|
This project follows [Semantic Versioning](https://semver.org/).
|
|
5
5
|
|
|
6
|
+
## [0.1.9] - 2026-05-13
|
|
7
|
+
|
|
8
|
+
### Changed
|
|
9
|
+
- Rewrote `README.md` for end users (was still MVP-era developer notes).
|
|
10
|
+
Now covers the full command catalog, JSON-for-agents flow, and risk-control
|
|
11
|
+
guidance. 0.1.8 carried the manifest changes but the README write failed —
|
|
12
|
+
this is the real publish.
|
|
13
|
+
- Added badges (version, downloads, license, node) to the README.
|
|
14
|
+
|
|
15
|
+
## [0.1.8] - 2026-05-13
|
|
16
|
+
|
|
17
|
+
### Changed
|
|
18
|
+
- Added `keywords`, `repository`, `homepage`, `bugs` to `package.json` for
|
|
19
|
+
npm search discoverability.
|
|
20
|
+
|
|
6
21
|
## [0.1.7] - 2026-05-13
|
|
7
22
|
|
|
8
23
|
### Changed
|
package/README.md
CHANGED
|
@@ -1,48 +1,203 @@
|
|
|
1
|
-
# 1688
|
|
1
|
+
# 1688-cli
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/1688-cli)
|
|
4
|
+
[](https://www.npmjs.com/package/1688-cli)
|
|
5
|
+
[](./LICENSE)
|
|
6
|
+
[](https://nodejs.org/)
|
|
4
7
|
|
|
5
|
-
|
|
6
|
-
|
|
8
|
+
**1688.com CLI for humans, Codex, and Claude Code.**
|
|
9
|
+
Search, browse, cart, place orders, track logistics, and talk to sellers — all
|
|
10
|
+
from your terminal. Outputs human text on a TTY and JSON when piped, so AI
|
|
11
|
+
agents can drive it without parsing.
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npm i -g 1688-cli
|
|
15
|
+
1688 login # scan QR with the 1688 app
|
|
16
|
+
1688 search "机械键盘" --max 10
|
|
17
|
+
1688 stuck # orders paid but not shipped > 3 days
|
|
18
|
+
1688 fake-shipped # waybill printed but courier never collected
|
|
19
|
+
1688 seller chat <orderId> "麻烦尽快发货谢谢"
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## Why
|
|
25
|
+
|
|
26
|
+
Existing 1688 automation options are heavy: Selenium glue you maintain, browser
|
|
27
|
+
extensions you can't pipe into a shell, MCP servers that fight with your
|
|
28
|
+
agent's tooling. `1688-cli` is a single command:
|
|
29
|
+
|
|
30
|
+
- **Real Chrome under the hood** (`channel:'chrome'` + stealth). Reduced
|
|
31
|
+
risk-control hits compared to bundled Chromium.
|
|
32
|
+
- **Persistent profile** at `~/.1688/`. One login lasts for weeks.
|
|
33
|
+
- **Long-running daemon** — first command warms the browser, subsequent
|
|
34
|
+
commands reuse it (no relaunch per call).
|
|
35
|
+
- **JSON-or-text dual mode** — `1688 order list | jq` works; `1688 order list`
|
|
36
|
+
in your terminal pretty-prints.
|
|
37
|
+
- **Designed for AI agents.** See [AGENTS.md](./AGENTS.md) for the contract.
|
|
38
|
+
|
|
39
|
+
---
|
|
7
40
|
|
|
8
41
|
## Install
|
|
9
42
|
|
|
43
|
+
Requires Node 20+ and (recommended) Google Chrome installed. Without Chrome,
|
|
44
|
+
postinstall downloads Playwright's bundled Chromium (~150 MB; China users get
|
|
45
|
+
the npmmirror automatically).
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
npm i -g 1688-cli
|
|
49
|
+
1688 doctor # verify environment
|
|
50
|
+
1688 login # one-time, scan QR on phone
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
## Commands
|
|
56
|
+
|
|
57
|
+
### Account
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
1688 login # scan QR; auto-starts daemon
|
|
61
|
+
1688 login --headed # open real window (fallback for risk control)
|
|
62
|
+
1688 login --force # re-login even if cached
|
|
63
|
+
1688 logout # clear cookies
|
|
64
|
+
1688 whoami # current nick + memberId
|
|
65
|
+
1688 doctor # environment check
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
### Daemon
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
1688 daemon start | stop | status | reload
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
### Search & browse
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
1688 search 机械键盘 --max 20
|
|
78
|
+
1688 image-search ./shoe.jpg # local file
|
|
79
|
+
1688 image-search https://.../img.png # http(s) URL
|
|
80
|
+
1688 offer 628196518518 # product detail
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
### Orders
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
1688 order list # all statuses
|
|
87
|
+
1688 order list --status waitsellersend # paid, awaiting shipment
|
|
88
|
+
1688 order list --status waitbuyerreceive # shipped, awaiting delivery
|
|
89
|
+
1688 order get <orderId>
|
|
90
|
+
1688 order logistics <orderId> # tracking number + trace
|
|
91
|
+
1688 order get <orderId> --status waitbuyerreceive # speeds up scan on heavy accounts
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
### Cart
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
1688 cart list
|
|
98
|
+
1688 cart add <offerId> --sku <skuId> --qty 2
|
|
99
|
+
1688 cart remove <cartId>
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
### Checkout (writes!)
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
1688 checkout prepare <cartIds...> # preview only — safe
|
|
106
|
+
1688 checkout confirm <cartIds...> # default: TTY prompt y/N
|
|
107
|
+
1688 checkout confirm <cartIds...> -y # skip prompt (TTY still required)
|
|
108
|
+
1688 checkout confirm <cartIds...> --agent # AI-agent mode: no prompts
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
### Seller IM (旺旺)
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
1688 seller inquire <offerId> "支持定制 logo 吗？" # pre-sale (auto-finds seller)
|
|
115
|
+
1688 seller chat <orderId> "麻烦尽快发货谢谢" # post-sale (auto-attaches order card)
|
|
116
|
+
1688 seller chat <orderId> "..." --no-card # follow-up reply, no card
|
|
117
|
+
1688 seller messages <orderId> --limit 20
|
|
118
|
+
1688 seller messages <orderId> --since 2026-05-01T00:00:00+08:00
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
### Workflow shortcuts
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
1688 shipped <orderId> # order detail + logistics merged
|
|
125
|
+
1688 stuck --days 3 # paid but not shipped > N days
|
|
126
|
+
1688 fake-shipped --days 1 # marked shipped but courier never collected (虚假发货)
|
|
127
|
+
1688 fake-shipped --debug # show each candidate's status + remark
|
|
128
|
+
1688 seller-history <sellerName> # all orders + avg ship days + on-time rate
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
---
|
|
132
|
+
|
|
133
|
+
## JSON for agents
|
|
134
|
+
|
|
135
|
+
Every command auto-switches to JSON when stdout is piped:
|
|
136
|
+
|
|
137
|
+
```bash
|
|
138
|
+
1688 order list --status waitsellersend | jq '.orders[] | {id: .orderId, paid: .paidAt}'
|
|
139
|
+
1688 fake-shipped --debug | jq '.orders[].orderId'
|
|
140
|
+
1688 search 雨伞 | jq '.offers[0:5]'
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
Force JSON on a TTY:
|
|
144
|
+
|
|
10
145
|
```bash
|
|
11
|
-
|
|
12
|
-
npx playwright install chromium # if postinstall didn't run
|
|
146
|
+
BB1688_JSON=1 1688 doctor
|
|
13
147
|
```
|
|
14
148
|
|
|
15
|
-
|
|
149
|
+
---
|
|
150
|
+
|
|
151
|
+
## Risk control
|
|
152
|
+
|
|
153
|
+
1688's WAF triggers a slider challenge on suspicious traffic.
|
|
154
|
+
`1688-cli` already uses real Chrome + stealth + a persistent profile, and the
|
|
155
|
+
`search` command warms up `s.1688.com` before every request. If you still hit
|
|
156
|
+
a slider, solve it once with `--headed`:
|
|
16
157
|
|
|
17
158
|
```bash
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
pnpm dev whoami --verify # additionally probes 1688 to detect stale cookies
|
|
21
|
-
pnpm dev logout # interactive confirm; --yes to skip
|
|
22
|
-
pnpm dev logout --yes | jq # JSON output (auto when piped)
|
|
159
|
+
1688 search 雨伞 --headed # window opens; drag the slider once
|
|
160
|
+
1688 search 雨伞 # subsequent headless calls work for hours
|
|
23
161
|
```
|
|
24
162
|
|
|
25
|
-
|
|
163
|
+
---
|
|
26
164
|
|
|
27
|
-
|
|
28
|
-
Cookies, localStorage, IndexedDB, and device fingerprint all live there.
|
|
29
|
-
- **State cache** at `~/.1688/state.json` (nick / memberId / timestamps).
|
|
30
|
-
Source of truth is always the cookies — state.json is just a cache.
|
|
31
|
-
- **One process at a time** via `proper-lockfile` on `~/.1688/.lock`.
|
|
32
|
-
- **JSON when piped**, human-readable on TTY. Force JSON via `BB1688_JSON=1`.
|
|
165
|
+
## Files & directories
|
|
33
166
|
|
|
34
|
-
|
|
167
|
+
```
|
|
168
|
+
~/.1688/profiles/default/ Chromium profile (cookies, IndexedDB, fingerprint)
|
|
169
|
+
~/.1688/state.json cached identity (nick / memberId / timestamps)
|
|
170
|
+
~/.1688/daemon.sock daemon Unix socket
|
|
171
|
+
~/.1688/daemon.pid daemon PID
|
|
172
|
+
~/.1688/.lock proper-lockfile (one process at a time)
|
|
173
|
+
```
|
|
35
174
|
|
|
36
|
-
##
|
|
175
|
+
## Environment variables
|
|
37
176
|
|
|
38
177
|
```
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
tests/
|
|
47
|
-
scripts/postinstall.mjs # auto-installs Chromium on first npm install
|
|
178
|
+
BB1688_NO_DAEMON=1 disable daemon, always run inline
|
|
179
|
+
BB1688_JSON=1 force JSON output on TTY
|
|
180
|
+
BB1688_DEBUG=1 verbose internal logs to stderr
|
|
181
|
+
BB1688_FORCE_CHROMIUM=1 skip system Chrome, use bundled Chromium
|
|
182
|
+
BB1688_HOME=<path> override ~/.1688
|
|
183
|
+
BB1688_SKIP_POSTINSTALL=1 skip Chromium download during npm install
|
|
184
|
+
PLAYWRIGHT_DOWNLOAD_HOST custom Playwright mirror
|
|
48
185
|
```
|
|
186
|
+
|
|
187
|
+
---
|
|
188
|
+
|
|
189
|
+
## Status
|
|
190
|
+
|
|
191
|
+
Pre-1.0 — the surface is shaped but minor breaks are possible between minor
|
|
192
|
+
versions until 1.0. See [CHANGELOG.md](./CHANGELOG.md). Not affiliated with
|
|
193
|
+
Alibaba / 1688.
|
|
194
|
+
|
|
195
|
+
## Agent contract
|
|
196
|
+
|
|
197
|
+
If you're driving `1688-cli` from Codex, Claude Code, or another autonomous
|
|
198
|
+
agent, read [AGENTS.md](./AGENTS.md) — it documents JSON shapes, exit codes,
|
|
199
|
+
and the rules around the write commands.
|
|
200
|
+
|
|
201
|
+
## License
|
|
202
|
+
|
|
203
|
+
[MIT](./LICENSE)
|
package/package.json
CHANGED
|
@@ -1,9 +1,34 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "1688-cli",
|
|
3
|
-
"version": "0.1.
|
|
4
|
-
"description": "1688 CLI for humans, Codex, and Claude Code",
|
|
3
|
+
"version": "0.1.9",
|
|
4
|
+
"description": "1688.com CLI for humans, Codex, and Claude Code — search, cart, orders, logistics, seller IM, fake-shipping detection.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "nobodyjack",
|
|
7
|
+
"homepage": "https://github.com/nobodyjack/1688-cli#readme",
|
|
8
|
+
"repository": {
|
|
9
|
+
"type": "git",
|
|
10
|
+
"url": "git+https://github.com/nobodyjack/1688-cli.git"
|
|
11
|
+
},
|
|
12
|
+
"bugs": {
|
|
13
|
+
"url": "https://github.com/nobodyjack/1688-cli/issues"
|
|
14
|
+
},
|
|
15
|
+
"keywords": [
|
|
16
|
+
"1688",
|
|
17
|
+
"alibaba",
|
|
18
|
+
"cli",
|
|
19
|
+
"agent",
|
|
20
|
+
"ai-agent",
|
|
21
|
+
"claude",
|
|
22
|
+
"claude-code",
|
|
23
|
+
"codex",
|
|
24
|
+
"automation",
|
|
25
|
+
"ecommerce",
|
|
26
|
+
"procurement",
|
|
27
|
+
"playwright",
|
|
28
|
+
"mtop",
|
|
29
|
+
"wholesale",
|
|
30
|
+
"china"
|
|
31
|
+
],
|
|
7
32
|
"type": "module",
|
|
8
33
|
"bin": {
|
|
9
34
|
"1688": "dist/cli.js"
|