Metadata-Version: 2.5
Name: pulsewise-cli
Version: 0.1.3
Summary: Official command-line client for the Pulsewise Open API
Requires-Python: <3.13,>=3.12
Requires-Dist: httpx<1.0.0,>=0.28.0
Requires-Dist: rich<15.0.0,>=14.0.0
Requires-Dist: typer<1.0.0,>=0.16.0
Description-Content-Type: text/markdown

# Pulsewise CLI

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

## 安装

需要 Python 3.12 和 [uv](https://docs.astral.sh/uv/)。

从仓库根目录独立安装：

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

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

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

更新本地源码安装：

```bash
uv tool install --reinstall ./cli
```

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

## API Key 与配置

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

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

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

```toml
# ~/.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 表格或详情：

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

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

```bash
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` 同时使用。

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

```bash
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`：

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

### 组合相关性

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

```bash
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`。

```bash
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`：

```bash
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`。
