Skip to main content

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 — --json returns 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.

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 — default or latest
  • --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:

  • keyword
  • title
  • price
  • area
  • seller
  • link
  • image_url
  • publish_time
  • item_id

Notes

  • Avoid large page counts.
  • Avoid frequent live testing.
  • Prefer xianyu login before live runs.
  • Use --dry-run while 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)

Source distribution for xianyu-cli 0.1.0
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)

Table of built distributions (wheels) for xianyu-cli 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page