Oura CLI

oura-cli

oura-cli downloads the user's Oura Ring data into ~/.oura-cli/oura.db and prints it. After one oura-cli sync, every report and summary is answered from that file without a network call.

Rules

1. Always pass --format json. Output format is otherwise guessed from whether stdout is a terminal, and an agent's shell is often neither reliably one nor the other.
2. Cache first. Answer from db today, db date, db week, db trends, db rows or report. Run sync when doctor says the data is stale or the user asks for the latest. Use fetch only when the cache cannot answer (the user wants the exact API record, or a range older than the cache).
3. Never ask for or print the token. oura-cli login is interactive and hides the input. If there is no token, tell the user to run oura-cli login themselves, or to export OURA_TOKEN in the environment the agent runs in. Do not echo ~/.oura-token, OURA_TOKEN, or the --token flag into a transcript.
4. This is personal health data. Keep it on the machine. Do not paste rows into a third-party service or file outside the user's request without saying so first.
5. Gate on .ok, not the exit code. healthcheck always exits 0 once the probe ran, and doctor exits 0 for a warn (stale or empty cache) even though ok is false. doctor exits 2 when a token check fails and 4 when the database check fails, so a non-zero exit is a finding, not a crash.

Preflight

oura-cli doctor --offline --format json

Returns {ok, checks[], nextStep}. Each check is {id, status: "ok"|"warn"|"fail"|"skip", detail}; nextStep is the first fix to apply, or null. What each id means when it is not ok:

Drop --offline when you also want to know whether Oura has newer data than the cache: one API call to validate the token, and up to one per collection to look for newer data when the cache is stale.

Which command answers which question

A day object from db today, db date and db week:

{
  "day": "2026-09-01", "partial": false,
  "sleep_score": 84, "readiness_score": 79, "activity_score": 71, "steps": 9412,
  "stress": "normal", "spo2": 97.4, "temp_deviation": -0.1,
  "sleep_hours": 7.3, "deep_hours": 1.6, "rem_hours": 1.5,
  "avg_hrv": 52, "lowest_hr": 48, "efficiency": 91
}

Every field except day and partial can be null. Today is often all null until the morning, because Oura publishes a day's summary only after that night's sleep syncs from the ring. A past day that is all null is not cached: run oura-cli db date <day> --format table once, the one deliberate exception to rule 1: the table output says whether the day is before the cache begins, after it ends, or in a gap, and which sync call would fill it, and the JSON does not. Pass that hint on rather than guessing. When every day is null in db week and report as well, the cache is empty: doctor says so (data: warn, nextStep: oura-cli sync). A --db path that does not exist is created as a new empty cache rather than rejected, so check the path before concluding there is no data.

report.recommendations holds codes, not sentences: sleep_low, sleep_great, readiness_low, readiness_great, steps_low, steps_great. Phrase them yourself; the table output has one line per code.

Collections

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

Range flags for db rows and fetch: --day YYYY-MM-DD (default: today), --from YYYY-MM-DD --to YYYY-MM-DD (both required), or --days N. ring is a hardware snapshot and takes no range. hr and battery are timeseries keyed by timestamp: a single day of hr is hundreds of rows, so add --limit N on db rows or narrow the day before reading it into context.

oura-cli db rows workout --days 7 --format json          # last week's workouts
oura-cli db rows tags --from 2026-08-01 --to 2026-08-31 --format json
oura-cli db rows hr --day 2026-09-01 --limit 50 --format json
oura-cli db rows ring --format json                        # ring model, size, firmware
oura-cli fetch sleep-periods --day 2026-09-01               # bedtime, HRV, per-period detail

Reading the numbers

• Scores are 0–100. Oura's own bands: 85+ optimal, 70–84 good, under 70 pay attention. report flags days with sleep or readiness under 70 and activity at 90 or above.
• partial: true marks a day whose activity is still accumulating (normally today). Do not compare its activity score or steps with closed days; report already leaves such days out of the activity averages and out of the recommendations, and says so in completeThrough.
• temp_deviation is degrees Celsius against the user's baseline; a sustained rise with a readiness drop is what Oura itself reads as a possible illness signal. Report it, do not diagnose.
• stress is Oura's day summary (restored, normal, stressful) or null.
• --tz Europe/Helsinki (or OURA_TZ) sets the timezone --day and today are interpreted in; default is the system timezone. One quirk: day on cached hr and battery rows is the date in Oura's UTC timestamp, not the local day.

Errors and exit codes

Errors are a single JSON object on stderr:

{"error":{"code":"BAD_ARGS","message":"<day> must be a real YYYY-MM-DD date, got \"tomorrow\".","hint":"Write <day> as a calendar day, e.g. 2026-09-01."}}

code and message are always present. hint is optional: it is there when the CLI has a fix to suggest, and absent otherwise (an unexpected internal error, some argument conflicts), so treat a missing hint as no suggestion, not as a malformed payload.

Discovering the rest

• oura-cli describe prints a JSON manifest of every command, argument, enum value, exit code and the JSON Schema file for each output. Read it instead of scraping --help.
• oura-cli healthcheck is a liveness probe: {ok, version, latencyMs}.
• Global flags --format, --db, --tz, --token, --no-color may appear anywhere on the line.
• JSON Schemas for fetch <collection>, doctor and describe ship in the package under docs/schemas/.