Skip to content
Back to search

1688-cli

1688 CLI is an AI-agent-friendly command-line tool for 1688 sourcing, product research, supplier evaluation, procurement Inquire, and order management.helping dropshippers and Amazon sellers automate and streamline their sourcing workflow from 1688.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/superjack2050--1688-cli/badge.svg)](/listings/superjack2050--1688-cli)

HTML

<a href="/listings/superjack2050--1688-cli"><img src="/api/listings/superjack2050--1688-cli/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires Node 20+ and (recommended) Google Chrome installed. Without Chrome, postinstall downloads Playwright's bundled Chromium (~150 MB; China users get the npmmirror automatically).

npm i -g 1688-cli
1688 doctor                # verify environment
1688 login                 # one-time, scan QR on phone

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 689 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # 1688 CLI: AI Agents Friendly Alibaba 1688.com Product Search & Supplier Scraper CLI
  2. [![npm version](https://img.shields.io/npm/v/1688-cli.svg)](https://www.npmjs.com/package/1688-cli)
  3. [![npm downloads](https://img.shields.io/npm/dm/1688-cli.svg)](https://www.npmjs.com/package/1688-cli)
  4. [![license](https://img.shields.io/npm/l/1688-cli.svg)](./LICENSE)
  5. [![node](https://img.shields.io/node/v/1688-cli.svg)](https://nodejs.org/)
  6. [English](./README.md) | [简体中文](./README_zh-CN.md)
  7. Command-line tool for Alibaba 1688.com wholesale: product search, supplier
  8. company search, supplier scraper/research, image search, supplier inquiry, cart,
  9. checkout, order tracking, and seller chat. Outputs JSON when piped (for Codex /
  10. Claude Code / other AI agents) and pretty TTY text for humans.
  11. The 6 things you can do from the terminal:
  12. 1. **Sourcing** — product scraper/research + supplier scraper/research
  13. 2. **Pre-sale inquiry** — ask the supplier, watch replies live
  14. 3. **Cart** — collect SKUs (with diff-based add confirmation)
  15. 4. **Checkout** — preview + place the order
  16. 5. **Order tracking** — list / detail / logistics / overdue detection
  17. 6. **Post-sale chat** — chase shipment, read replies as JSON stream
  18. ```bash
  19. npm i -g 1688-cli
  20. 1688 login # scan QR with the 1688 app
  21. # Product scraper / product research
  22. 1688 search "佛龛柜" --max 10 # keyword search
  23. 1688 search "手机壳" --sort best-selling --price-max 50 # sorted/filtered sourcing
  24. 1688 research 手机壳 数据线 --max-per-query 50 --jsonl # multi-keyword research dataset
  25. 1688 image-search ./sample.jpg # search by image
  26. 1688 offer 628196518518 # single product detail
  27. 1688 offer 628196518518 1234567890 --json --pretty --pro # batch product detail, bypass daemon
  28. 1688 compare 628196518518 1234567890 # compare offer details
  29. # Supplier scraper / supplier research
  30. 1688 supplier search 键盘 --factory-only --json # supplier discovery from company search
  31. 1688 supplier research 键盘 --enrich top:5 --csv # supplier scoring + inspect enrichment
  32. 1688 supplier inspect 628196518518 # inspect supplier/factory trust signals
  33. # Pre-sale inquiry (with live watch for AI agents)
  34. 1688 seller inquire 628196518518 "支持定制 logo 吗?" # ask seller
  35. 1688 seller messages --offer 628196518518 # one-shot read
  36. 1688 seller messages --offer 628196518518 --watch # live-tail new replies (JSON when piped)
  37. # Order tracking & post-sale chat
  38. 1688 order list --status waitsellersend # list orders
  39. 1688 order get <orderId> # one order detail
  40. 1688 order logistics <orderId> # tracking + trace
  41. 1688 seller chat <orderId> "麻烦尽快发货谢谢" # chase shipment
  42. 1688 seller messages <orderId> # read seller's reply
  43. ```
  44. ---
  45. ## Why
  46. Existing 1688 automation options are heavy: Selenium glue you maintain, browser
  47. extensions you can't pipe into a shell, MCP servers that fight with your
  48. agent's tooling. `1688-cli` is a single command:
  49. - **Real Chrome under the hood** (`channel:'chrome'`). Same browser you'd
  50. use manually — your session is real, not a synthetic Chromium.
  51. - **Persistent profiles** under `~/.1688/`. One login lasts for weeks, and
  52. multiple buyer profiles can stay isolated.
  53. - **Profile-scoped daemon** — each profile can keep its own warm browser
  54. context, so subsequent commands reuse it without relaunching Chrome.
  55. - **JSON-or-text dual mode** — `1688 order list | jq` works; `1688 order list`
  56. in your terminal pretty-prints.
  57. - **Designed for AI agents.** See [AGENTS.md](./AGENTS.md) for the contract.
  58. ### Not in scope
  59. This is not a marketing / scraping tool for bulk-listing the whole site, and
  60. not a checkout automation farm. It mirrors what a buyer does manually: pick
  61. a product, ask the seller a question, place an order, track shipping. Place
  62. order (`checkout confirm`) is gated behind TTY prompts or an explicit
  63. `--agent` flag so agents can't move money silently.
  64. ---
  65. ## Install
  66. Requires Node 20+ and (recommended) Google Chrome installed. Without Chrome,
  67. postinstall downloads Playwright's bundled Chromium (~150 MB; China users get
  68. the npmmirror automatically).
  69. ```bash
  70. npm i -g 1688-cli
  71. 1688 doctor # verify environment
  72. 1688 login # one-time, scan QR on phone
  73. ```
  74. ---
  75. ## Command reference
  76. | Command | Description |
  77. |---|---|
  78. | `1688 login` | Scan QR code to log in; auto-starts daemon |
  79. | `1688 search <keyword>` | Keyword product search with filters |
  80. | `1688 research <keywords...>` | Multi-keyword sourcing with scoring and enrichment |
  81. | `1688 compare <offerIds...>` | Compare multiple offer detail pages |
  82. | `1688 supplier inspect <target>` | Supplier identity, factory card, trust signals |
  83. | `1688 supplier search <keywords...>` | Company-search supplier discovery |
  84. | `1688 supplier research <keywords...>` | Scored supplier dataset with inspect enrichment |
  85. | `1688 image-search <path\|url>` | Search by local image or http(s) URL |
  86. | `1688 offer <offerIds...>` | Single or batch product detail (SKUs, package, images) |
  87. | `1688 similar <offerId>` | Find similar / 找同款 offers (official entry point) |
  88. | `1688 inbox` | List recent 旺旺 IM conversations |
  89. | `1688 seller inquire` | Pre-sale inquiry: send product link + question |
  90. | `1688 seller messages` | Read seller conversation messages |
  91. | `1688 seller chat` | Send message to seller (order or pre-sale) |
  92. | `1688 checkout prepare` | Preview total/address/items for checkout (read-only) |
  93. | `1688 checkout confirm` | Place an order for selected cart items |
  94. | `1688 cart list` | List items in your cart |
  95. | `1688 cart add` | Add one item to cart by offerId + SKU |
  96. | `1688 cart remove` | Remove one item from cart by cartId |
  97. | `1688 shipped <orderId>` | Order detail + logistics merged |
  98. | `1688 stuck` | Orders paid but not shipped after N days |
  99. | `1688 fake-shipped` | Orders marked shipped but courier never collected |
  100. | `1688 seller-history <seller>` | All orders from a seller + stats |
  101. | `1688 order list` | List buyer orders by status |
  102. | `1688 order get <orderId>` | Show one order by orderId |
  103. | `1688 order logistics <orderId>` | Shipping status + tracking number |
  104. | `1688 whoami` | Show the current logged-in account |
  105. | `1688 logout` | Log out and clear local session |
  106. | `1688 doctor` | Check environment, profile, Chromium, and session |
  107. | `1688 serve` | Run the 1688 daemon in the foreground |
  108. | `1688 daemon start\|stop\|reload\|status` | Manage the background daemon |
  109. | `1688 profile list\|status` | Inspect local 1688 profiles |
  110. | `1688 debug list\|last\|show` | Inspect recent command events and artifacts |
  111. | `1688 feedback` | Submit feedback or a bug report |
  112. ---
  113. ## Commands
  114. Organized by the buyer journey: discover → ask → decide → buy → track →
  115. follow up.
  116. ### 1. Sourcing — Product Scraper and Supplier Scraper
  117. Sourcing has two separate paths. Use **Product Scraper / Product Research**
  118. when you start from products or offers. Use **Supplier Scraper / Supplier
  119. Research** when you start from companies, factories, or supplier qualification.
  120. #### Product Scraper / Product Research
  121. ```bash
  122. 1688 search 机械键盘 --max 20 # keyword search
  123. 1688 search 手机壳 --sort best-selling --price-max 50 --exclude-ads
  124. 1688 research 手机壳 数据线 --max-per-query 50 --enrich top:5 --csv
  125. 1688 image-search ./shoe.jpg # search by local image
  126. 1688 image-search https://.../img.png # search by http(s) URL
  127. 1688 offer 628196518518 # single product detail (priceTiers, attributes, packageInfo, SKUs)
  128. 1688 offer 628196518518 1234567890 --pro --json # batch product detail, bypass daemon
  129. 1688 compare 628196518518 1234567890 # compare price/MOQ/SKU/sales signals
  130. ```
  131. #### Batch offer collection
  132. Pass multiple offer IDs to collect them in sequence. Single ID keeps the
  133. original JSON shape; multiple IDs return a batch envelope:
  134. ```bash
  135. 1688 offer 967417789506 --json --pretty # single → OfferResult
  136. 1688 offer 967417789506 --json --pretty --pro # single, bypass daemon pause
  137. 1688 offer 967417789506 817273094122 --json --pretty --pro # batch → OfferBatchResult
  138. ```
  139. Batch output shape:
  140. ```json
  141. {
  142. "mode": "batch",
  143. "total": 2,
  144. "success": 2,
  145. "failed": 0,
  146. "offerIds": ["967417789506", "817273094122"],
  147. "offers": [ /* ... */ ],
  148. "failures": []
  149. }
  150. ```
  151. - `--pro` bypasses daemon health pause for each offer.
  152. - `RISK_CONTROL` per-offer failures appear in `failures[]`, don't stop the batch.
  153. - Progress lines are written to stderr so `--json --pretty` stdout stays clean.
  154. #### Deep pro search
  155. Search first, then deep collect returned offer IDs in pro inline mode.
  156. Each offer is retried up to 2 times after the first failed attempt.
  157. ```bash
  158. # Official npm install
  159. 1688 search "修枝剪" --max 30 --deeppro --json --pretty
  160. # Local dev build
  161. node .\dist\cli.js search "修枝剪" --max 30 --deeppro --json --pretty
  162. # Price-filtered deep search
  163. 1688 search "修枝剪" --max 15 --price-min 5 --price-max 20 --deeppro --json --pretty
  164. ```
  165. > `--price-min` / `--price-max` filter the search-page card prices.
  166. > DEEPPRO detail-page prices may exceed the search-page range because
  167. > SKUs are fully expanded on the detail page.
  168. Output includes a `deeppro` envelope alongside normal search results:
  169. ```json
  170. {
  171. "keyword": "修枝剪",
  172. "total": 30,
  173. "offers": [ /* normal search results */ ],
  174. "deeppro": {
  175. "enabled": true,
  176. "total": 30,
  177. "success": 27,
  178. "failed": 3,
  179. "offers": [ /* full OfferResult deep collects */ ],
  180. "failures": [
  181. { "offerId": "...", "code": "RISK_CONTROL", "message": "...", "attempts": 3 }
  182. ]
  183. }
  184. }
  185. ```
  186. - `--max` controls how many search results are deep-collected.
  187. - `--deeppro` uses pro inline collection for every offer, bypassing daemon health pause.
  188. - `--deeppro-delay-min` / `--deeppro-delay-max` control the pause between offers (default 6–10 s).
  189. - Each offer is retried up to 3 times total (1 initial + 2 retries).
  190. - Progress is written to stderr; stdout remains clean JSON.
  191. - `RISK_CONTROL` still means 1688 itself showed a verification challenge.
  192. `1688 search` and `1688 research` are offer-first. They search product offers,
  193. score offer results, export datasets, and can enrich top offers through detail
  194. pages. Use this path when price, MOQ, SKU depth, sales signals, images, and
  195. offer-level comparison are the first decision points.
  196. `1688 similar <offerId>` is retained for compatibility with the official
  197. 1688 "找同款" entry point, but that entry point currently returns an empty
  198. image-search shell for tested offers. The command does not fall back to
  199. keyword or image search because those results are not strict same-product
  200. matches.
  201. #### Supplier Scraper / Supplier Research
  202. ```bash
  203. 1688 supplier search 键盘 --factory-only # company-search supplier discovery, not offer aggregation
  204. 1688 supplier search 键盘 --max 20 --province 广东 --city 深圳
  205. 1688 supplier research 键盘 --enrich top:5 --csv # supplier scoring + optional supplier inspect enrichment
  206. 1688 supplier inspect 628196518518 # supplier identity, factory card, trust/service signals
  207. 1688 supplier inspect b2b-22066467246504ba0d # inspect by supplier memberId
  208. ```
  209. `1688 supplier search` is the read-only 1688 Supplier Scraper. It pulls
  210. supplier/company records directly from 1688 company search
  211. (`companySearchBusinessService`) for a keyword and filters. It does not build
  212. suppliers by grouping product-offer results.
  213. `1688 supplier research` is the scored/export workflow on top of that supplier
  214. scraper, with optional `supplier inspect` enrichment for the top companies.
  215. Use this path when factory identity, service years, repeat/response rates,
  216. location, company profile, and supplier qualification are the first decision
  217. points.
  218. #### Which path should I use?
  219. | Need | Command |
  220. |---|---|
  221. | Find product offers | `1688 search <keyword...>` |
  222. | Build a scored product dataset | `1688 research <keyword...>` |
  223. | Official same-product matching | `1688 similar <offerId>` (currently unavailable when the official endpoint returns empty) |
  224. | Inspect one product offer | `1688 offer <offerId>` |
  225. | Batch collect product offers | `1688 offer <offerId...>` |
  226. | Compare product offers | `1688 compare <offerId...>` |
  227. | Find companies or factories directly | `1688 supplier search <keyword...>` |
  228. | Build a scored supplier dataset | `1688 supplier research <keyword...>` |
  229. | Inspect one supplier/factory | `1688 supplier inspect <offerId|memberId>` |
  230. Supplier company-search flags:
  231. ```bash
  232. 1688 supplier search 键盘 --max 20 --factory-only --province 广东 --city 深圳
  233. 1688 supplier search 键盘 --min-years 3 --min-repeat-rate 0.4 --min-response-rate 0.6
  234. 1688 supplier research 键盘 --enrich top:10 --jsonl
  235. 1688 supplier research 键盘 --enrich top:5 --csv --output suppliers.csv
  236. ```
  237. `supplier search` defaults to no enrichment (`--enrich 0`). `supplier research`
  238. defaults to `--enrich top:10`, which calls `supplier inspect` for the top
  239. company-search suppliers when a `memberId` is available. The supplier result
  240. includes company name, `memberId`, shop URL, location, service years, factory
  241. signals, repeat/response rates, 3-month order/amount signals, score breakdown,
  242. and product previews from the company-search payload.
  243. ### 2. Pre-sale inquiry — ask the supplier
  244. > Uses the same `seller messages` / `seller chat` tooling as §6, scoped by
  245. > `--offer <offerId>` instead of an orderId.
  246. ```bash
  247. 1688 seller inquire 628196518518 "支持定制 logo 吗?" # send a product link + question
  248. 1688 seller messages --offer 628196518518 # read replies (one-shot)
  249. 1688 seller messages --offer 628196518518 --since 2026-05-13T10:00:00+08:00
  250. 1688 seller messages --offer 628196518518 --watch --interval 30 # live-tail new replies
  251. ```
  252. **Watch mode** prints only newly-arrived messages as line-delimited JSON
  253. when stdout is piped — pipe into any agent. Dedup is by server-side
  254. `messageId`. Min interval 10 s.
  255. ### 3. Cart — collect SKUs
  256. ```bash
  257. 1688 cart list
  258. 1688 cart add <offerId> --sku <skuId> --qty 2
  259. 1688 cart remove <cartId>
  260. ```
  261. `cart add` returns `{added: CartItem, isNewRow, addedQuantity}` so pipelines
  262. can pick up the new cartId reliably even when the same SKU is already in cart
  263. (server merges into the existing row in that case):
  264. ```bash
  265. id=$(1688 cart add 628196518518 --sku 6070845665229 --qty 1 | jq -r '.added.cartId')
  266. 1688 cart remove "$id"
  267. ```
  268. PowerShell equivalent:
  269. ```powershell
  270. $added = 1688 cart add 628196518518 --sku 6070845665229 --qty 1 --json | ConvertFrom-Json
  271. 1688 cart remove $added.added.cartId
  272. ```
  273. ### 4. Checkout — place the order
  274. ```bash
  275. 1688 checkout prepare <cartIds...> # preview total/address/items — safe, read-only
  276. 1688 checkout confirm <cartIds...> # default: TTY prompt y/N
  277. 1688 checkout confirm <cartIds...> -y # skip prompt (TTY still required)
  278. 1688 checkout confirm <cartIds...> --agent # AI-agent mode: no prompts (explicit autonomy opt-in)
  279. ```
  280. ### 5. Order tracking — follow the shipment
  281. ```bash
  282. 1688 order list # all statuses (with actions, services, badges)
  283. 1688 order list --status waitsellersend # paid, awaiting shipment
  284. 1688 order list --status waitbuyerreceive # shipped, awaiting delivery
  285. 1688 order get <orderId> # one order detail
  286. 1688 order logistics <orderId> # tracking number + trace
  287. 1688 order get <orderId> --status waitbuyerreceive # narrow the scan on heavy accounts
  288. # Convenience views
  289. 1688 shipped <orderId> # order detail + logistics merged
  290. 1688 stuck --days 3 # paid but not shipped > N days
  291. 1688 fake-shipped --days 1 # marked shipped but courier never collected (虚假发货)
  292. 1688 fake-shipped --debug # show each candidate's status + remark
  293. 1688 seller-history <sellerName> # all orders + avg ship days + on-time rate
  294. ```
  295. ### 6. Post-sale chat — chase delivery / claims
  296. > Same tooling as §2, scoped by `<orderId>` so messages auto-attach the
  297. > order card and replies thread under the right conversation.
  298. ```bash
  299. 1688 seller chat <orderId> "麻烦尽快发货谢谢" # send (auto-attaches order card)
  300. 1688 seller chat <orderId> "请问什么时候发货" --no-card # follow-up, no card
  301. 1688 seller messages <orderId> # read replies
  302. 1688 seller messages <orderId> --limit 50 --since 2026-05-01T00:00:00+08:00
  303. 1688 seller messages <orderId> --watch # live-tail
  304. ```
  305. ### Account & daemon
  306. ```bash
  307. 1688 login # scan QR; auto-starts daemon
  308. 1688 login --headed # open real window (fallback for risk control)
  309. 1688 login --force # re-login even if cached
  310. 1688 logout # clear cookies
  311. 1688 whoami # current nick + memberId
  312. 1688 doctor # environment check
  313. 1688 daemon start | stop | status | reload
  314. ```
  315. ### Profiles
  316. Every command uses the `default` profile unless you pass `--profile <name>`.
  317. Default behavior is backwards-compatible: `1688 search 雨伞` uses the default
  318. profile, default daemon, default lock, and default cached identity.
  319. Use profiles when you operate more than one buyer account or want isolated
  320. cookie/session state:
  321. ```bash
  322. 1688 login --profile acc-a --headed
  323. 1688 login --profile acc-b --headed
  324. 1688 daemon start --profile acc-a
  325. 1688 daemon start --profile acc-b
  326. 1688 daemon status --profile acc-a
  327. 1688 daemon status --profile acc-b
  328. 1688 search "实木床头柜" --profile acc-a
  329. 1688 search "实木床头柜" --profile acc-b
  330. 1688 profile list
  331. 1688 profile status acc-a
  332. 1688 doctor --profile acc-a
  333. ```
  334. Each profile has its own persistent browser directory, daemon process,
  335. socket/named pipe, pid/version/log files, state file, and lock. Different
  336. profiles can run in parallel; commands for one profile do not wait on another
  337. profile's lock. Within one profile, daemon work remains serialized and paced.
  338. ### Inbox — 旺旺 conversations
  339. ```bash
  340. 1688 inbox --limit 20 # recent conversations (newest first)
  341. 1688 inbox --unread # only unread conversations
  342. 1688 inbox --profile acc-a # scoped to a named profile
  343. ```
  344. ### Debug — inspect command events
  345. ```bash
  346. 1688 debug list # recent command events
  347. 1688 debug list --limit 50 --failed # failed events with more history
  348. 1688 debug last # most recent command event
  349. 1688 debug last --failed # most recent failed event
  350. 1688 debug show <requestId> # full event + artifact location
  351. ```
  352. ### Feedback — submit bug reports
  353. ```bash
  354. 1688 feedback "search --deeppro failed on Windows" --bug --no-open
  355. 1688 feedback "offer batch should support --csv export" --submit
  356. ```
  357. ### Serve — foreground daemon
  358. ```bash
  359. 1688 serve --profile default # run daemon in foreground
  360. 1688 serve --idle-timeout 60 # custom idle timeout (minutes)
  361. 1688 serve --no-prewarm # skip Chromium pre-warm at startup
  362. ```
  363. ### Doctor — environment check
  364. ```bash
  365. 1688 doctor # full check with Chromium launch
  366. 1688 doctor --no-launch # skip Chromium launch test (faster)
  367. 1688 doctor --live # read-only live probes (daemon, artifacts, event logging)
  368. 1688 doctor --profile acc-a # check a specific profile
  369. ```
  370. ### Login — options
  371. ```bash
  372. 1688 login # scan QR, auto-start daemon
  373. 1688 login --timeout 300 # wait up to 5 minutes for QR scan
  374. 1688 login --no-daemon # login without auto-starting daemon
  375. 1688 login --headed # open real browser window instead of terminal QR
  376. 1688 login --force # re-login even if session already exists
  377. ```
  378. ### Output shape principles
  379. - **Normal search** (no `--deeppro`): returns `{ offers: Offer[] }` — behaviour unchanged.
  380. - **Single offer**: returns one `OfferResult` — original shape preserved.
  381. - **Batch offer**: returns `{ mode: "batch", offers: OfferResult[], failures: OfferFailure[] }`.
  382. - **Search `--deeppro`**: returns normal `offers[]` + `deeppro: { offers: OfferResult[], failures: DeepProFailure[] }`.
  383. - **Progress** lines are written to `stderr`; **JSON** output is written to `stdout`.
  384. ---
  385. ## FAQ
  386. ### Compared to alternatives
  387. #### How does 1688-cli compare to MCP servers and Selenium scripts?
  388. 1688-cli runs as a regular shell command, not an MCP server. Agents call it
  389. via `child_process` or shell pipes instead of the MCP protocol — easier to
  390. compose with `jq`, `xargs`, and CI scripts. Compared to writing low-level
  391. browser automation directly, 1688-cli ships with structured JSON output,
  392. session persistence, and a daemon for warm context, so you don't reinvent
  393. that per project.
  394. #### Does 1688 have an official API I should use instead?
  395. Alibaba offers a 1688 Open API at `open.1688.com`, but it's gated to
  396. enterprise ISV partners with a sales contract and per-app authorization.
  397. Individual buyers, small businesses, and AI agents typically can't get
  398. access. 1688-cli uses your normal logged-in buyer account via a one-time
  399. QR scan, mirroring what you can do manually in a browser — no developer
  400. keys required.
  401. ### Account & verification
  402. #### Does this tool require any 1688 developer account or API keys?
  403. No. Login is a one-time QR scan with your normal 1688 mobile app — the
  404. same flow as logging into 1688 on a fresh browser. The default session is
  405. stored in your local profile (`~/.1688/profiles/default/`) and reused across
  406. commands, so you only re-scan when 1688 invalidates it. Named profiles use
  407. their own directories under `~/.1688/profiles/<name>/`.
  408. #### What happens if 1688 shows a verification challenge (滑块)?
  409. 1688 occasionally shows a slider verification on unfamiliar sessions or
  410. after long inactivity — the same one you'd see when logging in from a new
  411. device manually. If a command fails because of this, run it once with
  412. `--headed` (e.g. `1688 search 雨伞 --headed`); a real window opens, you
  413. drag the slider yourself, and the verified session is reused for
  414. subsequent commands. There is no automated solver — it's the same manual
  415. step a person would take.
  416. #### Is it safe to use? Will my account get rate-limited?
  417. The tool drives your own logged-in browser session and only performs
  418. actions you'd do manually — search, read order details, send chat
  419. messages, place an order you confirmed. Use it at human pace (the default
  420. `--watch` interval is 30 seconds, minimum 10) for one of your own
  421. accounts. Aggressive automation, high-frequency scraping, or running it
  422. across many accounts is outside the tool's design and increases the
  423. chance of triggering 1688's risk controls.
  424. ---
  425. ## JSON for agents
  426. Every command auto-switches to JSON when stdout is piped:
  427. ```bash
  428. 1688 order list --status waitsellersend | jq '.orders[] | {id: .orderId, paid: .paidAt}'
  429. 1688 fake-shipped --debug | jq '.orders[].orderId'
  430. 1688 search 雨伞 | jq '.offers[0:5]'
  431. 1688 supplier search 键盘 | jq '.items[0] | {company: .supplier.companyName, memberId: .supplier.memberId, score}'
  432. 1688 supplier research 键盘 --enrich top:1 | jq '{source,total,enrichedCount,first: .items[0].supplier.companyName}'
  433. ```
  434. Supplier-search JSON explicitly carries source provenance:
  435. ```json
  436. {
  437. "source": {
  438. "kind": "company-search",
  439. "endpoint": "companySearchBusinessService",
  440. "offerAggregation": false
  441. }
  442. }
  443. ```
  444. ### Built-in JSON flags (no `jq` required)
  445. Every command supports four output-shaping flags. Useful on Windows or any
  446. environment where `jq` isn't installed — and for agents that want concise
  447. output without parsing the full payload.
  448. ```bash
  449. 1688 offer <id> --json # force JSON even in a TTY
  450. 1688 offer <id> --json --pretty # JSON with 2-space indent
  451. 1688 offer <id> --get supplier.name # one scalar field, raw line
  452. 1688 offer <id> --get supplier # sub-object as JSON
  453. 1688 offer <id> --get 'skus[0].skuId' # array index
  454. 1688 offer <id> --get 'skus[*].price' # wildcard — one line per element
  455. 1688 offer <id> --pick price,supplier.name,'skus[0].skuId'
  456. # {"price":1.25,"supplier.name":"...","skus[0].skuId":"..."}
  457. ```
  458. Path syntax: `field.sub`, `arr[N].field`, `arr[*].field`. Wildcards stream
  459. one line per element; scalars print as a raw line (no quotes), objects and
  460. arrays as JSON. The full payload still goes through when no `--get`/`--pick`
  461. is given, so existing `| jq` pipelines keep working unchanged.
  462. Force JSON in a TTY (alternative to `--json`):
  463. ```bash
  464. BB1688_JSON=1 1688 doctor
  465. ```
  466. PowerShell:
  467. ```powershell
  468. $env:BB1688_JSON = "1"
  469. 1688 doctor
  470. Remove-Item Env:\BB1688_JSON
  471. ```
  472. ### Windows / PowerShell examples
  473. The npm `1688` shim works from PowerShell and cmd.exe. Prefer built-in
  474. `--get` / `--pick` when `jq` is not installed:
  475. ```powershell
  476. 1688 offer 628196518518 --get supplier.name
  477. 1688 supplier search 键盘 --pick total,source.kind,'items[0].supplier.companyName'
  478. 1688 supplier research 键盘 --csv --output "$env:TEMP\suppliers.csv"
  479. ```
  480. Daemon management is the same command surface:
  481. ```powershell
  482. 1688 daemon start
  483. 1688 daemon status --json
  484. 1688 daemon stop
  485. 1688 daemon start --profile acc-a
  486. 1688 daemon status --profile acc-a --json
  487. 1688 daemon stop --profile acc-a
  488. ```
  489. ---
  490. ## Risk control
  491. If 1688 shows a slider verification (滑块), solve it once with `--headed`:
  492. ```bash
  493. 1688 search 雨伞 --headed # window opens; drag the slider yourself
  494. 1688 supplier search 键盘 --headed
  495. 1688 search 雨伞 # subsequent calls reuse the verified session
  496. ```
  497. See also the FAQ entry on [verification challenges](#what-happens-if-1688-shows-a-verification-challenge-滑块).
  498. ---
  499. ## Files & directories
  500. ```
  501. ~/.1688/profiles/default/ Chromium profile (macOS/Linux)
  502. ~/.1688/state.json cached identity (macOS/Linux)
  503. ~/.1688/daemon.sock daemon Unix socket (macOS/Linux)
  504. ~/.1688/daemon.pid daemon PID
  505. ~/.1688/.lock proper-lockfile (one process at a time)
  506. ~/.1688/profiles/<name>/state.json named-profile cached identity
  507. ~/.1688/profiles/<name>/daemon.sock named-profile daemon Unix socket
  508. ~/.1688/profiles/<name>/daemon.pid named-profile daemon PID
  509. ~/.1688/profiles/<name>/.lock named-profile lock
  510. %USERPROFILE%\.1688\profiles\default\ Chromium profile (Windows)
  511. %USERPROFILE%\.1688\state.json cached identity (Windows)
  512. \\.\pipe\1688-cli-daemon-<hash> daemon named pipe (Windows)
  513. \\.\pipe\1688-cli-daemon-<hash>-<hash> named-profile daemon pipe (Windows)
  514. ```
  515. ## Environment variables
  516. ```
  517. BB1688_NO_DAEMON=1 disable daemon, always run inline
  518. BB1688_JSON=1 force JSON output on TTY
  519. BB1688_DEBUG=1 verbose internal logs to stderr
  520. BB1688_FORCE_CHROMIUM=1 skip system Chrome, use bundled Chromium
  521. BB1688_HOME=<path> override ~/.1688 or %USERPROFILE%\.1688
  522. BB1688_SKIP_POSTINSTALL=1 skip Chromium download during npm install
  523. PLAYWRIGHT_DOWNLOAD_HOST custom Playwright mirror
  524. ```
  525. ---
  526. ## Status
  527. Pre-1.0 — the surface is shaped but minor breaks are possible between minor
  528. versions until 1.0. See [CHANGELOG.md](./CHANGELOG.md). Not affiliated with
  529. Alibaba / 1688.
  530. ## Agent contract
  531. If you're driving `1688-cli` from Codex, Claude Code, or another autonomous
  532. agent, read [AGENTS.md](./AGENTS.md) — it documents JSON shapes, exit codes,
  533. and the rules around the write commands.
  534. ## License
  535. [MIT](./LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.