Metadata-Version: 2.5
Name: pulsewise-cli
Version: 0.1.2
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
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`：

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

### 回测等待

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

完整命令入口：

| 分组 | 命令 |
| --- | --- |
| 认证 | `auth check` |
| ETF 与因子 | `instrument list`、`instrument get`、`instrument bars`、`instrument factors`、`factor list` |
| 策略 | `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`。
