跳转至

CLI 参考

xq 是 xiangqin 的客户端。装好跑 xq --help 看完整子命令。

全局选项

xq --help
xq --version
xq --endpoint <URL>       # 覆盖默认服务端（或 XIANGQIN_ENDPOINT 环境变量）

默认 endpoint：http://112.124.27.213（0.1 期生产）。session 里记住的 endpoint 优先。

基础

xq health

健康检查。

xq health
# → {"status":"ok","version":"0.3.1"}

认证

xq register <phone>

发送注册 / 登录验证码。返回 request_id（ULID）。60s 内重复发同号不重复扣码（返回原 request_id）。

xq register 13800001111

xq verify <code> --request-id <ULID>

换 session。session 写 ~/.xiangqin/session.json（权限 600）。

xq verify 123456 --request-id 01JF...

xq logout

删本机 session + 服务端 session 行。

xq me

查当前登录态。

Profile

xq profile show

xq profile set <field> <value>

字段：gender / age / city / tags / bio

  • age 必须 18-99
  • city ≤30 字
  • tags 逗号分隔（xq profile set tags 程序,登山,做饭）
  • bio ≤500 字

xq profile clear <tags|bio>

只允许清可空字段。gender / age / city 必填，不让清。

Query

xq query <WHERE> [--limit N] [--json]

xq query 'gender=f AND city=hangzhou AND age>=25'
xq query 'tags CONTAINS 登山' --limit 20
xq query 'gender IN (f,nb)' --json

Exposure（曝光）

xq expose buy --count N [--mock]

xq expose buy --count 100          # 真付（支付宝扫码）
xq expose buy --count 100 --mock   # 服务端 provider=mock 时必带

真付返回二维码 URL + 终端 ASCII 二维码；支付宝扫码付款后 webhook 回来自动充值。

xq expose balance

xq expose balance
# → 剩余曝光次数: 87
#   历史总买   : 500

xq expose history [--limit N]

xq expose history --limit 20
# 2026-04-22 15:30  [真付]  100 次曝光  ¥10.00  01JF...

退出码

码 含义
0 成功
1 任意错误（网络 / 业务 / 鉴权失败）

错误分类靠 stderr 消息文本：

  • 未登录 → 过了 session 有效期
  • register failed: 429 → rate limited
  • verify failed: 400 → 验证码错 / 过期
  • query failed: 400 → DSL 不合规
  • buy failed: 400 → count 超限