内容
# oura-toolkit
你的 [Oura Ring](https://ouraring.com) 数据，无处不在：一个快速的Rust命令行工具（`oura`），一个用于AI助手的本地 [MCP](https://modelcontextprotocol.io) 服务器，一个带有健康技能的Claude插件，以及六种语言（Rust、TypeScript、Python、Go、Java和C#）生成的SDK客户端——所有这些都由Oura自己的OpenAPI规范驱动。
```
$ oura sleep
日期 分数 深度 休息 效率
2026-06-27 82 70 85 93
2026-06-28 77 64 79 90
...
$ oura readiness --json | jq '.[0].score'
88
```
- **只读且本地优先**：您的凭证仅发送给Oura，从不发送给任何第三方。
- **自带Oura应用**：使用*您自己的*客户端ID/密钥（Oura已在2025年12月废弃个人访问令牌）。引导注册大约需要2分钟。
- **可脚本化**：稳定的退出代码，管道TSV， `--json` ——参见 [CLI合约](docs/cli-contract.md)。
📖 **完整文档： [ouratoolkit.com](https://ouratoolkit.com)** ——指南、完整的CLI参考、Oura API v2参考和每种语言的SDK文档，均可搜索。
## 安装
**npx（推荐 —— 无需安装）：**
```sh
npx -y oura-toolkit --help
```
**常规使用的快速路径：**
```sh
brew install spxrogers/tap/oura-toolkit # Homebrew（macOS/Linux）
bun install -g oura-toolkit # Bun
cargo install oura-toolkit-cli # 从源代码安装；安装`oura`二进制文件
```
Shell和PowerShell安装程序随每个 [GitHub发布](https://github.com/spxrogers/oura-toolkit/releases)发布。无论您选择哪种方式，命令都是`oura`（通过npx：`npx -y oura-toolkit <args>`）。
> **预发布说明：** npx / brew / bun路径 — 以及MCP +插件路线（如下所述），它们通过npx启动 — 将在第一个标记版本后激活。在此之前，请从源代码构建：`cargo install --git https://github.com/spxrogers/oura-toolkit oura-toolkit-cli`。
## 一次性设置：注册您的Oura应用并登录
Oura的API使用带有机密客户端的OAuth，因此您需要注册自己的（免费）Oura应用程序，并将凭证保存在您的机器上。CLI将引导您完成整个过程：
```sh
oura auth setup
```
它会依次执行以下操作：
1. 在您的浏览器中打开 <https://cloud.ouraring.com/oauth/applications> 并打印出要填写的确切值：
- **应用程序名称**：任何名称（例如`oura-toolkit`）
- **重定向URI**：`http://localhost:8788/callback` —— 必须完全匹配
- **范围**：`personal daily heartrate workout tag session spo2Daily`
2. 在终端中提示输入应用程序的**客户端ID**和**客户端密钥**（密钥为隐藏输入 —— 它永远不会离开您的机器）。
3. 直接进入`oura auth login`：您的浏览器将打开Oura的同意页面，本地监听器在端口8788上捕获回调，令牌被存储。
已经注册？只需运行`oura auth login`。如果端口8788被占用，请使用 `--port <n>` —— 并注册匹配的重定向URI。在远程或无头主机上，无法通过循环回调到达您（SSH，容器），请添加 `--no-browser`（见下文）。
令牌和凭证存储在 `~/.config/oura-toolkit/`（仅所有者文件模式； 在Windows上， `%LOCALAPPDATA%\oura-toolkit\` 在您的个人资料的私有ACL下）并自动刷新。
随时管理存储的状态：
```sh
oura auth status # 存储内容：客户端ID、范围、令牌过期时间（退出代码4 = 运行设置/登录）
oura auth token # 打印新鲜的访问令牌 —— 用于curl和脚本
oura auth refresh # 强制刷新令牌（持久化旋转的刷新令牌）
oura auth logout # 删除令牌； --all 还删除应用程序凭证
```
### 无头、CI和容器
没有本地浏览器，或者远程盒子OAuth回调无法到达？
- **`oura auth login --no-browser`** （也是 `oura auth setup --no-browser`）—— CLI打印授权URL，您在任何机器上的浏览器中批准它，然后将完整的重定向URL粘贴回终端。相同的`state` CSRF检查适用。SSH会话自动检测并建议 `--no-browser`。
- **`OURA_ACCESS_TOKEN`** —— 一个原始的OAuth访问令牌，数据命令和 `oura mcp` 直接使用，绕过存储（无需登录，无需刷新）。它优先于任何存储的登录；当它过期时，命令会说出来，您可以导出一个新的。（Oura在2025年废弃了个人访问令牌，因此这是短期OAuth令牌 —— 用于CI和一次性代理。 `oura auth …` 帐户命令仍然作用于存储，而不是此变量。）
- **`OURA_API_BASE_URL`** —— 指向客户端的替代Oura主机、代理或模拟器；默认为 `https://api.ouraring.com`。
## CLI
八个数据读取命令：
```sh
oura sleep # 每日睡眠分数 + 贡献者
oura readiness # 每日准备度 + 温度偏差
oura activity # 分数、步数、卡路里
oura stress # 高压力 vs 恢复时间
oura heartrate # 每分钟心率（bpm）时间序列（频繁采样；预计有许多行）
oura sessions # 冥想、午睡、呼吸训练
oura workouts # 带有强度 + 卡路里的训练
oura personal-info # 您的个人资料
```
每个窗口命令都采用 `--start` / `--end` （`today`、`yesterday` 或 `YYYY-MM-DD`，以您的本地时区为准），默认为最近7天 —— 或 `--date <day>` 作为单日简写（`oura sleep --date yesterday`）。自动跟随光标分页。
Oura对每个访问令牌和每个应用程序（滚动窗口 —— 429响应头带有重试指导）限制API速率。当请求受到速率限制时，工具包等待短暂的`Retry-After`时间（最多10秒，最多3次速率限制等待跨一个命令），然后重试；如果API仍然限制流量，则命令失败并显示 `rate limited until <time>` 而不是重试风暴 —— 详情见 [docs/cli-contract.md](docs/cli-contract.md)。
输出根据上下文调整：在终端上为对齐表格，在管道中为稳定的制表符分隔行， `--json` 为漂亮的JSON。退出代码是记录的合约（`0` ok，`1` 运行时错误，`2` 用法错误，`4` 需要身份验证） —— 详情见 [docs/cli-contract.md](docs/cli-contract.md)。
### 原始API访问
需要一个终结点，而精选命令却无法涵盖？ `oura api` 是一个经过身份验证的直通（类似于 `gh api`）：它附加您的存储令牌并将原始JSON响应打印到stdout。
```sh
oura api /v2/usercollection/personal_info # GET（默认）
oura api /v2/usercollection/daily_sleep --paginate # 跟随 next_token，聚合 {"data":[…]}
oura api -f start_date=2026-06-01 /v2/usercollection/daily_sleep # -f → 查询参数在GET上
```
`-X`/`--method` 设置方法（默认GET）； `-f`/`--field key=value` 是可重复的，变为GET/HEAD/DELETE的查询参数或否则为JSON正文对象；可以通过stdin管道输入请求正文。 `--paginate` （仅限GET）跟随 `next_token` 到结尾并发出单个 `{"data":[…]}`。响应原样打印，因此将其通过 `jq` 管道传输。非2xx响应是运行时错误（退出代码1），stderr上显示HTTP状态和正文 —— 包括429（尽管类型化命令不等待速率限制）。
`oura api` 仅附加您的 **Bearer** 令牌，因此它可以访问任何使用它进行身份验证的终结点 —— 即读取（GET）API。 Oura的写入终结点（Webhooks订阅）使用单独的客户端ID/密钥方案， `oura api` 不会发送，因此 `-X` / `-f`-正文 / stdin支持是为了与 `gh api` 保持一致并适用于未来的Bearer认证写入终结点。
### Shell补全和手册页
```sh
oura completion zsh > ~/.zfunc/_oura # 另见：bash、fish、powershell、elvish
oura man > oura.1 # roff 手册页
```
两者都是纯生成器（无需认证，无需网络），输出到stdout —— 将它们重定向到shell或 `man` 期望的位置。 未知shell是用法错误（退出代码2）。
发布存档（ [GitHub发布](https://github.com/spxrogers/oura-toolkit/releases) tarball和Homebrew/shell安装程序）还附带 `oura.1` 和 `bash`/`zsh`/`fish` 补全，因此您不必自己生成它们。 （目前， `brew install` 将它们放在公式的共享目录下，而不是自动加载它们 —— 请在您的shell期望的位置加载文件；自动Homebrew连接作为后续跟踪。）
## MCP服务器（AI助手）
```sh
oura mcp
```
运行一个STDIO MCP服务器，暴露八个精选、描述的工具（`get_daily_sleep`、`get_daily_readiness`等）。 工具结果由您连接的AI助手读取 —— 这就是目的 —— 同时凭证保持本地。 服务器重用相同的存储令牌并静默刷新它们； 如果您尚未登录，工具调用返回一个结构化错误，告诉您运行 `oura auth login` —— 服务器本身从不提示或打开浏览器。 在没有存储登录的容器中，使用注入的令牌启动它： `OURA_ACCESS_TOKEN=<token> oura mcp` （参见 [无头，CI和容器](#无头-ci-和容器)）。
对于Claude Code：
```sh
claude mcp add oura -- npx -y oura-toolkit mcp
```
## Claude插件
内置电池路线 —— MCP服务器加 `/morning-checkin` 和 `/wellness-report` 技能：
/plugin marketplace add spxrogers/oura-toolkit
/plugin install oura-toolkit@oura-toolkit
```
然后问Claude “我昨晚睡得怎么样？”。 有关详细信息，请参见 [plugins/oura-toolkit](plugins/oura-toolkit/)。
## SDK
每个语言在 `sdks/<lang>/` 下的内容相同：一个从Oura的OpenAPI规范（身份验证无关 —— 携带Bearer令牌）生成的平面客户端，加上一个手写的身份验证伴侣（令牌存储 + 刷新）。 目前已有：
| 语言 | 生成的客户端 | 身份验证伴侣 | 包名（保留） |
|---|---|---|---|
| Rust | `sdks/rust/oura-toolkit-api` （CLI在此基础上运行 — 端到端测试） | `oura-toolkit-auth` ✅ | `oura-toolkit-api` / `oura-toolkit-auth` （crates.io） |
| TypeScript | `sdks/typescript/api` | `@oura-toolkit/auth` ✅ | `@oura-toolkit/api` （npm） |
| Python | `sdks/python` （`oura_toolkit.api`） | `oura_toolkit.auth` ✅ | `oura-toolkit` （PyPI） |
| Go | `sdks/go` | `sdks/go/auth` ✅ | 模块 `github.com/spxrogers/oura-toolkit/sdks/go` |
| Java | `sdks/java/api` | `com.ouratoolkit:auth` ✅ | `com.ouratoolkit:api` （Maven Central） |
| C# | `sdks/csharp/api` | `OuraToolkit.Auth` ✅ | `OuraToolkit.Api` （NuGet） |
客户端的广度经过编译检查和CI中的漂移检查，并在Oura的实时沙盒（所有五个：TypeScript、Python、Go、Java和C#）中进行烟雾测试，但 **尚未发布** 到它们的注册表中 —— 目前请从源代码中消费它们。 直到每个语言的身份验证伴侣落地，请提供您自己的访问令牌。
## 开发
一个前提条件：安装 [`just`](https://github.com/casey/just)。 所有其他内容都是一个配方：
```sh
just setup # 工具链 + 代码生成/发布工具
just ci # CI运行的内容：fmt-check + lint + 测试
just docs-dev # 在本地运行文档站点（ouratoolkit.com）
just # 列出所有配方
```
参见 [CONTRIBUTING.md](CONTRIBUTING.md) 了解开发循环， [CLAUDE.md](CLAUDE.md) 了解硬性约束和测试法则（“绿色CI是发布决定”）， [ARCHITECTURE.md](ARCHITECTURE.md) 了解各个部分如何组合， [DECISIONS.md](DECISIONS.md) 了解为什么选择每个锁定选项。
## 许可证
MIT
