The free, offline, agent-native 1688 wholesale sourcing CLI — keyword search with the signals the web UI buries (回头率 reorder rate, factory-verified status, supplier trade scores, price drift), persisted to a local store no scraper tracks over time.
Search 1688.com's China-domestic wholesale catalog and get structured offers (tiered price, MOQ, supplier, region, transaction volume) for free, with no paid scraper API and no API key. Every search persists to a local SQLite store, so drift shows how prices and reorder rates moved since last week, factory-find ranks real manufacturers above resellers, and supplier-report rolls up a shop's full reliability footprint. Read-only sourcing research.
Quick Start
# health check; confirms the mtop endpoint is reachable, no key needed
1688-pp-cli doctor --dry-run
# live wholesale search (translate English terms to Chinese first for rich results)
1688-pp-cli search 手机壳 --limit 10
# persist the result set into the local store to build drift history
1688-pp-cli sync 手机壳
# rank likely real factories above resellers
1688-pp-cli factory-find 手机壳 --top 10
# after a later sync, see which offers moved on price or reorder rate
1688-pp-cli drift 手机壳
Unique Features
These capabilities aren't available in any other tool for this API.
Sourcing signals competitors don't rank
-
factory-find — Rank wholesale offers by how likely the seller is the real factory, not a reseller, and label each trader / likely-factory / verified-factory.
Reach for this when an agent must pick a manufacturer over a middleman among dozens of near-identical listings.
1688-pp-cli factory-find 蓝牙耳机 --top 10 --json
-
repurchase-top — Rank synced offers and suppliers by 回头率 (buyer reorder rate), with a minimum-transaction floor to suppress low-volume noise.
Use it to surface suppliers buyers actually come back to, instead of trusting a one-off star rating.
1688-pp-cli repurchase-top 手机壳 --min-tx 100 --json
-
region-spread — Group stored offers for a keyword by Chinese province and report min, median, and max price plus transaction count per region.
Reach for this to spot whether a product is meaningfully cheaper out of one manufacturing cluster before narrowing suppliers.
1688-pp-cli region-spread 手机壳 --json
Local state that compounds
-
drift — Show how an offer's price, reorder rate, and 30-day transaction count moved across your stored snapshots.
Reach for this before a reorder to see whether a 'limited-time' price actually dropped or a supplier's reliability is trending down.
1688-pp-cli drift 手机壳 --json
-
compare — Render a side-by-side table of price, MOQ, tier, reorder rate, transactions, factory flags, and trade scores for several offers of the same product.
Use it to make the final buy decision between a handful of shortlisted suppliers in one view.
1688-pp-cli compare 927875250705 836112681124 --json
-
supplier-report — Aggregate one shop across all its stored offers: trade-service scores, average reorder rate, total transactions, verification badges, offer count, and price range.
Reach for this to vet or audit a supplier before committing volume, instead of judging from one listing.
1688-pp-cli supplier-report b2b-2850655109d72ea --json
-
watch — Re-run a saved search, store a fresh snapshot, and print only what changed since last run: price and reorder-rate moves plus newly appeared offers and suppliers.
Use it on a schedule to catch new entrants and price moves in a category without re-reading the whole result set.
1688-pp-cli watch 手机壳 --json
Recipes
Find verified factories for a product
1688-pp-cli factory-find 蓝牙耳机 --top 10 --json
Ranks likely manufacturers above traders using factory flags, reorder rate, and trade scores.
Narrow a verbose search payload for an agent
1688-pp-cli search 手机壳 --agent --select offers.title,offers.price_cny,offers.repurchase_rate,offers.supplier_name
Search responses are large and nested; --select pulls only the fields an agent needs so it does not burn context.
Compare shortlisted suppliers head to head
1688-pp-cli compare 927875250705 836112681124 --json
Side-by-side price/MOQ/reorder/factory signals for specific offers you already synced.
Check price and reorder-rate drift before a reorder
1688-pp-cli drift 手机壳 --json
Diffs the latest stored snapshot against prior ones so you see real movement, not marketing 'limited-time' labels.
Rank suppliers by buyer reorder rate
1688-pp-cli repurchase-top 手机壳 --min-tx 100 --json
Surfaces shops buyers actually come back to, ignoring low-volume noise.
Usage
Run 1688-pp-cli --help for the full command reference and flag list.
Commands
offers
Inspect 1688 wholesale offer detail pages
1688-pp-cli offers <offer_id> - Fetch a 1688 offer's public detail page by offer ID
Output Formats
# Human-readable table (default in terminal, JSON when piped)
1688-pp-cli offers mock-value
# JSON for scripting and agents
1688-pp-cli offers mock-value --json
# Filter to specific fields
1688-pp-cli offers mock-value --json --select id,name,status
# Dry run — show the request without sending
1688-pp-cli offers mock-value --dry-run
# Agent mode — JSON + compact + no prompts in one flag
1688-pp-cli offers mock-value --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Read-only by default - this CLI does not create, update, delete, publish, send, or mutate remote resources
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 5 API error, 7 rate limited, 10 config error.
Health Check
1688-pp-cli doctor
Verifies configuration and connectivity to the API.
Configuration
Config file: ~/.config/1688-pp-cli/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Troubleshooting
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- search returns very few or zero results for an English keyword — 1688's corpus is Mandarin; translate the term to Simplified Chinese (e.g. 'phone case' -> 手机壳) and retry
- FAIL_SYS_TOKEN_EMPTY or FAIL_SYS_TOKEN_EXPIRED from the API — the signed-request token expired; the client re-bootstraps automatically on the next call, so just retry once
- requests blocked or punished (action=deny) from a cloud/CI host — Alibaba blocks data-center IPs (cloud_ip_bl); run from a residential IP or a residential proxy, not a cloud egress
- a transcendence command returns an empty result — run 'sync ' first to populate the local store; drift/compare/region-spread read stored data, not the live API
Sources & Inspiration
This CLI was built by studying these projects and resources:
Generated by CLI Printing Press