xianyu-cli
English | 中文
A CLI for Xianyu (闲鱼 / Goofish) — search listings and capture raw search responses with Playwright.
Disclaimer
This project is created and shared purely for personal interest, learning, and technical research.
- It must not be used for commercial purposes, profit-making activities, large-scale scraping, or any unlawful use.
- Any use of this project is at the user's own risk.
- The user is solely responsible for any direct or indirect consequences arising from the use of this project.
- The project author and contributors assume no responsibility or liability for any loss, damage, legal risk, account restriction, or other consequence caused by the use or misuse of this project.
- Technical discussion, learning, and collaborative research are welcome.
Features
- 🔐 Login — browser-assisted login, saved session reuse, login status check, logout
- 🔍 Search — search by keyword, repeated keywords, or keyword file
- 📦 Output formats —
table,json,ndjson,csv - 🧾 Raw API output —
--jsonreturns captured search API payloads - ♻️ Session reuse — automatically uses the saved Playwright storage state when available
- 🧹 CLI-first design — no FastAPI, no database
Installation
# Recommended after publish
pip install xianyu-cli
playwright install chromium
From source:
git clone <your-repo-url>
cd xianyu-cli
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
python -m playwright install chromium
Usage
# ─── Login ────────────────────────────────────────
xianyu login # Open browser and save login state
xianyu login --qrcode # Render QR in terminal and complete login automatically
xianyu login --auto-detect # Auto-save when strong auth cookies appear
xianyu status # Check saved login status
xianyu logout # Remove saved login state
xianyu login --storage-state ./state.json # Save to a custom path
# ─── Search ───────────────────────────────────────
xianyu search "iPhone 15" # Basic search
xianyu search "显卡" --pages 2 # Pagination
xianyu search --keyword 显卡 --keyword 相机
xianyu search --keyword-file keywords.txt
# Structured output
xianyu search "显卡" --format json
xianyu search "显卡" --format ndjson
xianyu search "显卡" --format csv --output result.csv
# Raw search API payloads
xianyu search "显卡" --json
xianyu search "显卡" --json --output raw.json
# Parameter validation only
xianyu search "MacBook" --dry-run --format json
Authentication
Anonymous sessions often return empty or incomplete results on Xianyu. You should usually log in before running live searches.
xianyu login opens a visible Chromium window. Complete the login in the browser, then return to the terminal and press Enter to save.
If you prefer terminal QR login, use:
xianyu login --qrcode
This mode keeps a Playwright browser context running in the background, renders the QR code directly in the terminal, polls the QR status, and saves the login state automatically after confirmation.
The CLI supports three login styles:
- manual confirm: default and recommended, press Enter in the terminal after login
- auto-detect: optional, use
xianyu login --auto-detect - terminal QR login: use
xianyu login --qrcode
Saved login state path by default:
~/.config/xianyu-cli/storage-state.json
Once saved, later xianyu search ... commands automatically reuse that state.
If the browser used to close too early, that was caused by overly loose anonymous-cookie detection. The default login flow is now manual-save, which is more reliable.
Search
Basic search:
xianyu search "iPhone 15"
Multiple keywords:
xianyu search "显卡" "机械键盘" "相机"
xianyu search --keyword 显卡 --keyword 机械键盘 --keyword 相机
xianyu search --keyword-file keywords.txt
Structured output:
xianyu search "显卡" --format json
xianyu search "显卡" --format ndjson
xianyu search "显卡" --format csv --output result.csv
Raw API JSON:
xianyu search "显卡" --json
xianyu search "显卡" --json --output raw.json
Common Options
--pages— pages to fetch per keyword--sort—defaultorlatest--format—table,json,ndjson,csv--json— output raw captured API payloads--output— write results to a file--max-items— limit returned normalized items--storage-state— specify a custom login-state file--headful— run search with a visible browser--min-wait-ms— wait between page actions--navigation-timeout-ms— Playwright timeout--no-dedupe— disable deduplication--compact— disable pretty JSON formatting--dry-run— validate arguments without a live request
Output Fields
Normalized item output currently includes:
keywordtitlepriceareasellerlinkimage_urlpublish_timeitem_id
Notes
- Avoid large page counts.
- Avoid frequent live testing.
- Prefer
xianyu loginbefore live runs. - Use
--dry-runwhile adjusting parameters. - For live verification, start with one keyword and one page.
Metadata
Release files for xianyu-cli 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| xianyu_cli-0.1.0.tar.gz | 18.9 kB | With provenance | Details for xianyu_cli-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| xianyu_cli-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for xianyu_cli-0.1.0-py3-none-any.whl |
Total release size: 36.6 kB
Release files / xianyu_cli-0.1.0.tar.gz
| Download URL | xianyu_cli-0.1.0.tar.gz |
|---|---|
| Size | 18.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
79d054326e6376ed156f2c2611eadfebe23f3f646009c5d82e6d12ea245f92e9
|
|
BLAKE2b-256 checksum How to use checksums |
a9ec3ed63252cabdc27f1b65adea7315a37ad6cf0800fd91054564eeeefa9da5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 25, 2026.
Transparency logRelease files / xianyu_cli-0.1.0-py3-none-any.whl
| Download URL | xianyu_cli-0.1.0-py3-none-any.whl |
|---|---|
| Size | 17.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
55453c370c601ab9343e9f37fe380a43ce8a8cca502eb67b9a0b3ecd597f31e7
|
|
BLAKE2b-256 checksum How to use checksums |
1d7ad0219cb14c831f6b8aa0a6239b93ef031c5641883fffd8c011bc664e1aee
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 25, 2026.
Transparency logSecurity for xianyu-cli 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for xianyu_cli-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 25, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.