@drakulavich/oura-cli 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -6,6 +6,20 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-09-13
+
+### Added
+- `db rows <collection>` prints the cached rows of any collection, as stored, in both output modes: the cache-side twin of `fetch`, with the same range flags and defaults (`--day`, `--from/--to`, `--days`; today by default; none for `ring`). Eight of the seventeen collections were write-only from the user's side: `sync` filled resilience, VO₂ max, bedtime guidance, sessions, rest mode, tags, ring and battery, `db stats` counted them, and nothing read them back short of `fetch`, which goes to the API and ignores the cache. The table view shows one column per stored column, numbers right-aligned, text cells cut at 40 characters and, on a terminal, squeezed further so the table fits the screen; a column name is never cut, and when the names alone would not fit (sleep-periods has 19 columns) each row is printed as a block of `name  value` lines instead. `--limit N` prints the first N rows and the title says how many the range holds; a day of heart rate is hundreds. A newline in a tag comment shows as ⏎ instead of breaking the row. The JSON is the rows exactly as stored, so a JSON blob such as `contributors` stays a string. Heart-rate and battery samples are bounded on the local day asked for, the way `fetch` bounds its request, not on the UTC date their `day` column stores. An empty result names the range asked for and how to fill it. The `describe` manifest lists the subcommand with the collection enum. (#73)
+
+### Fixed
+- `doctor` no longer calls a cache current while `report` and `db week` mark its newest day as still accumulating. The `data` check compared calendar days and only warned past two, so on 2026-09-12 a cache ending on 2026-09-10 passed. It now measures hours from the end of the newest day (its local midnight in the cache timezone) and warns past 36: one missed night is ordinary ring lag, a second is worth the nudge. The detail names the limit, and `nextStep` points at `oura-cli sync`. (#114)
+- Text output is tidier. Every view draws its horizontal rule at the same two-column indent as the text under it (`db today`, `db week`, `db trends`, `db stats`, `doctor` and the panel after `sync` drew theirs at column 0), as wide as the widest line it delimits (a fixed 50 sat under 63-column trend rows), and never wider than the terminal, where it wrapped onto a second line. `db week` no longer pads its last column, which left up to nine trailing spaces on every row. The empty-today panel after `sync` explains that Oura publishes a day's summary once the night's sleep has synced, as `db today` already did, instead of printing bare dashes. `oura-cli db` on its own, `db toady`, and `db --format json` with no subcommand name the subcommands `db` takes and point at `oura-cli db --help` rather than the root help; on a terminal a bare `oura-cli db` prints that help, as a bare `oura-cli` does. (#61)
+- A `429 Too Many Requests` no longer ends a long `fetch` or `sync` on the spot. The page is retried up to three times after the wait `Retry-After` asks for (seconds or an HTTP date, each wait capped at one minute), or one, two and four seconds without it, and one command waits at most three minutes on 429 answers in total; only then is it an `API_ERROR`, with a hint that says how often the page was retried, how long the command waited, and to try again later or ask for a shorter range. A transport failure (DNS, connection refused) is an `API_ERROR` with a hint too, where it was an `UNKNOWN` with none. On a terminal, `fetch` and `sync` show a one-line progress counter on stderr (`fetching heartrate: page 41, 40000 rows so far…`), which also says when the client is waiting on a 429 (`; rate limited, retrying in 30 s…`) and is wiped when the command finishes; a 61-day `fetch hr` is 77 pages and was over a minute of silence, and a rate-limit wait was the same silence. On a pipe stderr stays clean, since it carries the error envelope. `doctor` names a next step when the API could not be reached, where it reported `ok: false` with `nextStep: null`. No upper bound was put on the range: a long backfill is a legitimate use, and pacing rather than refusing is what the API asks for. (#45)
+- A malformed response body from the Oura API is now an `API_ERROR` (exit 3) naming the endpoint and what came back, instead of an `UNKNOWN` with an internal expression. `sync` and `fetch` walked whatever sat under `data`: an object failed with `{} is not iterable`, and a string was iterated character by character and reported as dropped samples that never existed. A missing or null `data` is still an empty page; a `next_token` that is not a string or null is the same error, not a last page. (#112)
+- `db date` and `db today` mark a day whose activity totals are not final the way `db week` and `report` already do: `2026-09-10*` in the header and one note under the numbers. The JSON has carried `partial` since 0.7.1; the table output did not show it, so drilling from a marked week row into the day lost the mark. The note's wording is now one string shared by the day and week views. (#113)
+- Small text inconsistencies from the eight-collection expansion. `db stats` names each table by both its collection name and its table (`sleep-periods (sleep_model)`), as the `sync` lines already did, and prints `1 row`, not `1 rows`; its JSON rows carry a `collection` field. `db stats` explains itself when the cache holds rows but no daily summaries, instead of printing counts and nothing else. The `*` note in `report` says "activity totals are not final" like the day and week views, which reads right when the marked day is in the past. `sync --help` describes what the command prints; the unknown-flag hint no longer claims there are no single-letter flags when `-v` and `-h` exist; README names the identity fields the per-collection schemas actually pin. (#72)
+- A `sync` response that includes a row from outside the window it was asked for no longer widens that request's reconciliation scope. The scope of one request was taken from the timestamps that came back, so a single early or empty-string timestamp reached back over every stored sample between it and the window: on a 60-sample cache one stray value put 59 rows up as "not returned", with the truncation guard's own message naming the `--prune=hr` flag that would have deleted them. Each request now carries the range it asked for and only rows inside it count towards the scope; rows outside are still stored, they just vouch for nothing. (#111)
+
 ## [0.7.1] - 2026-09-12
 
 ### Fixed

package/README.md

@@ -96,7 +96,7 @@ 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. A day whose activity is still accumulating — normally just today — is shown with a `*` and kept out of the activity averages and recommendations; the JSON says so via `days[].partial` and `completeThrough`. `db today`, `db date` and `db week` carry the same `partial` flag, and `db week` marks the day with a `*` too, so the two screens cannot disagree. A day is treated as closed once Oura reports a full 24 hours of five-minute activity slots for it, so a ring that stops syncing no longer freezes its last day as unfinished.
+Reports cover daily scores, averages, deltas vs the previous window, sleep details, and a short recommendation block. A day whose activity is still accumulating — normally just today — is shown with a `*` and kept out of the activity averages and recommendations; the JSON says so via `days[].partial` and `completeThrough`. `db today`, `db date` and `db week` carry the same `partial` flag and mark the day with the same `*` and note, so the screens cannot disagree. A day is treated as closed once Oura reports a full 24 hours of five-minute activity slots for it, so a ring that stops syncing no longer freezes its last day as unfinished.
 
 ### Trends and stats
 
@@ -105,6 +105,16 @@ oura-cli db trends 30             # score trends across the last 30 days
 oura-cli db stats                 # row counts, date range, personal bests
 ```
 
+### 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 the collections no summary shows — tags, sessions, resilience, VO₂ max, bedtime guidance, rest mode, ring, battery — are read back.
+
+```bash
+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
+```
+
 ### Raw API records
 
 `fetch` returns one collection straight from the Oura API as JSON, without touching the local cache.
@@ -187,7 +197,7 @@ If you're driving the CLI from a script or LLM harness:
 - 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 (the probe itself ran). `doctor --offline` skips the token-validation call, and a skipped check still counts towards `ok`.
 - 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/) cover `fetch <collection>`, `doctor` and the `describe` manifest itself, semver-stable; `describe` names the schema next to each command. Per-collection schemas pin the identity fields (`id`, `day`, `timestamp`) and allow the rest of the Oura record through unchanged, so new upstream fields never break validation. The local-data commands (`sync`, `db *`, `report`) have no schema files yet; their shapes are versioned through the CHANGELOG.
+- JSON Schemas under [`docs/schemas/`](docs/schemas/) cover `fetch <collection>`, `doctor` and the `describe` manifest itself, semver-stable; `describe` names the schema next to each command. Per-collection schemas pin each collection's 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 allow the rest of the Oura record through unchanged, so new upstream fields never break validation. The local-data commands (`sync`, `db *`, `report`) have no schema files yet; their shapes are versioned through the CHANGELOG.
 - Two contract quirks, kept for compatibility: `report --period month` returns its window as `weekStart`/`weekEnd`, and `heartrate.day` (likewise `ring_battery_level.day`) in the cache is the date written in Oura's timestamp (UTC in practice) while every `--day`/`--tz` argument is local.
 
 Plays cleanly with [OpenClaw](https://github.com/openclaw/openclaw) — `oura-cli manifest` returns the tool-registry shape. A first-party `oura-mcp` companion is on the roadmap.

package/dist/index.js

@@ -1534,11 +1534,46 @@ function resolveToken(explicit, tokenPath) {
 
 // src/api/client.ts
 var BASE_URL = "https://api.ouraring.com/v2/usercollection";
+function kindOf(value) {
+  if (value === null)
+    return "null";
+  if (Array.isArray(value))
+    return "an array";
+  return typeof value === "object" ? "an object" : `a ${typeof value}`;
+}
 var MAX_PAGES = 1e4;
+var RETRY_LIMIT = 3;
+var MAX_RETRY_AFTER_MS = 60000;
+var MAX_TOTAL_WAIT_MS = 3 * 60000;
+var BACKOFF_MS = [1000, 2000, 4000];
+function retryDelayMs(retryAfter, attempt, now = Date.now()) {
+  let ms = Number.NaN;
+  if (retryAfter !== null) {
+    const whole = retryAfter.trim();
+    const firstPart = whole.split(",")[0].trim();
+    const firstDate = whole.match(/^[A-Za-z]{3}, [^,]*? GMT/)?.[0] ?? "";
+    const seconds = [whole, firstPart].filter((r) => r !== "").map(Number).find(Number.isFinite);
+    const date = [whole, firstDate, firstPart].map(Date.parse).find(Number.isFinite);
+    if (seconds !== undefined)
+      ms = seconds * 1000;
+    else if (date !== undefined)
+      ms = date - now;
+  }
+  if (!Number.isFinite(ms) || ms <= 0)
+    ms = BACKOFF_MS[Math.min(attempt, BACKOFF_MS.length - 1)];
+  return Math.min(ms, MAX_RETRY_AFTER_MS);
+}
 
 class OuraClient {
   token;
+  onPage;
+  onRetry;
+  sleep;
+  waitedMs = 0;
   constructor(options = {}) {
+    this.onPage = options.onPage;
+    this.onRetry = options.onRetry;
+    this.sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
     const { token, source } = resolveToken(options.token, options.tokenPath);
     if (!token) {
       throw new CliError("TOKEN_MISSING", `No Oura access token at ${source}.`, "Run `oura-cli login` or set OURA_TOKEN.");
@@ -1559,7 +1594,8 @@ class OuraClient {
       const params = new URLSearchParams(query);
       if (nextToken)
         params.set("next_token", nextToken);
-      const page = await this.getPage(`${BASE_URL}/${endpoint}?${params}`);
+      const page = await this.getPage(endpoint, `${BASE_URL}/${endpoint}?${params}`);
+      this.onPage?.({ endpoint, rows: page.data.length });
       for (const row of page.data)
         rows.push(row);
       nextToken = page.next_token;
@@ -1571,17 +1607,38 @@ class OuraClient {
     } while (nextToken);
     return rows;
   }
-  async getPage(url) {
-    const response = await fetch(url, {
-      headers: { Authorization: `Bearer ${this.token}` }
-    });
+  async request(url) {
+    try {
+      return await fetch(url, { headers: { Authorization: `Bearer ${this.token}` } });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new CliError("API_ERROR", `Could not reach the Oura API: ${msg}`, "Check the network connection and try again.");
+    }
+  }
+  async getPage(endpoint, url) {
+    let response = await this.request(url);
+    let retries = 0;
+    for (;response.status === 429 && retries < RETRY_LIMIT; retries++) {
+      const waitMs = retryDelayMs(response.headers.get("retry-after"), retries);
+      if (this.waitedMs + waitMs > MAX_TOTAL_WAIT_MS)
+        break;
+      await response.body?.cancel();
+      this.waitedMs += waitMs;
+      this.onRetry?.({ endpoint, waitMs, attempt: retries });
+      await this.sleep(waitMs);
+      response = await this.request(url);
+    }
     if (!response.ok) {
       const rawBody = await response.text();
-      const redacted = redactSecrets(rawBody);
+      const redacted = redactSecrets(rawBody).split(this.token).join("[REDACTED]");
       const body = redacted.length > 200 ? redacted.slice(0, 200) + "\u2026 (truncated)" : redacted;
       if (response.status === 401 || response.status === 403) {
         throw new CliError("TOKEN_INVALID", `Oura API ${response.status}: ${body}`, "Run `oura-cli login` with a fresh Personal Access Token, or check OURA_TOKEN.");
       }
+      if (response.status === 429) {
+        const waited = Math.round(this.waitedMs / 1000);
+        throw new CliError("API_ERROR", `Oura API 429: ${body}`, `Rate limited; this page was retried ${retries} time${retries === 1 ? "" : "s"} and the command has waited ${waited} s on 429 answers (the most it will is ${MAX_TOTAL_WAIT_MS / 1000} s). Wait a few minutes and run it again, or ask for a shorter range.`);
+      }
       throw new CliError("API_ERROR", `Oura API ${response.status}: ${body}`);
     }
     let json;
@@ -1591,6 +1648,15 @@ class OuraClient {
       throw new CliError("API_ERROR", "Empty response body from Oura API.");
     }
     const body = json;
+    if (body === null || typeof body !== "object" || Array.isArray(body)) {
+      throw new CliError("API_ERROR", `Oura API returned a malformed body for ${endpoint}: expected an object, got ${kindOf(body)}.`);
+    }
+    if (body.data != null && !Array.isArray(body.data)) {
+      throw new CliError("API_ERROR", `Oura API returned a malformed body for ${endpoint}: expected an array under "data", got ${kindOf(body.data)}.`);
+    }
+    if (body.next_token != null && typeof body.next_token !== "string") {
+      throw new CliError("API_ERROR", `Oura API returned a malformed body for ${endpoint}: expected a string or null under "next_token", got ${kindOf(body.next_token)}.`);
+    }
     return { data: body.data ?? [], next_token: body.next_token ?? null };
   }
 }
@@ -1685,6 +1751,45 @@ function formatFromArgv(argv, isTty) {
   }
 }
 
+// src/lib/progress.ts
+function pageProgress(sink, verb) {
+  let endpoint;
+  let pages = 0;
+  let rows = 0;
+  let widest = 0;
+  let written = false;
+  const show = (text) => {
+    widest = Math.max(widest, text.length);
+    written = true;
+    sink.write(`\r${text}`);
+  };
+  const status = () => pages === 0 ? `  ${verb} ${endpoint}` : `  ${verb} ${endpoint}: page ${pages}, ${rows} rows so far`;
+  return {
+    onPage(page) {
+      if (page.endpoint !== endpoint) {
+        endpoint = page.endpoint;
+        pages = 0;
+        rows = 0;
+      }
+      pages++;
+      rows += page.rows;
+      show(`${status()}\u2026`);
+    },
+    onRetry(retry) {
+      if (retry.endpoint !== endpoint) {
+        endpoint = retry.endpoint;
+        pages = 0;
+        rows = 0;
+      }
+      show(`${status()}; rate limited, retrying in ${Math.ceil(retry.waitMs / 1000)} s\u2026`);
+    },
+    done() {
+      if (written)
+        sink.write(`\r${" ".repeat(widest)}\r`);
+    }
+  };
+}
+
 // src/lib/time.ts
 function nowUtc() {
   return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
@@ -1794,7 +1899,8 @@ var processIo = {
 `);
   },
   exit: (code) => process.exit(code),
-  isTty: process.stdout.isTTY === true
+  isTty: process.stdout.isTTY === true,
+  progress: process.stderr.isTTY ? process.stderr : undefined
 };
 var camel = (s) => s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
 function assertKnownArgs(declared, args) {
@@ -1815,7 +1921,7 @@ function assertKnownArgs(declared, args) {
   const unknown = Object.keys(args).filter((k) => !known.has(k));
   if (unknown.length > 0) {
     const flags = unknown.map((f) => f.length === 1 ? `-${f}` : `--${f}`).join(", ");
-    const hint = unknown.every((f) => f.length === 1) ? 'oura-cli has no single-letter flags; a value that starts with "-" must come after "--".' : "Run the command with --help to see its flags.";
+    const hint = unknown.every((f) => f.length === 1) ? 'oura-cli has no single-letter flags other than -v and -h; a value that starts with "-" must come after "--".' : "Run the command with --help to see its flags.";
     throw new CliError("BAD_ARGS", `Unknown flag${unknown.length > 1 ? "s" : ""}: ${flags}.`, hint);
   }
   const extra = (args._ ?? []).slice(positionals);
@@ -1834,16 +1940,25 @@ async function execute(def, args, io = processIo) {
     assertKnownArgs({ ...commonArgs, ...def.args ?? {} }, args);
     const outputFormat = def.jsonOnly ? "json" : format;
     const tz = assertTimezone(args.tz ?? resolveDefaultTimezone());
-    const ctx = { format: outputFormat, tz, today: today(tz) };
+    const ctx = { format: outputFormat, tz, today: today(tz), ...io.progress ? { progress: io.progress } : {} };
     if (def.needs?.db) {
       db = openDatabase(args.db);
       ensureSchema(db);
       ctx.db = db;
     }
+    const progress = def.needs?.client && io.progress ? pageProgress(io.progress, "syncing") : undefined;
     if (def.needs?.client) {
-      ctx.client = new OuraClient(args.token ? { token: args.token } : {});
+      ctx.client = new OuraClient({
+        ...args.token ? { token: args.token } : {},
+        ...progress ? { onPage: progress.onPage, onRetry: progress.onRetry } : {}
+      });
+    }
+    let out;
+    try {
+      out = await def.run(ctx, args);
+    } finally {
+      progress?.done();
     }
-    const out = await def.run(ctx, args);
     io.stdout(outputFormat === "json" ? JSON.stringify(out.json, null, 2) : out.text());
     exitCode = out.exitCode ?? 0;
   } catch (raw) {
@@ -2442,18 +2557,19 @@ function rangeQueries(c, start, end, tz) {
 async function fetchCollectionByPiece(client, c, start, end, tz) {
   const pieces = [];
   for (const query of rangeQueries(c, start, end, tz)) {
-    pieces.push(await client.fetch(c.endpoint, query));
+    pieces.push({ query, rows: await client.fetch(c.endpoint, query) });
   }
   return pieces;
 }
 async function fetchCollection(client, c, start, end, tz) {
-  return (await fetchCollectionByPiece(client, c, start, end, tz)).flat();
+  return (await fetchCollectionByPiece(client, c, start, end, tz)).flatMap((p) => p.rows);
 }
 
 // src/commands/describe.ts
 var OUTPUT_SCHEMAS = { doctor: "docs/schemas/doctor.json", describe: "docs/schemas/describe.json" };
 var ENUM_ARGS = {
   fetch: { collection: names() },
+  rows: { collection: names() },
   report: { period: ["week", "month"] }
 };
 function resolved(def) {
@@ -2556,6 +2672,19 @@ var KEY_SEPARATOR = "\x00";
 function emptyPlan() {
   return { added: 0, stale: [], refused: 0, bypassed: 0 };
 }
+function requestedRange(c, query) {
+  if (c.rangeParams === "datetime") {
+    const from = Date.parse(query.start_datetime ?? "");
+    const to = Date.parse(query.end_datetime ?? "");
+    return (value) => {
+      const t = Date.parse(value);
+      return t >= from && t <= to;
+    };
+  }
+  const from = query.start_date;
+  const to = query.end_date;
+  return (value) => from !== undefined && to !== undefined && value >= from && value <= to;
+}
 function keyOf(values) {
   return values.map((v) => String(v)).join(KEY_SEPARATOR);
 }
@@ -2570,12 +2699,13 @@ function planWindow(db, c, pieces, options = {}) {
   if (scopePick === undefined || identityPicks.some((p) => p === undefined))
     return emptyPlan();
   const keyFor = (row) => keyOf(identityPicks.map((pick) => pick(row)));
-  const wanted = new Set(pieces.flat().map(keyFor));
+  const wanted = new Set(pieces.flatMap((p) => p.rows).map(keyFor));
   const plan = emptyPlan();
   const judged = pieces.map((piece) => {
-    if (piece.length === 0)
+    if (piece.rows.length === 0)
       return null;
-    const scopeValues = piece.map((row) => scopePick(row)).filter((v) => v !== null && v !== undefined).map(String);
+    const inRequested = requestedRange(c, piece.query);
+    const scopeValues = piece.rows.map((row) => scopePick(row)).filter((v) => v !== null && v !== undefined).map(String).filter(inRequested);
     if (scopeValues.length === 0)
       return null;
     const days = [...new Set(scopeValues)];
@@ -2591,7 +2721,7 @@ function planWindow(db, c, pieces, options = {}) {
         stale.push(values);
     }
     const looksTruncated = stale.length > ALWAYS_SAFE_TO_REMOVE && stale.length > stored.length * MAX_REMOVED_SHARE;
-    const fresh = [...new Set(piece.map(keyFor))].filter((key) => !storedKeys.has(key));
+    const fresh = [...new Set(piece.rows.map(keyFor))].filter((key) => !storedKeys.has(key));
     return { stale, looksTruncated, fresh };
   });
   const doubted = new Set;
@@ -2677,9 +2807,9 @@ async function importDaily(db, client, clock, log, window = {}, options = {}) {
   const mayPrune = (name) => options.prune === "all" || (options.prune?.includes(name) ?? false);
   for (const { c, start } of plan) {
     const returned = await fetchCollectionByPiece(client, c, start, end, tz);
-    const pieces = returned.map((piece) => piece.filter((r) => hasIdentity(c, r)));
-    const rows = pieces.flat();
-    const missing = returned.flat().length - rows.length;
+    const pieces = returned.map((piece) => ({ ...piece, rows: piece.rows.filter((r) => hasIdentity(c, r)) }));
+    const rows = pieces.flatMap((p) => p.rows);
+    const missing = returned.flatMap((p) => p.rows).length - rows.length;
     if (missing > 0)
       dropped[c.table] = missing;
     const droppedTail = missing > 0 ? `, ${missing} dropped (no ${identityColumns(c).join("/")})` : "";
@@ -2717,7 +2847,7 @@ async function importDaily(db, client, clock, log, window = {}, options = {}) {
     const { windowPlan, gone } = db.transaction((ps) => {
       const windowPlan = planWindow(db, c, ps, { prune: mayPrune(c.name) });
       for (const piece of ps)
-        for (const r of piece)
+        for (const r of piece.rows)
           stmt.run(...rowValues(c, r));
       return { windowPlan, gone: applyWindowPlan(db, c, windowPlan) };
     }).immediate(pieces);
@@ -2821,7 +2951,7 @@ function getTrends(db, days, today) {
 function getStats(db, today) {
   const tables = COLLECTIONS.map((c) => {
     const row = db.query(`SELECT COUNT(*) as cnt FROM ${c.table}`).get();
-    return { table: c.table, rows: row.cnt };
+    return { collection: c.name, table: c.table, rows: row.cnt };
   });
   const range = db.query("SELECT MIN(day) as first, MAX(day) as last FROM daily_sleep").get();
   const trends = getTrends(db, 99999, today);
@@ -2857,7 +2987,28 @@ function padRight(text, width) {
 
 // src/lib/terminal.ts
 function terminalWidth() {
-  return process.stdout.isTTY && process.stdout.columns ? process.stdout.columns : 80;
+  return screenWidth() ?? 80;
+}
+function screenWidth() {
+  return process.stdout.isTTY && process.stdout.columns ? process.stdout.columns : undefined;
+}
+
+// src/render/rule.ts
+init_source();
+var INDENT = "  ";
+function rule(width, glyph = "\u2500", max = screenWidth()) {
+  const drawn = max === undefined ? width : Math.max(0, Math.min(width, max - INDENT.length));
+  return drawn === 0 ? "" : source_default.gray(INDENT + glyph.repeat(drawn));
+}
+var PLACEHOLDER = "<rule ";
+var RULE = `${PLACEHOLDER}\u2500>`;
+var DOUBLE_RULE = `${PLACEHOLDER}\u2550>`;
+function finish(lines, max = screenWidth()) {
+  let widest = 0;
+  for (const l of lines)
+    if (!l.startsWith(PLACEHOLDER))
+      widest = Math.max(widest, visibleWidth(l) - INDENT.length);
+  return lines.map((l) => l.startsWith(PLACEHOLDER) ? rule(widest, l.slice(PLACEHOLDER.length, -1), max) : l);
 }
 
 // src/render/format.ts
@@ -2882,19 +3033,19 @@ function formatDaySummary(summary, format, emptyHint) {
   if (format === "json")
     return JSON.stringify(summary, null, 2);
   if (emptyHint && isEmptyDay(summary)) {
-    return [
+    return finish([
       "",
       source_default.bold(`  ${summary.day}`),
-      source_default.gray("\u2500".repeat(50)),
+      RULE,
       `  No Oura data for ${summary.day} yet.`,
       `  ${emptyHint}`
-    ].join(`
+    ]).join(`
 `);
   }
   const lines = [
     "",
-    source_default.bold(`  ${summary.day}`),
-    source_default.gray("\u2500".repeat(50)),
+    source_default.bold(`  ${summary.partial ? `${summary.day}*` : summary.day}`),
+    RULE,
     `  Sleep:     ${scoreColor(summary.sleep_score)}    Readiness: ${scoreColor(summary.readiness_score)}    Activity: ${scoreColor(summary.activity_score)}`,
     `  Steps:     ${summary.steps ?? source_default.gray("\u2014")}`
   ];
@@ -2911,9 +3062,13 @@ function formatDaySummary(summary, format, emptyHint) {
     lines.push(`  Sleep:     ${fmtHours(summary.sleep_hours)} total | ${fmtHours(summary.deep_hours)} deep | ${fmtHours(summary.rem_hours)} REM`);
     lines.push(`  HRV:       ${summary.avg_hrv ?? "\u2014"}    Lowest HR: ${summary.lowest_hr ?? "\u2014"}    Efficiency: ${summary.efficiency ?? "\u2014"}%`);
   }
-  return lines.join(`
+  if (summary.partial)
+    lines.push("", PARTIAL_NOTE);
+  return finish(lines).join(`
 `);
 }
+var PARTIAL_NOTE = "  * activity totals are not final.";
+var PUBLISH_DELAY_NOTE = "Oura publishes a day's summary after that night's sleep syncs from the ring.";
 var SUMMARY_INDENT = 4;
 var SUMMARY_GAP = 2;
 var SUMMARY_MAX_COLUMNS = 4;
@@ -2956,10 +3111,10 @@ function formatWeekTable(days, format, emptyHint) {
     ].join(`
 `);
   }
-  const header = `${"Day".padEnd(12)} ${"Sleep".padStart(6)} ${"Ready".padStart(6)} ${"Activity".padStart(9)} ${"Steps".padStart(7)} ${"Stress".padEnd(10)}`;
-  const sep = source_default.gray("\u2500".repeat(56));
-  const rows = days.map((d) => `${padRight(d.partial ? `${d.day}*` : d.day, 12)} ${padLeft(scoreColor(d.sleep_score), 6)} ${padLeft(scoreColor(d.readiness_score), 6)} ` + `${padLeft(scoreColor(d.activity_score), 9)} ${padLeft(String(d.steps ?? "\u2014"), 7)} ${padRight(d.stress ?? "\u2014", 10)}`);
-  const note = days.some((d) => d.partial) ? ["  * still accumulating; its activity totals are not final."] : [];
+  const header = `${"Day".padEnd(12)} ${"Sleep".padStart(6)} ${"Ready".padStart(6)} ${"Activity".padStart(9)} ${"Steps".padStart(7)} Stress`;
+  const rows = days.map((d) => `${padRight(d.partial ? `${d.day}*` : d.day, 12)} ${padLeft(scoreColor(d.sleep_score), 6)} ${padLeft(scoreColor(d.readiness_score), 6)} ` + `${padLeft(scoreColor(d.activity_score), 9)} ${padLeft(String(d.steps ?? "\u2014"), 7)} ${d.stress ?? "\u2014"}`);
+  const sep = rule(Math.max(visibleWidth(header), ...rows.map(visibleWidth)));
+  const note = days.some((d) => d.partial) ? [PARTIAL_NOTE] : [];
   return [`
   Last 7 Days`, sep, `  ${header}`, sep, ...rows.map((r) => `  ${r}`), ...note].join(`
 `);
@@ -2970,14 +3125,14 @@ function formatTrends(trends, days, format, emptyHint) {
   const lines = [
     "",
     source_default.bold(`  Trends: last ${days} days`),
-    source_default.gray("\u2500".repeat(50))
+    RULE
   ];
   if (emptyHint && trends.length === 0)
     lines.push(`  No Oura data for the last ${days} days yet.`, `  ${emptyHint}`);
   for (const t of trends) {
     lines.push(`  ${t.label.padEnd(15)} avg: ${String(t.avg).padStart(5)}  min: ${String(t.min).padStart(5)}  max: ${String(t.max).padStart(5)}  (${t.count} days)`);
   }
-  return lines.join(`
+  return finish(lines).join(`
 `);
 }
 function formatStats(stats, format, emptyHint) {
@@ -2986,15 +3141,18 @@ function formatStats(stats, format, emptyHint) {
   const lines = [
     "",
     source_default.bold("  Database Statistics"),
-    source_default.gray("\u2550".repeat(50))
+    DOUBLE_RULE
   ];
   if (emptyHint && stats.tables.every((t) => t.rows === 0)) {
-    return [...lines, "  No Oura data in the database yet.", `  ${emptyHint}`].join(`
+    return finish([...lines, "  No Oura data in the database yet.", `  ${emptyHint}`]).join(`
 `);
   }
   for (const t of stats.tables) {
-    lines.push(`  ${t.table.padEnd(22)} ${String(t.rows).padStart(8)} rows`);
+    lines.push(`  ${`${t.collection} (${t.table})`.padEnd(38)} ${String(t.rows).padStart(8)} row${t.rows === 1 ? "" : "s"}`);
   }
+  const noDailyData = stats.dateRange.first === null && stats.trends.length === 0 && stats.records.mostSteps === null && stats.records.bestSleep === null;
+  if (emptyHint && noDailyData)
+    lines.push("", "  No daily summaries in the database yet.", `  ${emptyHint}`);
   if (stats.dateRange.first) {
     lines.push(`
   Date range: ${stats.dateRange.first} \u2192 ${stats.dateRange.last}`);
@@ -3009,7 +3167,7 @@ function formatStats(stats, format, emptyHint) {
   if (stats.records.bestSleep) {
     lines.push(`  Best sleep:  ${stats.records.bestSleep.score} on ${stats.records.bestSleep.day}`);
   }
-  return lines.join(`
+  return finish(lines).join(`
 `);
 }
 
@@ -3047,6 +3205,7 @@ function resolvePruneScope(value) {
   }
   return [...new Set(wanted)];
 }
+var TODAY_HINT_AFTER_SYNC = `${PUBLISH_DELAY_NOTE} Run \`oura-cli sync\` again later.`;
 async function runSync(ctx, window = {}, options = {}) {
   const lines = [];
   const log = ctx.format === "table" ? (m) => lines.push(m) : undefined;
@@ -3054,7 +3213,7 @@ async function runSync(ctx, window = {}, options = {}) {
   const today = getDaySummary(ctx.db, ctx.today, dayCompleteness(ctx.db, ctx.today));
   return {
     json: { import: importResult, today },
-    text: () => [...lines, formatImportSummary(importResult), formatDaySummary(today, "table")].join(`
+    text: () => [...lines, formatImportSummary(importResult), formatDaySummary(today, "table", TODAY_HINT_AFTER_SYNC)].join(`
 `)
   };
 }
@@ -3064,15 +3223,171 @@ var syncArgs = {
   prune: { type: "string", description: "Apply removals sync kept back: --prune=hr, a list, or --prune=all" }
 };
 var syncDef = {
-  meta: { name: "sync", description: "Import latest data from Oura API and return today's summary" },
+  meta: { name: "sync", description: "Download new Oura data into the local cache and report what each collection fetched" },
   args: syncArgs,
   needs: { db: true, client: true },
   run: (ctx, args) => runSync(ctx, resolveWindow({ from: args.from, to: args.to }, ctx.today), { prune: resolvePruneScope(args.prune) })
 };
 var syncCommand = dataCommand(syncDef);
 
+// src/db/rows.ts
+function getRows(db, c, range, tz) {
+  const cols = c.columns.map((k) => k.name);
+  if (range !== null && !cols.includes("day"))
+    throw new Error(`getRows: ${c.name} has no day column to bound a range on.`);
+  const order = [...new Set([...cols.includes("day") ? ["day"] : [], ...identityColumns(c)])].join(", ");
+  const select = `SELECT ${cols.join(", ")} FROM ${c.table}`;
+  if (range === null)
+    return db.query(`${select} ORDER BY ${order}`).all();
+  const between = db.query(`${select} WHERE day BETWEEN ? AND ? ORDER BY ${order}`);
+  if (c.rangeParams !== "datetime")
+    return between.all(range.start, range.end);
+  const fromMs = Date.parse(localDateToUtcRange(range.start, tz)[0]);
+  const toMs = Date.parse(localDateToUtcRange(range.end, tz)[1]);
+  const instant = (r) => Date.parse(String(r.timestamp));
+  return between.all(shiftDay(range.start, -1), shiftDay(range.end, 1)).filter((r) => {
+    const t = instant(r);
+    return t >= fromMs && t < toMs;
+  }).sort((a, b) => instant(a) - instant(b));
+}
+
+// src/render/format-rows.ts
+init_source();
+var MAX_CELL = 40;
+var MIN_CELL = 8;
+var GAP = 2;
+function printable(value) {
+  if (value === null)
+    return "\u2014";
+  return String(value).replace(/\r\n|\r|\n/g, "\u23CE").replace(/[\u0000-\u001f\u007f]/g, " ");
+}
+function clip(text, width) {
+  return text.length > width ? `${text.slice(0, Math.max(0, width - 1))}\u2026` : text;
+}
+function widest(values, floor = 0) {
+  let out = floor;
+  for (const v of values)
+    if (v > out)
+      out = v;
+  return out;
+}
+function fit(natural, floors, available) {
+  const out = [...natural];
+  while (out.reduce((sum, w) => sum + w, 0) > available) {
+    let target = -1;
+    for (let i = 0;i < out.length; i++) {
+      if (out[i] > floors[i] && (target === -1 || out[i] > out[target]))
+        target = i;
+    }
+    if (target === -1)
+      return null;
+    out[target]--;
+  }
+  return out;
+}
+function records(names, texts, max) {
+  const nameW = widest(names.map(visibleWidth));
+  const valueW = max === undefined ? Number.POSITIVE_INFINITY : Math.max(MIN_CELL, max - INDENT.length - nameW - GAP);
+  const lines = [];
+  texts.forEach((row, r) => {
+    if (r > 0)
+      lines.push("");
+    names.forEach((name, i) => lines.push(`${INDENT}${padRight(name, nameW)}${" ".repeat(GAP)}${clip(row[i], valueW)}`.trimEnd()));
+  });
+  return lines;
+}
+function formatRows(c, rows, scope, format, emptyHint, max = screenWidth(), total = rows.length) {
+  if (format === "json")
+    return JSON.stringify(rows, null, 2);
+  const all = Math.max(total, rows.length);
+  const count = rows.length === all ? `${all} row${all === 1 ? "" : "s"}` : `${rows.length} of ${all} rows`;
+  const title = source_default.bold(`  ${c.name} (${c.table}): ${count}${scope}`);
+  if (rows.length === 0) {
+    return finish(["", title, RULE, `  No cached ${c.name} rows${scope}.`, `  ${emptyHint}`], max).join(`
+`);
+  }
+  const names = c.columns.map((k) => k.name);
+  const numeric = new Set(c.columns.filter((k) => k.type !== "TEXT").map((k) => k.name));
+  const texts = rows.map((r) => names.map((name) => clip(printable(r[name] ?? null), MAX_CELL)));
+  const headers = names.map(visibleWidth);
+  const natural = names.map((_, i) => widest(texts.map((row) => visibleWidth(row[i])), headers[i]));
+  const gaps = GAP * (names.length - 1);
+  const widths = max === undefined ? natural : fit(natural, headers.map((h) => Math.max(h, MIN_CELL)), max - INDENT.length - gaps);
+  if (widths === null)
+    return finish(["", title, RULE, ...records(names, texts, max)], max).join(`
+`);
+  const line = (parts) => `${INDENT}${parts.map((p, i) => numeric.has(names[i]) ? padLeft(clip(p, widths[i]), widths[i]) : padRight(clip(p, widths[i]), widths[i])).join(" ".repeat(GAP))}`.trimEnd();
+  return finish(["", title, RULE, line(names), RULE, ...texts.map(line)], max).join(`
+`);
+}
+
+// src/commands/fetch.ts
+function resolveRange(opts) {
+  const modes = [opts.day !== undefined, opts.from !== undefined || opts.to !== undefined, opts.days !== undefined].filter(Boolean).length;
+  if (modes > 1)
+    throw new CliError("BAD_ARGS", "Use only one of --day, --from/--to, or --days.");
+  if (opts.day !== undefined) {
+    const d = assertCalendarDate(opts.day, "--day");
+    return { start: d, end: d };
+  }
+  if (opts.from !== undefined || opts.to !== undefined) {
+    if (opts.from === undefined || opts.to === undefined)
+      throw new CliError("BAD_ARGS", "--from and --to must be given together.");
+    const start = assertCalendarDate(opts.from, "--from");
+    const end = assertCalendarDate(opts.to, "--to");
+    if (start > end)
+      throw new CliError("BAD_ARGS", `--from (${start}) must not be after --to (${end}).`);
+    return { start, end };
+  }
+  if (opts.days !== undefined) {
+    const n = assertPositiveInt(opts.days, "--days");
+    return { start: shiftDay(opts.today, -(n - 1)), end: opts.today };
+  }
+  return { start: opts.today, end: opts.today };
+}
+function assertRangeAllowed(c, opts) {
+  if (c.rangeParams === "none" && [opts.day, opts.from, opts.to, opts.days].some((v) => v !== undefined)) {
+    throw new CliError("BAD_ARGS", `"${c.name}" is a snapshot, not a day range; it takes no --day, --from/--to or --days.`);
+  }
+}
+var fetchCommand = dataCommand({
+  meta: { name: "fetch", description: "Fetch raw records for one Oura collection straight from the API (JSON)." },
+  args: {
+    collection: { type: "positional", required: true, description: `Collection: ${names().join(" | ")} (ring is a snapshot and takes no range flags)` },
+    day: { type: "string", description: "Single day (YYYY-MM-DD). Default: today." },
+    from: { type: "string", description: "Range start (YYYY-MM-DD); requires --to" },
+    to: { type: "string", description: "Range end (YYYY-MM-DD); requires --from" },
+    days: { type: "string", description: "Last N days ending today" }
+  },
+  jsonOnly: true,
+  async run(ctx, args) {
+    const c = byName(args.collection);
+    if (!c)
+      throw new CliError("BAD_ARGS", `Unknown collection "${args.collection}".`, `Valid collections: ${names().join(", ")}`);
+    const opts = {
+      day: args.day,
+      from: args.from,
+      to: args.to,
+      days: args.days
+    };
+    assertRangeAllowed(c, opts);
+    const { start, end } = resolveRange({ ...opts, today: ctx.today });
+    const progress = ctx.progress ? pageProgress(ctx.progress, "fetching") : undefined;
+    const client = new OuraClient({
+      ...args.token ? { token: args.token } : {},
+      ...progress ? { onPage: progress.onPage, onRetry: progress.onRetry } : {}
+    });
+    try {
+      const data = await fetchCollection(client, c, start, end, ctx.tz);
+      return { json: data, text: () => JSON.stringify(data, null, 2) };
+    } finally {
+      progress?.done();
+    }
+  }
+});
+
 // src/commands/db.ts
-var SYNC_HINT = "Run `oura-cli sync` to download your data. Oura publishes a day's summary after that night's sleep syncs from the ring.";
+var SYNC_HINT = `Run \`oura-cli sync\` to download your data. ${PUBLISH_DELAY_NOTE}`;
 var dbCommand = defineCommand({
   meta: { name: "db", description: "Query and manage the local SQLite database" },
   subCommands: {
@@ -3120,6 +3435,37 @@ var dbCommand = defineCommand({
         const stats = getStats(ctx.db, ctx.today);
         return { json: stats, text: () => formatStats(stats, "table", "Run `oura-cli sync`, then `oura-cli db stats` again.") };
       }
+    }),
+    rows: dataCommand({
+      meta: { name: "rows", description: "Cached rows of one collection, as stored: the local twin of `fetch`" },
+      args: {
+        collection: { type: "positional", required: true, description: `Collection: ${names().join(" | ")} (ring is a snapshot and takes no range flags)` },
+        day: { type: "string", description: "Single day (YYYY-MM-DD). Default: today." },
+        from: { type: "string", description: "Range start (YYYY-MM-DD); requires --to" },
+        to: { type: "string", description: "Range end (YYYY-MM-DD); requires --from" },
+        days: { type: "string", description: "Last N days ending today" },
+        limit: { type: "string", description: "Print at most N rows, the earliest first (a day of heart rate is hundreds)" }
+      },
+      needs: { db: true },
+      run(ctx, args) {
+        const c = byName(String(args.collection));
+        if (!c)
+          throw new CliError("BAD_ARGS", `Unknown collection "${args.collection}".`, `Valid collections: ${names().join(", ")}`);
+        const opts = {
+          day: args.day,
+          from: args.from,
+          to: args.to,
+          days: args.days
+        };
+        assertRangeAllowed(c, opts);
+        const range = c.rangeParams === "none" ? null : resolveRange({ ...opts, today: ctx.today });
+        const limit = args.limit === undefined ? undefined : assertPositiveInt(String(args.limit), "--limit");
+        const all = getRows(ctx.db, c, range, ctx.tz);
+        const rows = limit === undefined ? all : all.slice(0, limit);
+        const scope = range === null ? "" : range.start === range.end ? ` for ${range.start}` : ` for ${range.start} \u2192 ${range.end}`;
+        const hint = range === null ? `Run \`oura-cli sync\` to fill the cache, or \`oura-cli fetch ${c.name}\` to read the API.` : `Run \`oura-cli sync\` (\`sync --from <day>\` for older days), or \`oura-cli fetch ${c.name}\` to read the API.`;
+        return { json: rows, text: () => formatRows(c, rows, scope, "table", hint, undefined, all.length) };
+      }
     })
   }
 });
@@ -3286,7 +3632,7 @@ function partialDayNote(data, bucket) {
     return null;
   const which = bucket ? `the week of ${bucket.weekOf}` : partial.day === data.weekEnd ? "today" : partial.dayLabel;
   const covers = data.completeThrough ? `through ${data.completeThrough}` : "no complete day yet";
-  return `  * ${which} is still accumulating; activity averages cover ${covers}.`;
+  return `  * ${which}: activity totals are not final; averages cover ${covers}.`;
 }
 function formatReport(data, format, period) {
   if (format === "json")
@@ -3314,25 +3660,21 @@ function formatReport(data, format, period) {
   }
   if (period === "week") {
     lines.push(source_default.bold("  Last 7 Days:"));
-    lines.push(source_default.gray("  " + "\u2500".repeat(52)));
-    lines.push(`  ${"Day".padEnd(10)} ${"Sleep".padStart(6)} ${"Ready".padStart(6)} ${"Active".padStart(7)} ${"Steps".padStart(8)}`);
-    lines.push(source_default.gray("  " + "\u2500".repeat(52)));
+    const table = [RULE, `  ${"Day".padEnd(10)} ${"Sleep".padStart(6)} ${"Ready".padStart(6)} ${"Active".padStart(7)} ${"Steps".padStart(8)}`, RULE];
     for (const d of data.days) {
-      lines.push(`  ${(d.partial ? d.dayLabel + "*" : d.dayLabel).padEnd(10)} ${scoreCell(d.sleep, 6)} ${scoreCell(d.readiness, 6)} ${scoreCell(d.activity, 7)} ${stepsCell(d.steps, 8)}`);
+      table.push(`  ${(d.partial ? d.dayLabel + "*" : d.dayLabel).padEnd(10)} ${scoreCell(d.sleep, 6)} ${scoreCell(d.readiness, 6)} ${scoreCell(d.activity, 7)} ${stepsCell(d.steps, 8)}`);
     }
-    lines.push("");
+    lines.push(...finish(table), "");
   } else {
     lines.push(source_default.bold("  Last 30 Days:"));
-    lines.push(source_default.gray("  " + "\u2500".repeat(69)));
-    lines.push(`  ${"Week of".padEnd(21)} ${"Sleep".padStart(6)} ${"Ready".padStart(6)} ${"Active".padStart(7)} ${"Steps".padStart(10)}`);
-    lines.push(source_default.gray("  " + "\u2500".repeat(69)));
+    const table = [RULE, `  ${"Week of".padEnd(21)} ${"Sleep".padStart(6)} ${"Ready".padStart(6)} ${"Active".padStart(7)} ${"Steps".padStart(10)}`, RULE];
     for (const b of buckets) {
       const avgSleepInt = b.avgSleep !== null ? Math.round(b.avgSleep) : null;
       const avgReadyInt = b.avgReadiness !== null ? Math.round(b.avgReadiness) : null;
       const avgActiveInt = b.avgActivity !== null ? Math.round(b.avgActivity) : null;
-      lines.push(`  ${bucketLabel(b).padEnd(21)} ${scoreCell(avgSleepInt, 6)} ${scoreCell(avgReadyInt, 6)} ${scoreCell(avgActiveInt, 7)} ${stepsCell(b.totalSteps, 10)}`);
+      table.push(`  ${bucketLabel(b).padEnd(21)} ${scoreCell(avgSleepInt, 6)} ${scoreCell(avgReadyInt, 6)} ${scoreCell(avgActiveInt, 7)} ${stepsCell(b.totalSteps, 10)}`);
     }
-    lines.push("");
+    lines.push(...finish(table), "");
   }
   lines.push(source_default.bold("  Averages (this period vs previous):"));
   for (const a of data.averages) {
@@ -3432,14 +3774,14 @@ function statusSymbol(status) {
   return source_default.red("\u2717");
 }
 function formatDoctorTable(result) {
-  const lines = ["", source_default.bold("  Doctor"), source_default.gray("\u2500".repeat(50))];
+  const lines = ["", source_default.bold("  Doctor"), RULE];
   for (const c of result.checks) {
     lines.push(`  ${statusSymbol(c.status)} ${c.id.padEnd(12)} ${c.detail}`);
   }
   lines.push("");
   const next = result.nextStep ?? (result.ok ? "nothing \u2014 everything looks healthy." : "see the failing checks above.");
   lines.push(`  Next: ${next}`);
-  return lines.join(`
+  return finish(lines).join(`
 `);
 }
 
@@ -3466,7 +3808,7 @@ async function runChecks(deps) {
         checks.push({ id: "token-valid", status: "fail", detail: err.message, fix: "oura-cli login" });
       } else {
         const msg = err instanceof Error ? err.message : String(err);
-        checks.push({ id: "token-valid", status: "warn", detail: `Could not reach the Oura API: ${msg}` });
+        checks.push({ id: "token-valid", status: "warn", detail: `Could not reach the Oura API: ${msg}`, fix: "Check the network connection and run `oura-cli doctor` again in a few minutes." });
       }
     }
   }
@@ -3494,9 +3836,14 @@ async function runChecks(deps) {
     } else if (!last) {
       checks.push({ id: "data", status: "warn", detail: "No data in the local cache yet.", fix: "oura-cli sync" });
     } else {
-      const ageDays = Math.round((new Date(`${deps.today}T00:00:00Z`).getTime() - new Date(`${last}T00:00:00Z`).getTime()) / 86400000);
-      if (ageDays > 2) {
-        checks.push({ id: "data", status: "warn", detail: `Most recent data is from ${last} (${ageDays} days ago).`, fix: "oura-cli sync" });
+      const hours = hoursSinceDayEnded(last, deps.now, deps.tz);
+      if (hours > STALE_AFTER_HOURS) {
+        checks.push({
+          id: "data",
+          status: "warn",
+          detail: `Most recent data is from ${last}; that day ended over ${Math.floor(hours)} hours ago (the limit is ${STALE_AFTER_HOURS}).`,
+          fix: "oura-cli sync"
+        });
       } else {
         checks.push({ id: "data", status: "ok", detail: `Data current through ${last}.` });
       }
@@ -3521,6 +3868,14 @@ function quickCheck(db) {
   }
 }
 var DATA_TABLES = ["daily_sleep", "daily_readiness", "daily_activity"];
+var STALE_AFTER_HOURS = 36;
+function hoursSinceDayEnded(day, now, tz) {
+  const ended = Date.parse(localDateToUtcRange(day, tz)[1]);
+  const hours = (Date.parse(now) - ended) / 3600000;
+  if (!Number.isFinite(hours))
+    throw new Error(`hoursSinceDayEnded: cannot place ${JSON.stringify(now)} against day ${day}.`);
+  return hours;
+}
 function latestDataDay(db) {
   let latest = null;
   for (const tbl of DATA_TABLES) {
@@ -3549,7 +3904,9 @@ async function runDoctor(ctx, args) {
     },
     createClient: (token) => new OuraClient({ token }),
     offline: args.offline === true,
-    today: ctx.today
+    today: ctx.today,
+    now: nowUtc(),
+    tz: ctx.tz
   };
   const result = await runChecks(deps);
   return {
@@ -3603,63 +3960,6 @@ function manifestCommand(version, getCommands) {
   });
 }
 
-// src/commands/fetch.ts
-function resolveRange(opts) {
-  const modes = [opts.day !== undefined, opts.from !== undefined || opts.to !== undefined, opts.days !== undefined].filter(Boolean).length;
-  if (modes > 1)
-    throw new CliError("BAD_ARGS", "Use only one of --day, --from/--to, or --days.");
-  if (opts.day !== undefined) {
-    const d = assertCalendarDate(opts.day, "--day");
-    return { start: d, end: d };
-  }
-  if (opts.from !== undefined || opts.to !== undefined) {
-    if (opts.from === undefined || opts.to === undefined)
-      throw new CliError("BAD_ARGS", "--from and --to must be given together.");
-    const start = assertCalendarDate(opts.from, "--from");
-    const end = assertCalendarDate(opts.to, "--to");
-    if (start > end)
-      throw new CliError("BAD_ARGS", `--from (${start}) must not be after --to (${end}).`);
-    return { start, end };
-  }
-  if (opts.days !== undefined) {
-    const n = assertPositiveInt(opts.days, "--days");
-    return { start: shiftDay(opts.today, -(n - 1)), end: opts.today };
-  }
-  return { start: opts.today, end: opts.today };
-}
-function assertRangeAllowed(c, opts) {
-  if (c.rangeParams === "none" && [opts.day, opts.from, opts.to, opts.days].some((v) => v !== undefined)) {
-    throw new CliError("BAD_ARGS", `"${c.name}" is a snapshot, not a day range; it takes no --day, --from/--to or --days.`);
-  }
-}
-var fetchCommand = dataCommand({
-  meta: { name: "fetch", description: "Fetch raw records for one Oura collection straight from the API (JSON)." },
-  args: {
-    collection: { type: "positional", required: true, description: `Collection: ${names().join(" | ")} (ring is a snapshot and takes no range flags)` },
-    day: { type: "string", description: "Single day (YYYY-MM-DD). Default: today." },
-    from: { type: "string", description: "Range start (YYYY-MM-DD); requires --to" },
-    to: { type: "string", description: "Range end (YYYY-MM-DD); requires --from" },
-    days: { type: "string", description: "Last N days ending today" }
-  },
-  jsonOnly: true,
-  async run(ctx, args) {
-    const c = byName(args.collection);
-    if (!c)
-      throw new CliError("BAD_ARGS", `Unknown collection "${args.collection}".`, `Valid collections: ${names().join(", ")}`);
-    const opts = {
-      day: args.day,
-      from: args.from,
-      to: args.to,
-      days: args.days
-    };
-    assertRangeAllowed(c, opts);
-    const { start, end } = resolveRange({ ...opts, today: ctx.today });
-    const client = new OuraClient(args.token ? { token: args.token } : {});
-    const data = await fetchCollection(client, c, start, end, ctx.tz);
-    return { json: data, text: () => JSON.stringify(data, null, 2) };
-  }
-});
-
 // src/commands/registry.ts
 function buildRegistry(version) {
   const subCommands = Object.assign(Object.create(null), {
@@ -3707,11 +4007,28 @@ function nearestGlobalFlag(token) {
     return;
   return [...GLOBAL_FLAGS_WITH_VALUE].find((flag) => flag !== token && (editDistanceAtMostOne(flag, token) || flag.startsWith(token)));
 }
-function fromCittyError(err, removedCommandHints = {}, rawArgs = []) {
+function commandTokens(rawArgs) {
+  const tokens = [];
+  for (let i = 0;i < rawArgs.length; i++) {
+    const tok = rawArgs[i];
+    if (GLOBAL_FLAGS_WITH_VALUE.has(tok)) {
+      i++;
+      continue;
+    }
+    if (tok.startsWith("-"))
+      continue;
+    tokens.push(tok);
+  }
+  return tokens;
+}
+function fromCittyError(err, removedCommandHints = {}, rawArgs = [], parents = {}) {
   const code = err?.code;
   if (typeof code !== "string")
     return err;
   const message = (err instanceof Error ? err.message : String(err)).replace(ANSI2, "");
+  const first = commandTokens(rawArgs)[0];
+  const parent = first !== undefined && Object.hasOwn(parents, first) ? first : undefined;
+  const parentHelp = parent === undefined ? undefined : `\`oura-cli ${parent}\` takes one of: ${parents[parent].join(", ")}. Run \`oura-cli ${parent} --help\` for details.`;
   switch (code) {
     case "E_UNKNOWN_COMMAND": {
       const name = message.replace(/^Unknown command\s*/, "").trim();
@@ -3720,16 +4037,19 @@ function fromCittyError(err, removedCommandHints = {}, rawArgs = []) {
       if (meant) {
         return new CliError("BAD_ARGS", `Unknown flag "${before}".`, `Did you mean ${meant}? Its value was read as a command name.`);
       }
+      if (parentHelp !== undefined && before !== undefined && GLOBAL_FLAGS_WITH_VALUE.has(before)) {
+        return new CliError("BAD_ARGS", `"${parent}" needs a subcommand.`, parentHelp);
+      }
       if (!COMMAND_NAME.test(name)) {
         return new CliError("BAD_ARGS", "Unknown command.", "A value was read as a command name. Check the flags before it, and run `oura-cli --help` for the list of commands.");
       }
-      const hint = Object.hasOwn(removedCommandHints, name) ? removedCommandHints[name] : "Run `oura-cli --help` for the list of commands.";
+      const hint = Object.hasOwn(removedCommandHints, name) ? removedCommandHints[name] : parentHelp ?? "Run `oura-cli --help` for the list of commands.";
       return new CliError("BAD_ARGS", `Unknown command "${name}".`, hint);
     }
     case "EARG":
       return new CliError("BAD_ARGS", message.endsWith(".") ? message : `${message}.`, "Run the command with --help to see its arguments.");
     case "E_NO_COMMAND":
-      return new CliError("BAD_ARGS", "No command specified.", "Run `oura-cli --help` for the list of commands.");
+      return parentHelp === undefined ? new CliError("BAD_ARGS", "No command specified.", "Run `oura-cli --help` for the list of commands.") : new CliError("BAD_ARGS", `"${parent}" needs a subcommand.`, parentHelp);
     default:
       return err;
   }
@@ -3738,6 +4058,10 @@ function fromCittyError(err, removedCommandHints = {}, rawArgs = []) {
 // src/index.ts
 var VERSION = JSON.parse(readFileSync2(new URL("../package.json", import.meta.url), "utf-8")).version;
 var subCommands = buildRegistry(VERSION);
+var PARENT_COMMANDS = Object.fromEntries(Object.entries(subCommands).flatMap(([name, def]) => {
+  const subs = def.subCommands;
+  return subs !== null && typeof subs === "object" ? [[name, Object.keys(subs)]] : [];
+}));
 var FETCH_HINT = "The per-collection commands were replaced in 0.5.0 by `oura-cli fetch <collection>`, e.g. `oura-cli fetch sleep --day 2026-09-01`. Run `oura-cli fetch --help`.";
 var REMOVED_COMMANDS = {
   reset: "`db reset` was removed in 0.5.0; delete the database file (`--db` / OURA_DB_PATH) and run `oura-cli sync` to rebuild it.",
@@ -3760,14 +4084,16 @@ var main = defineCommand({
   subCommands
 });
 var rawArgs = normalizeArgv(process.argv).slice(2);
-var wantsHelp = rawArgs.some((a) => a === "--help" || a === "-h") || rawArgs.length === 0 && process.stdout.isTTY === true;
+var commands = commandTokens(rawArgs);
+var bareParent = commands.length === 1 && Object.hasOwn(PARENT_COMMANDS, commands[0]);
+var wantsHelp = rawArgs.some((a) => a === "--help" || a === "-h") || (commands.length === 0 || bareParent) && process.stdout.isTTY === true;
 if (isVersionRequest(rawArgs)) {
   console.log(VERSION);
 } else if (wantsHelp) {
-  runMain(main, { rawArgs });
+  runMain(main, { rawArgs: bareParent ? [...rawArgs, "--help"] : rawArgs });
 } else {
   runCommand(main, { rawArgs }).catch((raw) => {
-    const err = fromCittyError(raw, REMOVED_COMMANDS, rawArgs);
+    const err = fromCittyError(raw, REMOVED_COMMANDS, rawArgs, PARENT_COMMANDS);
     emitError(err, formatFromArgv(rawArgs, process.stdout.isTTY === true));
     process.exit(exitCodeFor(err));
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/oura-cli",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Oura Ring CLI — query and analyze Oura Ring health data from the command line, designed for humans and AI agents.",
   "keywords": [
     "oura",