Pull your Oura Ring data from the cloud, cache it locally in SQLite, and read it on your own terms. Weekly digests, daily scores, raw V2 endpoints, pipe-friendly JSON. No mobile app. No dashboards. No telemetry.
$ bun add -g @drakulavich/oura-cli
Capabilities
Nine endpoints, one SQLite cache. Use the high-level digests or drop down to raw Oura V2 — same shape across every command.
One oura-cli sync lands everything in ~/.oura-cli/oura.db.
Every report, trend and lookup after that hits local disk — no API call, no mobile
app, no internet required. Subsequent syncs pull only new days.
oura-cli report prints a weekly or monthly digest: daily scores,
averages, deltas vs the previous window, sleep detail, and a short recommendation
block. "You slept poorly Tuesday" callouts included.
Output auto-switches to stable JSON the moment stdout isn't a terminal.
Pipe to jq, plot with gnuplot, or feed it straight into
your own scripts and dashboards.
oura-cli db trends 30 walks score history across the last N days.
oura-cli db stats surfaces row counts, the full date range, and your
personal bests.
Every Oura V2 endpoint — daily sleep, readiness, activity, heart rate, SpO₂, stress,
workouts, sleep model, cardiovascular age — exposed with the same
today | date | week shape.
Errors emit a deterministic JSON shape on stderr — code, message,
hint. Documented exit codes for success, user errors, auth, API, and
storage. Predictable for CI and agents.
Uses your system timezone by default, falls back to UTC. Override per-invocation
with --tz or OURA_TZ when you sync from a different
machine.
The only outbound network calls are your authenticated requests to Oura Cloud. No
analytics. No phone-home. Token files written with 0600 on POSIX so
only you can read them.
Built on Bun with
bun:sqlite, citty for CLI parsing
and chalk for output.
One ~100 kB dist/index.js. Zero native deps.
oura-cli manifest returns the OpenClaw tool-registry shape. Drop your
ring data straight into an LLM agent.
Quick start
Requires Bun ≥ 1.0 and an Oura Personal Access Token. Works on macOS, Linux, and Windows (WSL).
Skip the first line if you already have Bun.
$ curl -fsSL https://bun.sh/install | bash
$ bun add -g @drakulavich/oura-cliOne time. Lands at ~/.oura-token, 0600.
$ oura-cli login
# paste PAT from cloud.ouraring.comBackfill recent days, then print your week.
$ oura-cli sync
$ oura-cli report# Today, from local cache
$ oura-cli db today
# A specific day
$ oura-cli db date 2026-05-10
# Last week at a glance — no API hit
$ oura-cli db week
# Pull the latest days into the cache
$ oura-cli sync# Weekly digest (default)
$ oura-cli report
# 30-day window with weekly buckets
$ oura-cli report --format month
# Score trends across the last 30 days
$ oura-cli db trends 30
# Row counts, date range, personal bests
$ oura-cli db stats# Every endpoint shares the same shape: today | date | week
$ oura-cli sleep today
$ oura-cli readiness date 2026-05-10
$ oura-cli activity week
# Fresh sleep detail straight from Oura
$ oura-cli sleep week
# Heart rate, SpO₂, stress, workouts
$ oura-cli hr week
$ oura-cli spo2 week
$ oura-cli stress week
$ oura-cli workout week# Output auto-switches to JSON the moment you pipe
$ oura-cli sleep week | jq '.[] | {day, score, hrv: .contributors.hrv_balance}'
# Dump 90 days of trends to a file
$ oura-cli db trends 90 > trends.json
# Pipe a digest into your favorite LLM
$ oura-cli report | llm "Summarize my week and call out anything concerning"What's inside
Every Oura V2 endpoint lands in its own cached table. Same date range, same shape,
same JSON. Inspect with the sqlite3 CLI if you want — it's your data.
daily_sleep
daily_sleep
oura-cli sleep …
daily_readiness
daily_readiness
oura-cli readiness …
daily_activity
daily_activity
oura-cli activity …
heartrate
heartrate
oura-cli hr …
daily_spo2
daily_spo2
oura-cli spo2 …
daily_stress
daily_stress
oura-cli stress …
workout
workouts
oura-cli workout …
sleep
sleep_model
via report
cardiovascular_age
cardiovascular_age
via report
Storage: bun:sqlite. CLI parsing: citty. Output: chalk.
Configuration
--token
OURA_TOKEN
file
--db
OURA_DB_PATH
~/.oura-cli/oura.db
--tz
OURA_TZ
system, else UTC
--format
—
auto (TTY → table)
Automation
If you're driving the CLI from a script or LLM harness, the introspection surface is first-class — and the output contracts are semver-stable.
oura-cli describe
A JSON manifest of every command, argument and output schema. Agents discover
capabilities without scraping --help.
oura-cli healthcheck
Returns {ok, version, latencyMs} for liveness probes. Wire it straight
into your monitoring stack or agent harness.
oura-cli manifest returns the tool-registry shape. A first-party
oura-mcp companion is on the roadmap.
Schemas under docs/schemas/ describe every output. Exit codes are
documented: 0 ok, 1 user, 2 auth,
3 API, 4 storage.
Security
This tool reads personal health data. The CLI is designed to keep your token off disk in obvious places, out of shell history, and out of error logs.
~/.oura-token written with 0600 by oura-cli login. Only your user can read it.
OURA_TOKEN works for CI & scripts — but shows up in ps auxe and core dumps. Prefer the file.
--token <pat> lands in shell history. Throw-away scripts only.
Bearer tokens and "token":"…" patterns.
Open source, MIT licensed, no telemetry. Star the repo, grab the binary, paste your token — your weekly digest is one command away.