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

完整命令入口：

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。