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；同一 业务操作重试时复用同一键和同一请求体。

cat <<'JSON' | pulsewise --output json strategy create --file - \
  --idempotency-key agent-run-0001
{
  "name": "Diversified risk parity",
  "strategy_definition_code": "ETF_MOMENTUM",
  "config": {
    "mode": "PROFESSIONAL",
    "absolute_momentum_benchmark_id": 201,
    "lookback_days": 120,
    "skip_days": 5,
    "holding_count": 2,
    "rebalance_frequency": "MONTHLY",
    "transaction_cost_rate": "0.0010",
    "backtest_start_date": "2025-01-01",
    "correlation_filter": {
      "lookback_days": 120,
      "maximum_correlation": "0.80"
    },
    "weighting_method": "RISK_PARITY",
    "weighting_lookback_days": 120,
    "shortfall_destination": "CASH"
  },
  "instrument_ids": [101, 102, 103]
}
JSON

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

组合相关性

相关性分析需要 API Key 具备 market:read 权限。表格模式展示分析区间和超过阈值 的 ETF 对；JSON 模式原样保留矩阵、全部配对、共同观测数和算法版本。

printf '%s\n' '{"instrument_ids":[101,102,103],"lookback_days":120,"maximum_correlation":"0.80"}' \
  | pulsewise --output table portfolio correlation --file -

pulsewise --output json portfolio correlation --file correlation.json \
  > correlation-result.json

相关性来自历史前复权日收益率，可能随时间变化，不代表未来风险或收益。创建策略时 无需根据分析结果自行删除候选，服务端会按专业策略配置执行相关性过滤。

回测等待

创建回测后可在有界时间内轮询。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 portfolio --help
pulsewise strategy --help
pulsewise strategy version --help
pulsewise backtest --help
pulsewise signal --help
pulsewise tracking --help
pulsewise strategy create --help
pulsewise portfolio correlation --help
pulsewise backtest wait --help

完整命令入口：

分组	命令
认证	auth check
ETF 与因子	instrument list、instrument get、instrument bars、instrument factors、factor list
组合分析	portfolio correlation
策略	strategy definitions、strategy list、strategy get、strategy create、strategy rename、strategy delete
策略版本	strategy version list、strategy version get、strategy version create、strategy activate、strategy pause
回测	backtest list、backtest create、backtest get、backtest wait、backtest series、backtest trades、backtest overview、backtest annual、backtest monthly、backtest daily、backtest allocations、backtest holding-periods、backtest rebalance-events
信号	signal list、signal get
运行跟踪	tracking overview、tracking series、tracking annual、tracking monthly、tracking daily、tracking holdings、tracking holding-intervals、tracking rebalances

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 或完整环境。

稳定退出码：

退出码	含义
0	成功
2	参数或本地输入错误
3	认证失败
4	权限不足
5	资源不存在
6	业务或幂等冲突
7	服务端校验失败
8	限流
9	网络、TLS、超时或服务不可用
10	回测失败或等待超时
1	未分类错误

密钥安全

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