Pull your Oura Ring data from the cloud, cache it locally in SQLite, and read it on your own terms: weekly digests, daily scores, seventeen raw V2 collections, pipe-friendly JSON. Without the mobile app, and without telemetry.
$ bun add -g @drakulavich/oura-cli
Capabilities
Seventeen collections, one SQLite cache. Read the digests, or drop down to the raw Oura
V2 records with fetch and db rows.
One oura-cli sync lands everything in ~/.oura-cli/oura.db.
Every report, trend and lookup after that reads local disk: no API call, no mobile
app, no internet required. Later syncs resume each collection from its last stored day.
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.
fetch <collection> reads the API, db rows <collection> reads the
cache, with the same range flags. Sleep, readiness, activity, heart rate, SpO₂, stress,
workouts, sleep periods, cardiovascular age, resilience, VO₂ max, bedtime guidance,
sessions, rest mode, tags, ring, battery.
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.
oura-cli doctor checks the token, the database, its integrity
(SQLite quick_check) and how fresh the data is, then prints one
Next: line. Online it asks Oura whether it holds newer days, so it can tell
"run sync" apart from "the ring has not uploaded".
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.
Runs straight from TypeScript source. 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. The token lands at ~/.oura-token with 0600.
$ oura-cli login
# paste PAT from cloud.ouraring.com
$ oura-cli doctorThe first sync fetches 30 days, then print your week.
$ oura-cli sync
$ oura-cli report# Today, from the local cache
$ oura-cli db today
# A specific day; an empty day says which sync would fill it
$ 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
# Token, database, integrity, freshness
$ oura-cli doctor# Weekly digest (default)
$ oura-cli report
# 30-day window with weekly buckets
$ oura-cli report --period month
# Score trends across the last 30 days
$ oura-cli db trends 30
# Row counts, date range, personal bests
$ oura-cli db stats# fetch reads the API; db rows reads the cache, same flags
$ oura-cli fetch sleep # today
$ oura-cli fetch hr --days 7
$ oura-cli fetch workout --from 2026-05-01 --to 2026-05-31
$ oura-cli db rows tags --days 30
$ oura-cli db rows battery --day 2026-09-01
$ oura-cli db rows hr --day 2026-09-01 --limit 20
# sleep readiness activity hr spo2 stress workout sleep-periods cv-age
# resilience vo2max sleep-time session rest-mode tags ring battery# Output switches to JSON the moment you pipe
$ oura-cli fetch sleep --days 7 | jq '.[] | {day, score, deep: .contributors.deep_sleep}'
# 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 collection lands in its own cached table. fetch <collection> reads
the API, db rows <collection> reads the cache. Inspect the file with the
sqlite3 CLI if you want: it's your data.
daily_sleep
daily_sleep
sleep
daily_readiness
daily_readiness
readiness
daily_activity
daily_activity
activity
heartrate
heartrate
hr
daily_spo2
daily_spo2
spo2
daily_stress
daily_stress
stress
workout
workouts
workout
sleep
sleep_model
sleep-periods
cardiovascular_age
cardiovascular_age
cv-age
daily_resilience
daily_resilience
resilience
vO2_max
vo2max
vo2max
sleep_time
sleep_time
sleep-time
session
sessions
session
rest_mode_period
rest_mode_periods
rest-mode
enhanced_tag
enhanced_tags
tags
ring_configuration
ring_configuration
ring
ring_battery_level
ring_battery_level
battery
Storage:
bun:sqlite.
CLI parsing:
citty.
Output:
chalk.
No build step: the CLI runs from src/ on Bun.
Configuration
--token
OURA_TOKEN
file
--path (login)
OURA_TOKEN_PATH
~/.oura-token
--db
OURA_DB_PATH
~/.oura-cli/oura.db
--tz
OURA_TZ
system, else UTC
--format
auto (TTY → table)
--no-color
NO_COLOR
on for a terminal, off when piped
Automation
If you're driving the CLI from a script or LLM harness, the introspection surface is first-class, and the output contracts follow semver.
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: the database opens and
answers a query. Gate on .ok, not the exit code; doctor does the
deeper checks.
skills/oura-cli/SKILL.md ships in the package, in the
Agent Skills format OpenClaw,
Hermes and ~/.agents/skills read: which command answers which question, the JSON
shapes, exit codes, and the rules. A test resolves every command in it against
describe, so it cannot drift.
Schemas under docs/schemas/ cover fetch <collection>,
doctor and the describe manifest. 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, install the package, paste your token: your weekly digest is one command away.