@drakulavich/oura-cli 0.3.2 → 0.3.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +11 -0
- package/README.md +84 -88
- package/dist/index.js +1 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,17 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
|
6
6
|
|
|
7
7
|
## [Unreleased]
|
|
8
8
|
|
|
9
|
+
## [0.3.3] - 2026-05-13
|
|
10
|
+
|
|
11
|
+
### Changed
|
|
12
|
+
- README refocused on the human reader: tagline, bullets, and "First five
|
|
13
|
+
minutes" address terminal users first; automation/agents/MCP content moved
|
|
14
|
+
to a single short section near the end.
|
|
15
|
+
|
|
16
|
+
### Build
|
|
17
|
+
- `release.yml` workflow re-enables `npm publish --provenance` now that the
|
|
18
|
+
repository is public.
|
|
19
|
+
|
|
9
20
|
## [0.3.2] - 2026-05-13
|
|
10
21
|
|
|
11
22
|
### Changed
|
package/README.md
CHANGED
|
@@ -7,106 +7,117 @@
|
|
|
7
7
|
<a href="https://bun.sh"><img src="https://img.shields.io/badge/runtime-Bun-f9f1e1?logo=bun" alt="Bun"></a>
|
|
8
8
|
</p>
|
|
9
9
|
|
|
10
|
-
<p align="center"><b>Own your Oura Ring data.</b>
|
|
10
|
+
<p align="center"><b>Own your Oura Ring data.</b> Pull your sleep, readiness, activity, heart rate, SpO₂, stress, and workouts from the Oura Cloud API straight to your terminal. No mobile app. No telemetry. Just SQLite and your data.</p>
|
|
11
11
|
|
|
12
|
-
- **
|
|
13
|
-
- **
|
|
14
|
-
- **
|
|
15
|
-
- **
|
|
12
|
+
- **Offline-first.** Everything caches into `~/.oura-cli/oura.db` after one `oura-cli sync`. Reports keep working when your internet doesn't.
|
|
13
|
+
- **Real terminal reports.** `oura-cli report` writes a weekly or monthly digest with averages, trend deltas, and "you slept poorly Tuesday" callouts. No dashboards, no logging in.
|
|
14
|
+
- **Pipe-friendly.** Output auto-switches to stable JSON when stdout isn't a terminal. Analyse with `jq`, plot with `gnuplot`, or feed it into your own scripts.
|
|
15
|
+
- **Single 142 kB binary, MIT, no telemetry.** Built on Bun; zero native dependencies.
|
|
16
16
|
|
|
17
|
-
##
|
|
18
|
-
|
|
19
|
-
Runtime: **[Bun](https://bun.sh)** >= 1.0.
|
|
17
|
+
## Install
|
|
20
18
|
|
|
21
19
|
```bash
|
|
22
|
-
curl -fsSL https://bun.sh/install | bash #
|
|
23
|
-
|
|
20
|
+
curl -fsSL https://bun.sh/install | bash # if you don't have Bun yet
|
|
24
21
|
bun add -g @drakulavich/oura-cli
|
|
25
|
-
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
You'll also need a [Personal Access Token from Oura](https://cloud.ouraring.com/personal-access-tokens). Paste it into `oura-cli login` once — it lands at `~/.oura-token` with `0600` perms.
|
|
25
|
+
|
|
26
|
+
## First five minutes
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
oura-cli login # paste your PAT, one time
|
|
26
30
|
oura-cli sync # backfill recent days into ~/.oura-cli/oura.db
|
|
27
|
-
oura-cli report
|
|
31
|
+
oura-cli report # weekly digest in the terminal
|
|
28
32
|
```
|
|
29
33
|
|
|
30
|
-
|
|
34
|
+
That's it. Subsequent `oura-cli sync` pulls only new days.
|
|
31
35
|
|
|
32
|
-
##
|
|
36
|
+
## Daily use
|
|
33
37
|
|
|
34
|
-
|
|
38
|
+
### Today
|
|
35
39
|
|
|
36
40
|
```bash
|
|
37
|
-
oura-cli
|
|
38
|
-
oura-cli db today # today's summary
|
|
39
|
-
oura-cli db date 2026-05-10 # any specific day
|
|
40
|
-
oura-cli db week # last 7 days
|
|
41
|
-
oura-cli db trends 30 # score trends across last 30 days
|
|
42
|
-
oura-cli db stats # row counts, date range, personal bests
|
|
43
|
-
oura-cli report weekly # narrative weekly summary
|
|
41
|
+
oura-cli db today
|
|
44
42
|
```
|
|
45
43
|
|
|
46
|
-
|
|
44
|
+
Today's scores from the local cache. If you forgot to sync, run `oura-cli sync` first.
|
|
45
|
+
|
|
46
|
+
### A specific day
|
|
47
47
|
|
|
48
48
|
```bash
|
|
49
|
-
oura-cli
|
|
49
|
+
oura-cli db date 2026-05-10
|
|
50
50
|
```
|
|
51
51
|
|
|
52
|
-
|
|
52
|
+
### Last week, at a glance
|
|
53
53
|
|
|
54
54
|
```bash
|
|
55
|
-
oura-cli
|
|
56
|
-
oura-cli
|
|
57
|
-
oura-cli activity week # daily_activity, last 7 days
|
|
58
|
-
oura-cli hr week # heartrate samples
|
|
59
|
-
oura-cli spo2 week # daily_spo2
|
|
60
|
-
oura-cli stress week # daily_stress
|
|
61
|
-
oura-cli workout week # workouts
|
|
55
|
+
oura-cli db week # local cache summary, no API hit
|
|
56
|
+
oura-cli sleep week # fresh sleep details direct from Oura
|
|
62
57
|
```
|
|
63
58
|
|
|
64
|
-
|
|
59
|
+
### Reports
|
|
65
60
|
|
|
66
|
-
|
|
61
|
+
```bash
|
|
62
|
+
oura-cli report # weekly (default)
|
|
63
|
+
oura-cli report --period month # 30-day window with weekly buckets
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Reports cover daily scores, averages, deltas vs the previous window, sleep details, and a short recommendation block.
|
|
67
|
+
|
|
68
|
+
### Trends and stats
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
oura-cli db trends 30 # score trends across the last 30 days
|
|
72
|
+
oura-cli db stats # row counts, date range, personal bests
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
### Per-endpoint detail
|
|
76
|
+
|
|
77
|
+
When you want raw Oura V2 data, every endpoint shares the same shape — `today | date <day> | week`:
|
|
67
78
|
|
|
68
79
|
```bash
|
|
69
|
-
|
|
70
|
-
oura-cli
|
|
71
|
-
oura-cli
|
|
72
|
-
oura-cli
|
|
80
|
+
oura-cli sleep today
|
|
81
|
+
oura-cli readiness date 2026-05-10
|
|
82
|
+
oura-cli activity week
|
|
83
|
+
oura-cli hr week
|
|
84
|
+
oura-cli spo2 week
|
|
85
|
+
oura-cli stress week
|
|
86
|
+
oura-cli workout week
|
|
73
87
|
```
|
|
74
88
|
|
|
75
|
-
|
|
89
|
+
### Piping to other tools
|
|
76
90
|
|
|
77
|
-
|
|
91
|
+
Output auto-switches to JSON the moment you pipe it:
|
|
78
92
|
|
|
79
|
-
```
|
|
80
|
-
|
|
93
|
+
```bash
|
|
94
|
+
oura-cli sleep week | jq '.[] | {day, score, hrv: .contributors.hrv_balance}'
|
|
95
|
+
oura-cli db trends 90 > trends.json
|
|
81
96
|
```
|
|
82
97
|
|
|
83
|
-
|
|
98
|
+
## Configuration
|
|
84
99
|
|
|
85
|
-
|
|
|
86
|
-
|
|
87
|
-
|
|
|
88
|
-
|
|
|
89
|
-
|
|
|
90
|
-
|
|
|
91
|
-
|
|
|
100
|
+
| Setting | Flag | Env var | Default |
|
|
101
|
+
|------------------|-------------|--------------------|-----------------------------|
|
|
102
|
+
| Token | `--token` | `OURA_TOKEN` | (file) |
|
|
103
|
+
| Token file path | | `OURA_TOKEN_PATH` | `~/.oura-token` |
|
|
104
|
+
| Database path | `--db` | `OURA_DB_PATH` | `~/.oura-cli/oura.db` |
|
|
105
|
+
| Timezone | `--tz` | `OURA_TZ` | system timezone, else `UTC` |
|
|
106
|
+
| Output format | `--format` | | auto-detect (TTY → table) |
|
|
92
107
|
|
|
93
|
-
##
|
|
108
|
+
## Security
|
|
94
109
|
|
|
95
|
-
|
|
110
|
+
This tool reads your personal health data — handle the token with care.
|
|
96
111
|
|
|
97
|
-
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
-
|
|
101
|
-
|
|
102
|
-
discovery and health-aggregation flow. Use this only if you're plugging
|
|
103
|
-
oura-cli into an OpenClaw gateway.
|
|
112
|
+
- `~/.oura-token` is written with `0600` permissions on POSIX (`oura-cli login` does it for you). On Windows the file is written but ACL hardening is left to you.
|
|
113
|
+
- `OURA_TOKEN` as an env var is convenient for scripts and CI, but it shows up in `ps auxe`, heap dumps, and core dumps. Prefer the file for interactive use.
|
|
114
|
+
- `--token <pat>` is the least safe option: the value lands in shell history. Avoid it outside throw-away scripts.
|
|
115
|
+
- Revoke a token at [cloud.ouraring.com/personal-access-tokens](https://cloud.ouraring.com/personal-access-tokens), not via this CLI.
|
|
116
|
+
- API error messages truncate response bodies to 200 chars and redact `Bearer` tokens and `"token":"…"` patterns before printing.
|
|
104
117
|
|
|
105
|
-
|
|
106
|
-
`compatManifestCommand` field so an agent can discover the second format
|
|
107
|
-
without prior knowledge.
|
|
118
|
+
**oura-cli performs no telemetry.** The only outbound network traffic is your authenticated Oura Cloud API calls.
|
|
108
119
|
|
|
109
|
-
## What's
|
|
120
|
+
## What's inside
|
|
110
121
|
|
|
111
122
|
| Endpoint | Source | Cached table |
|
|
112
123
|
|------------|-------------------------------------|-----------------------|
|
|
@@ -120,34 +131,19 @@ without prior knowledge.
|
|
|
120
131
|
| Sleep model | Oura V2 `sleep` | `sleep_model` |
|
|
121
132
|
| Cardiovascular age | Oura V2 `cardiovascular_age` | `cardiovascular_age` |
|
|
122
133
|
|
|
123
|
-
Runtime: [Bun](https://bun.sh). Storage: built-in `bun:sqlite`. CLI parsing: [Commander](https://github.com/tj/commander.js). Output styling: [chalk](https://github.com/chalk/chalk).
|
|
124
|
-
|
|
125
|
-
## Configuration
|
|
126
|
-
|
|
127
|
-
| Setting | Flag | Env var | Default |
|
|
128
|
-
|------------------|-------------|--------------------|-----------------------------|
|
|
129
|
-
| Token | `--token` | `OURA_TOKEN` | (file) |
|
|
130
|
-
| Token file path | | `OURA_TOKEN_PATH` | `~/.oura-token` |
|
|
131
|
-
| Database path | `--db` | `OURA_DB_PATH` | `~/.oura-cli/oura.db` |
|
|
132
|
-
| Timezone | `--tz` | `OURA_TZ` | system timezone, else `UTC` |
|
|
133
|
-
| Output format | `--format` | | auto-detect (TTY → table) |
|
|
134
|
-
|
|
135
|
-
## Security
|
|
136
|
-
|
|
137
|
-
This tool reads your personal health data — handle the access token with care.
|
|
134
|
+
Runtime: [Bun](https://bun.sh). Storage: built-in `bun:sqlite`. CLI parsing: [Commander](https://github.com/tj/commander.js). Output styling: [chalk](https://github.com/chalk/chalk). One 142 kB `dist/index.js`, no native deps.
|
|
138
135
|
|
|
139
|
-
|
|
140
|
-
- `OURA_TOKEN` as an environment variable is convenient for CI and containers, but it appears in `ps auxe`, heap dumps, and core dumps. Prefer the file-based path for interactive use.
|
|
141
|
-
- `--token <pat>` is the least safe option: the value lands in your shell history. Avoid it outside of throw-away scripts.
|
|
142
|
-
- Token revocation is done at <https://cloud.ouraring.com/personal-access-tokens>, not via this CLI.
|
|
143
|
-
- API responses are truncated to 200 chars and `Bearer`/`"token":"…"` patterns are redacted before being printed in error messages.
|
|
136
|
+
## Automation (LLM agents, scripts, MCP)
|
|
144
137
|
|
|
145
|
-
|
|
138
|
+
If you're driving the CLI from a script or LLM harness:
|
|
146
139
|
|
|
147
|
-
|
|
140
|
+
- `oura-cli describe` — JSON manifest of every command, argument, and output schema. Agents discover capabilities without scraping `--help`.
|
|
141
|
+
- `oura-cli healthcheck` — `{ok, version, latencyMs}` JSON for liveness probes.
|
|
142
|
+
- Errors emit a stable JSON envelope on stderr: `{"error":{"code":"…","message":"…","hint":"…"}}`.
|
|
143
|
+
- Documented exit codes: `0` success, `1` user error, `2` auth, `3` API, `4` storage.
|
|
144
|
+
- JSON Schemas under [`docs/schemas/`](docs/schemas/) describe every output shape, semver-stable.
|
|
148
145
|
|
|
149
|
-
|
|
150
|
-
- **MCP** — `oura-cli describe` returns enough metadata to autogenerate an MCP server wrapper. A first-party `oura-mcp` companion is on the roadmap.
|
|
146
|
+
Plays cleanly with [OpenClaw](https://github.com/openclaw/openclaw) — `oura-cli manifest` returns the tool-registry shape. A first-party `oura-mcp` companion is on the roadmap.
|
|
151
147
|
|
|
152
148
|
## Requirements
|
|
153
149
|
|
|
@@ -157,7 +153,7 @@ oura-cli performs **no telemetry**. The only outbound network traffic is your au
|
|
|
157
153
|
|
|
158
154
|
## Contributing
|
|
159
155
|
|
|
160
|
-
Bug reports and pull requests welcome at [drakulavich/oura-cli/issues](https://github.com/drakulavich/oura-cli/issues).
|
|
156
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md). Bug reports and pull requests welcome at [drakulavich/oura-cli/issues](https://github.com/drakulavich/oura-cli/issues).
|
|
161
157
|
|
|
162
158
|
## License
|
|
163
159
|
|
package/dist/index.js
CHANGED
package/package.json
CHANGED