Pulsewise CLI

pulsewise-cli 是 Pulsewise 开放 API 的官方命令行客户端。它封装认证、分页、 错误处理和异步回测轮询，但不改变 API 的权限、限流、幂等、资源归属或风险边界。

安装

需要 Python 3.12 和 uv。

从仓库根目录独立安装：

uv tool install ./cli
pulsewise --version
pulsewise --help

发布到包索引后可使用发行名称安装和升级：

uv tool install pulsewise-cli
uv tool upgrade pulsewise-cli
uv tool uninstall pulsewise-cli

更新本地源码安装：

uv tool install --reinstall ./cli

CLI 是独立包，不会导入 Pulsewise 后端，也不需要数据库或 Redis 配置。

API Key 与配置

登录 Pulsewise 后进入“账户设置 -> 开放 API”，为当前工作流创建独立、短期且 最小权限的 API Key。完整密钥只展示一次，使用环境变量传入：

export PULSEWISE_API_KEY="<从 Secret 管理器读取>"
export PULSEWISE_BASE_URL="https://pulsewise.top"
pulsewise auth check

默认 Base URL 是 https://pulsewise.top，业务接口前缀是 /api/open/v1。 全局配置优先级为命令参数、环境变量、XDG 配置文件、内置默认值：

# ~/.config/pulsewise/config.toml
[pulsewise]
base_url = "https://pulsewise.top"
timeout = 30
output = "table"

配置文件只允许 base_url、timeout 和 output，不得保存 API Key。可用全局 参数为 --base-url、--timeout、--output table|json、--no-color 和 --verbose；对应环境变量包括 PULSEWISE_BASE_URL、PULSEWISE_TIMEOUT、 PULSEWISE_OUTPUT、PULSEWISE_NO_COLOR、PULSEWISE_VERBOSE。

输出

交互终端默认显示 Rich 表格或详情：

pulsewise instrument list --scope recommended --page-size 20
pulsewise instrument get 101

Agent、Skill、脚本和管道应显式选择 JSON。stdout 只包含一个 JSON 文档，诊断和 结构化错误写入 stderr：

pulsewise --output json auth check
pulsewise --output json instrument list --scope recommended --all > etfs.json
jq '.items[] | {id, symbol, name}' etfs.json

非 TTY 且没有显式设置输出格式时也默认 JSON。自动化仍建议显式传入 --output json，避免执行环境变化影响契约。

常用工作流

分页和市场数据

--page 从 1 开始，--page-size 最大为 100。instrument list --all 会按稳定 顺序读取并聚合所有页面，不能与非第一页的 --page 同时使用。

pulsewise --output json instrument list --scope recommended --all
pulsewise --output json instrument bars 101 --start-date 2026-01-01 --end-date 2026-06-30
pulsewise --output json instrument factors 101 --codes momentum_20d,momentum_60d
pulsewise --output json factor list

stdin、幂等与确认

复杂写请求通过 UTF-8 JSON 文件或 --file - 的 stdin 传入。需要幂等保护的写 操作必须显式提供 8-128 个可打印 ASCII 字符组成的 --idempotency-key；同一 业务操作重试时复用同一键和同一请求体。

printf '%s\n' '{"name":"Agent strategy","strategy_definition_code":"ETF_MOMENTUM","config":{"lookback_days":120,"skip_days":5,"holding_count":1,"rebalance_frequency":"MONTHLY","transaction_cost_rate":"0.001","backtest_start_date":"2025-01-01"},"instrument_ids":[101,102]}' \
  | pulsewise --output json strategy create --file - --idempotency-key agent-run-0001

pulsewise --output json strategy version create 42 --file version.json \
  --idempotency-key agent-run-0002
pulsewise --output json strategy activate 42 --version-id 7 \
  --idempotency-key agent-run-0003

删除策略和暂停策略在交互终端要求确认。非交互调用不会等待输入，必须显式使用 --yes：

pulsewise --output json strategy pause 42 --yes
pulsewise --output json strategy delete 42 --yes

回测等待

创建回测后可在有界时间内轮询。JSON 模式只在终态输出一次；回测失败或超时返回 退出码 10。

pulsewise --output json backtest create 42 --file backtest.json \
  --idempotency-key agent-run-0004
pulsewise --output json backtest wait 9001 --interval 2 --wait-timeout 300

命令与帮助

根帮助列出全局参数和所有命令组，每个命令组及叶子命令都支持 --help：

pulsewise --help
pulsewise auth --help
pulsewise instrument --help
pulsewise factor --help
pulsewise strategy --help
pulsewise strategy version --help
pulsewise backtest --help
pulsewise signal --help
pulsewise tracking --help
pulsewise strategy create --help
pulsewise backtest wait --help

完整命令入口：

Agent 与 Skill 调用约定

1. 通过进程环境或 Secret 管理器注入 PULSEWISE_API_KEY，不要把密钥放在命令参数中。
2. 始终显式使用 --output json，只将 stdout 作为业务 JSON 解析。
3. 检查进程退出码；stderr 是错误或诊断通道，不要与 stdout 合并后解析。
4. 非交互危险操作显式使用 --yes，写操作复用调用方可追踪的幂等键。
5. 为分页读取选择明确的 --page/--page-size，或对 ETF 列表使用 --all。
6. 回测使用 backtest wait 并设置符合任务预算的 --wait-timeout。
7. 可记录非敏感的 request_id 用于排障，不记录 Authorization、请求 Secret 或完整环境。

稳定退出码：

密钥安全

• 每个 Agent、Skill 和环境使用独立、最小权限、短有效期的 API Key。
• API Key 不得写入 Skill 文件、提示词、源码、配置文件、测试快照、日志或错误上报。
• 不要在命令行直接赋值密钥，以免进入 Shell 历史或进程列表。
• 不要把密钥放入 URL、stdin JSON、幂等键或 --verbose 相关诊断。
• 生产与测试不得共用密钥。工作流结束、人员变化或疑似泄露时立即撤销并轮换。
• 只通过 HTTPS 连接可信 Base URL；排障时仅保留状态码、错误 code 和 request_id。