@onebullex-group/cli

OneBullEx Open API V2 的命令行工具。

当前版本（1.1.0）覆盖 V2 文档的全部 60 个端点：22 个公开 + 18 个私有只读 + 20 个写。所有写命令默认 dry-run，需 --confirm 才真发请求。

安装

npm i -g @onebullex-group/cli

或本地构建：

cd cli
pnpm install
pnpm build
pnpm link --global

校验：

onebullex --version
onebullex public time --base-url https://futures-openapi.1bullex.com

Quick Start

# 1. 初始化一个 profile（向导式）
onebullex config init

# 2. 看下当前 profile 配置（敏感字段已脱敏）
onebullex config show

# 3. 跑公开接口验证联通性
onebullex public time
onebullex symbol list

# 4. 跑私有只读接口（需要在 config init 时填了 api-key/secret）
onebullex balance list
onebullex position list

命令分组

完整命令列表跟 V2 文档逐项对齐，可用 onebullex <group> --help 查询。

公开（22）

public time                    GET /v2/public/time
symbol  list / get / coins / all
ticker  get / list / agg / agg-list
depth   get
deal    list
kline   list
mark-price  list / get
index-price list / get*       (* index-price get 需要认证)
funding rate / history
risk-balance list
open-interest get
leverage brackets-list / brackets-get

私有只读（18）

listen-key get
balance list / get / bills
order list-unfinished / list-unfinished-multi / list / list-by-ids /
      list-history / get / trades
entrust plan-list / plan-history / plan-get / profit-list / profit-get
order-entrust list
position list

写操作（20）

所有写命令默认 dry-run：仅打印预览不发请求。加 --confirm 才会真正下单/撤单/改仓。

order create / create-batch / cancel / cancel-batch / cancel-all
entrust create-plan / create-profit /
        cancel-plan / cancel-profit / update-profit /
        cancel-all-plan / cancel-all-profit
order-entrust cancel / cancel-all
position adjust-leverage / margin / auto-margin /
         close-all / merge / change-type

例：

# dry-run（默认，退出码 4，preview 在 stdout）
onebullex order create --symbol btc_usdt --order-type LIMIT \
  --order-side BUY --position-side LONG --orig-qty 0.001 --price 50000

# 真正下单
onebullex order create --symbol btc_usdt --order-type LIMIT \
  --order-side BUY --position-side LONG --orig-qty 0.001 --price 50000 \
  --confirm

CLI flag 用 kebab-case，会映射到 API 的 camelCase 字段（如 --order-side → orderSide）。批量类（create-batch / cancel-batch）的 --list / --order-ids 接受 JSON 字符串数组。

配置管理（6）

config init           交互式向导
config set <key>      仅 base-url / identify / env 可用 --value
                      api-key / secret 必须用 --stdin
config show           [--reveal] 默认脱敏，加 --reveal 后明文（带 stderr 警告）
config use <profile>  切换默认 profile
config list-profiles  表格列出全部 profile
config remove <p>     删除 profile（防止删掉最后一个）

配置文件

默认路径 ~/.onebullex/config.json，权限 0600（非 Windows 上自动校正）。

{
  "version": 1,
  "default-profile": "test",
  "profiles": {
    "test": {
      "base-url": "https://futures-openapi.1bullex.com",
      "api-key": "AK...",
      "secret": "...",
      "identify": null,
      "env": "test"
    }
  }
}

可通过 ONEBULLEX_CONFIG_PATH 环境变量覆盖路径（脚本/CI 友好）。

优先级与全局 flag

每次调用按以下顺序解析：

CLI flag > 环境变量 > 配置文件 profile > 报错（要求 config init）

| 全局 flag | 环境变量 | 说明 | |---|---|---| | --profile <name> | ONEBULLEX_PROFILE | 临时切换 profile | | --api-key <key> | ONEBULLEX_API_KEY | 覆盖 api key | | --secret <s> | ONEBULLEX_SECRET | 覆盖 secret（不建议 CLI 上明文） | | --base-url <url> | ONEBULLEX_BASE_URL | 覆盖 base URL | | --output <fmt> | — | table / json，TTY 默认 table，否则 json | | --debug | ONEBULLEX_DEBUG=1 | 把请求/响应（脱敏后）写到 stderr | | --timeout <ms> | — | HTTP 超时，默认 10s | | --confirm | — | Phase 2 写命令使用，未传时走 dry-run |

安全

• secret 与 api-key 明文落盘在 config.json，权限收紧到 0600
• config set api-key / config set secret 拒绝 --value，强制 --stdin，防止 shell history 泄漏
• config show 默认脱敏（AK****1234 / ****），仅 --reveal 时明文并带 stderr 警告
• --debug 输出会通过 redact 过滤掉 X-Signature / X-API-KEY / Authorization / secret 字段
• 每次调用都会校验 ~/.onebullex/config.json 的 mode（非 win32），不是 0600 时打 warn 并自动修复

输出格式

• TTY 下默认表格（cli-table3），列名取并集，时间戳列自动渲染成 YYYY-MM-DD HH:mm:ss
• 非 TTY（管道、重定向、CI）默认 JSON，jq 友好
• 任意时候用 --output json 强制 JSON，--output table 强制表格

防漂移 lint

pnpm check-coverage 跑三层校验：

1. 端点级：把 docs/onebullex-openapi-cn-v2.md 里的所有 #### GET/POST /v2/* 标题与 cli/src/registry.ts 对账，缺/多就 fail
2. 参数级：用 ts-morph 解析每个命令文件，提取 commander 的 command() / requiredOption() / option()，与文档参数表的 必填 列对账
3. 写守门：方法是 GET 但 isWrite=true，或者 method 是 POST 但 isWrite=false（/v2/order/list-by-ids 是已知例外）

CI 上当文档新增一个端点时，coverage 检查会立刻 fail，强制开发者补一个新命令。

开发

cd cli
pnpm install
pnpm dev <command>      # 直接跑 src/index.ts，无需先 build
pnpm test               # 跑全部单测/集成测
pnpm typecheck          # tsc --noEmit
pnpm lint               # biome
pnpm check-coverage     # 防漂移 lint
pnpm build              # 产出 dist/index.js

跑 testnet e2e

只读 e2e（默认跳过）只验证公开接口连通性：

ONEBULLEX_E2E=1 pnpm vitest run tests/e2e/public.e2e.test.ts

写 e2e（默认跳过）会真发请求到 testnet：下/撤远价限价单、改杠杆、改持仓模式、用 MARKET 单开仓 → 加保证金 → 创建止盈止损 → close-all。需要测试网账户和 ≥ 50 USDT 余额：

ONEBULLEX_E2E=1 \
ONEBULLEX_E2E_API_KEY=<testnet-key> \
ONEBULLEX_E2E_SECRET=<testnet-secret> \
pnpm vitest run tests/e2e/write.e2e.test.ts

按业务流程组织成 4 个 block，串行执行：configuration chain → limit order chain → plan + order-entrust chain → position + profit chain。每个 block 末尾有 best-effort cancel-all / close-all，跑挂时也尽量不留挂单/持仓残留。

Nightly CI（可选）

cli/.gitlab-ci.yml 里有一个 cli-e2e-nightly job，仅在 schedule 触发时跑（$CI_PIPELINE_SOURCE == "schedule"），跑完整 tests/e2e/ 套件。开启方式：

1. 在 GitLab project Settings → CI/CD → Variables 添加 masked + protected 变量：
   • ONEBULLEX_E2E_API_KEY = testnet API key
   • ONEBULLEX_E2E_SECRET = testnet API secret
2. Build → Pipeline schedules → New schedule，cron 设成例如 0 19 * * *（每日 03:00 UTC+8），target branch 选 main。

job 标 allow_failure: true 且 retry 一次——testnet 偶发抖动不会阻塞调度。变量没配时只有 public e2e 跑，写 e2e 自动 skip（HAS_AUTH 门控）。

与 Java SDK 的关系

签名实现严格对齐 src/main/java/com/onebullex/api/common/SignatureUtilsV2.java：

• timestamp 秒级（10 位）
• nonce 是 UUID v4 去横线（32 位 hex 小写）
• query string 按 key 字典序排序，不做 URL 编码
• HMAC-SHA256，输出 hex 小写

Java 端通过 SignatureVectorGenTest 生成 cli/tests/fixtures/signature-vectors.json，CLI 端 signature-parity.test.ts 把 7 条向量逐条对照 Java 输出，保证字节级一致。

License

MIT