oura-cli

oura-cli downloads your Oura data into a SQLite file and prints it. After one oura-cli sync every report works offline. On a terminal you get tables and a weekly digest; in a pipe you get JSON, so jq, gnuplot and your own scripts can read it. The package is MIT, runs from TypeScript source on Bun, has no native dependencies and sends nothing anywhere except to the Oura API.

Install

curl -fsSL https://bun.sh/install | bash   # if you don't have Bun yet
bun add -g @drakulavich/oura-cli

You also need a Personal Access Token from Oura. Run oura-cli login once. It hides the token while you type and saves it to ~/.oura-token with 0600 permissions.

First five minutes

Four commands take you from an empty cache to a weekly digest:

oura-cli login    # paste your PAT; the input is hidden
oura-cli doctor   # confirm the token works and the database is ready
oura-cli sync     # the first sync fetches the last 30 days
oura-cli report   # weekly digest in the terminal

The digest looks like this:

  Oura Weekly Report
  2026-08-24 — 2026-08-30

  Last 7 Days:
  ────────────────────────────────────────────────────
  Day         Sleep  Ready  Active    Steps
  ────────────────────────────────────────────────────
  Mon 24/08      87     74      68    9,668
  Tue 25/08      82     79      74   11,204
  ...

How sync behaves after the first run

Each collection resumes from its own last stored day. Oura revises recent days, so the overlap is deliberate, and the summary reports rows fetched (+new) per collection.

Heart rate also re-reads the two weeks behind its watermark, because Oura publishes workout samples days after the day they belong to. That re-read happens on the first sync of the day and whenever a sync brings samples newer than the cache, which means the ring has uploaded. A repeat sync on a quiet ring costs about 17 requests instead of 37.

A re-fetched window ends up holding exactly what the API returned for it. A sample Oura reclassified, or a record it re-issued under a new id, replaces the row it supersedes instead of joining it. There is one exception. When a response drops most of what one request covered, which is what a partial or short answer looks like, sync keeps those rows and names the collection and how many it kept. Once you have judged the correction genuine, oura-cli sync --prune=hr applies them for that collection, and --prune=all does it for every collection in the run.

oura-cli sync --from 2026-08-01 [--to 2026-08-07] re-fetches an explicit window for every collection instead, for example after an interrupted sync. A 429 Too Many Requests is retried with the wait Retry-After asks for, up to a minute per wait and three minutes per command, before it becomes an error.

oura-cli db today and oura-cli db week read the local cache and make no API call.

If something looks wrong

What you see	What to run
No Oura data is available for this report yet.	oura-cli sync
No Oura access token at ~/.oura-token	oura-cli login
Oura API 401	oura-cli login with a fresh PAT
Oura API 429 after the automatic retries	Wait a few minutes. A long fetch hr window is hundreds of requests.
db today empty right after a sync	Normal. Oura publishes a day's summary after that night's sleep syncs from the ring.
doctor still warns that data is stale after a sync	The ring has not uploaded. Open the Oura app near the ring, then run oura-cli sync. doctor without --offline says which side is behind.
Database query failed: database disk image is malformed	The cache file is damaged. Delete it (see --db and OURA_DB_PATH) and run oura-cli sync to rebuild it. oura-cli doctor shows what is wrong with it first.
Anything else	oura-cli doctor

Daily use

Today

oura-cli db today

Today's scores from the local cache. If you forgot to sync, run oura-cli sync first.

A specific day

oura-cli db date 2026-05-10

When the cache has nothing for the day, db date says where the day sits (before the cache begins, after it ends, or in a gap inside it) and which sync call would fill it, instead of printing a row of dashes.

Last week, at a glance

oura-cli db week                  # local cache summary, no API hit
oura-cli fetch sleep --days 7     # fresh sleep details direct from Oura

Reports

oura-cli report                   # weekly (default)
oura-cli report --period month    # 30-day window with weekly buckets

A report has daily scores, averages with deltas against the previous window, the days that stood out (sleep or readiness under 70, activity at 90 or above), sleep details and a short recommendation block.

A day whose activity is still accumulating, normally just today, is marked with a *. It stays out of the activity and steps averages and out of the recommendations; sleep, readiness and SpO2 averages take every day shown, and each average line says how many days it covers. In JSON the same information is days[].partial and completeThrough. db today, db date and db week carry the same partial flag and print the same * and note, so the screens agree. A day counts as closed once Oura reports a full 24 hours of five-minute activity slots for it, so a ring that stops syncing does not freeze its last day as unfinished.

Trends and stats

oura-cli db trends 30             # score trends across the last 30 days
oura-cli db stats                 # row counts, date range, personal bests

Health check

oura-cli doctor            # token, token accepted by Oura, database, integrity, data freshness
oura-cli doctor --offline  # the same without the live token check

doctor prints one row per check and a Next: line with the first fix to apply. The integrity row runs SQLite's quick_check. The data row warns once the newest cached day ended more than 36 hours ago; online, it also asks Oura whether it holds anything newer, so it can tell "run oura-cli sync" apart from "the ring has not uploaded".

Cached rows of any collection

db rows prints what the cache holds for one collection, as stored, in either output mode. It takes the same range flags and defaults as fetch (--day, --from/--to, --days; today by default; none for ring), so the two are twins: fetch reads the API, db rows reads the cache. This is how you read back the collections no summary shows: tags, sessions, resilience, VO₂ max, bedtime guidance, rest mode, ring, battery.

oura-cli db rows tags --days 30                     # your own annotations for the month
oura-cli db rows battery --day 2026-09-01           # the battery curve for one day
oura-cli db rows ring --format json                 # every ring on the account, as JSON
oura-cli db rows hr --day 2026-09-01 --limit 20     # a day of heart rate is hundreds of rows

Raw API records

fetch returns one collection straight from the Oura API as JSON and does not touch the local cache.

oura-cli fetch sleep                       # today
oura-cli fetch hr --days 7                 # last 7 days
oura-cli fetch workout --from 2026-05-01 --to 2026-05-31
oura-cli fetch sleep-periods --day 2026-06-01 | jq '.[] | {day, type, average_hrv}'

Collections: sleep readiness activity hr spo2 stress workout sleep-periods cv-age resilience vo2max sleep-time session rest-mode tags ring battery.

ring is a snapshot of your ring's hardware, not a day range, so it takes no --day, --from or --days. battery is a timeseries like hr: keyed by timestamp and fetched in pieces of at most 30 days.

Piping to other tools

Output switches to JSON as soon as stdout is not a terminal:

oura-cli fetch sleep --days 7 | jq '.[] | {day, score, deep: .contributors.deep_sleep}'
oura-cli db trends 90 > trends.json

Configuration

Setting	Flag	Env var	Default
Token	--token	OURA_TOKEN	(file)
Token file path	--path (login only)	OURA_TOKEN_PATH	~/.oura-token
Database path	--db	OURA_DB_PATH	~/.oura-cli/oura.db
Timezone	--tz	OURA_TZ	system timezone, else UTC
Output format	--format		auto-detect (TTY → table)
Colour	--no-color	NO_COLOR	on for a terminal, off when piped

These flags are global and may appear anywhere on the command line: before the command, between a command and its subcommand, or at the end. oura-cli --format json db today, oura-cli db --format json today and oura-cli db today --format json are the same command.

Security

This tool reads your personal health data, so handle the token with care.

• ~/.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.
• 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.
• --token <pat> is the least safe option: the value lands in shell history. Avoid it outside throw-away scripts.
• Revoke a token at cloud.ouraring.com/personal-access-tokens, not through this CLI.
• API error messages truncate response bodies to 200 characters and redact Bearer tokens and "token":"…" patterns before printing.

oura-cli has no telemetry. The only outbound network traffic is your authenticated Oura Cloud API calls.

What's inside

Endpoint	Source	Cached table
Sleep	Oura V2 daily_sleep	daily_sleep
Readiness	Oura V2 daily_readiness	daily_readiness
Activity	Oura V2 daily_activity	daily_activity
Heart rate	Oura V2 heartrate	heartrate
SpO₂	Oura V2 daily_spo2	daily_spo2
Stress	Oura V2 daily_stress	daily_stress
Workouts	Oura V2 workout	workouts
Sleep model	Oura V2 sleep	sleep_model
Cardiovascular age	Oura V2 cardiovascular_age	cardiovascular_age
Resilience	Oura V2 daily_resilience	daily_resilience
VO₂ max	Oura V2 vO2_max	vo2max
Sleep time	Oura V2 sleep_time	sleep_time
Sessions	Oura V2 session	sessions
Rest mode	Oura V2 rest_mode_period	rest_mode_periods
Tags	Oura V2 enhanced_tag	enhanced_tags
Ring	Oura V2 ring_configuration	ring_configuration
Battery	Oura V2 ring_battery_level	ring_battery_level

Runtime: Bun. Storage: the built-in bun:sqlite. CLI parsing: citty. Output styling: chalk. There is no build step: the CLI runs from src/ on Bun and has no native dependencies.

Automation (LLM agents, scripts, MCP)

For a script or an LLM harness driving the CLI:

• oura-cli describe prints a JSON manifest of every command, argument and output schema, so an agent can discover the surface without scraping --help.
• oura-cli healthcheck prints {ok, version, latencyMs} for liveness probes, plus error when ok is false. It proves the database opens and answers a query; it does not inspect the contents. oura-cli doctor runs SQLite's quick_check for that.
• Gate on .ok, not on the exit code. doctor exits 0 with ok: false for any warning-level check (no data yet, stale data, Oura API unreachable), and healthcheck exits 0 with ok: false for an unusable database, because the probe itself ran. doctor --offline skips the token-validation call, and a skipped check still counts towards ok.
• Errors go to stderr as a stable JSON envelope: {"error":{"code":"…","message":"…","hint":"…"}}.
• Exit codes: 0 success, 1 user error, 2 auth, 3 API, 4 storage.
• JSON Schemas under docs/schemas/ cover fetch <collection>, doctor and the describe manifest itself, and follow semver; describe names the schema next to each command. Each collection schema pins the identity fields (id and day for the daily summaries, timestamp for the heart-rate and battery series, id and start_day for rest mode and tags, id alone for ring) and lets the rest of the Oura record through unchanged, so a new upstream field never breaks validation. The local-data commands (sync, db *, report) have no schema files yet; their shapes are versioned through the CHANGELOG.
• Two contract quirks stay for compatibility. report --period month returns its window as weekStart and weekEnd. heartrate.day (and ring_battery_level.day) in the cache is the date written in Oura's timestamp, UTC in practice, while every --day and --tz argument is local.

oura-cli manifest prints the tool-registry shape OpenClaw expects. A first-party oura-mcp companion is on the roadmap.

Agent skill

skills/oura-cli/SKILL.md is an Agent Skills file: which command answers which question, the JSON shapes, the exit codes, and the rules an agent should keep (always --format json, cache before API, never print the token). It ships in the npm package, so link the folder into wherever your harness looks for skills:

SKILL_SRC=~/.bun/install/global/node_modules/@drakulavich/oura-cli/skills/oura-cli
ln -s "$SKILL_SRC" ~/.openclaw/skills/oura-cli     # OpenClaw
ln -s "$SKILL_SRC" ~/.hermes/skills/oura-cli       # Hermes Agent
ln -s "$SKILL_SRC" ~/.agents/skills/oura-cli       # any harness that reads ~/.agents/skills

A test resolves every oura-cli … line in the skill against describe, so the file cannot name a command, flag, collection or error code the CLI does not have, and CI runs the reference validator (uvx --from skills-ref agentskills validate skills/oura-cli) on the frontmatter. One deliberate deviation from the spec: metadata.openclaw and metadata.hermes are nested objects, because both harnesses read them that way (the spec types metadata as string → string); the same test confines the deviation to those two keys.

Requirements

• Bun >= 1.4.4
• macOS, Linux, or Windows (WSL)
• An Oura Personal Access Token

Contributing

See CONTRIBUTING.md. Bug reports and pull requests are welcome at drakulavich/oura-cli/issues.

License

Made with 💍🤖 under MIT License.