Oura Cli

oura-cli

Own your Oura Ring data. 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.

• Offline-first. Everything caches into ~/.oura-cli/oura.db after one oura-cli sync. Reports keep working when your internet doesn't.
• 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.
• 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.
• Single 100 kB binary, MIT, no telemetry. Built on Bun; zero native dependencies.

Install

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

You'll also need a Personal Access Token from Oura. Paste it into oura-cli login once — it lands at ~/.oura-token with 0600 perms.

First five minutes

oura-cli login          # paste your PAT, one time
oura-cli sync           # backfill recent days into ~/.oura-cli/oura.db
oura-cli report         # weekly digest in the terminal

That's it. Subsequent oura-cli sync pulls only new days.

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

Last week, at a glance

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

Reports

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

Reports cover daily scores, averages, deltas vs the previous window, sleep details, and a short recommendation block.

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

Per-endpoint detail

When you want raw Oura V2 data, every endpoint shares the same shape — today | date | week:

oura-cli sleep today
oura-cli readiness date 2026-05-10
oura-cli activity week
oura-cli hr week
oura-cli spo2 week
oura-cli stress week
oura-cli workout week

Piping to other tools

Output auto-switches to JSON the moment you pipe it:

oura-cli sleep week | jq '.[] | {day, score, hrv: .contributors.hrv_balance}'
oura-cli db trends 90 > trends.json

Configuration

| Setting | Flag | Env var | Default | |------------------|-------------|--------------------|-----------------------------| | Token | --token | OURA_TOKEN | (file) | | Token file path | | 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) |

Security

This tool reads your personal health data — 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 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 via this CLI.
• API error messages truncate response bodies to 200 chars and redact Bearer tokens and "token":"…" patterns before printing.

oura-cli performs 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 |

Runtime: Bun. Storage: built-in bun:sqlite. CLI parsing: citty. Output styling: chalk. One 100 kB dist/index.js, no native deps.

Automation (LLM agents, scripts, MCP)

If you're driving the CLI from a script or LLM harness:

• oura-cli describe — JSON manifest of every command, argument, and output schema. Agents discover capabilities without scraping --help.
• oura-cli healthcheck — {ok, version, latencyMs} JSON for liveness probes.
• Errors emit a stable JSON envelope on stderr: {"error":{"code":"…","message":"…","hint":"…"}}.
• Documented exit codes: 0 success, 1 user error, 2 auth, 3 API, 4 storage.
• JSON Schemas under [docs/schemas/](docs/schemas/) describe every output shape, semver-stable.

Plays cleanly with OpenClaw — oura-cli manifest returns the tool-registry shape. A first-party oura-mcp companion is on the roadmap.

Requirements

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

Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Bug reports and pull requests welcome at drakulavich/oura-cli/issues.

License

Made with 💍🤖 under MIT License.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: drakulavich
• Source: drakulavich/oura-cli
• License: MIT
• Homepage: https://drakulavich.github.io/oura-cli/

Install and usage instructions live in the source repository linked above.