Skip to content

Improve first-run onboarding for human CLI users #28

Description

@drakulavich

Problem

A new Oura user can install the CLI but may not reach a useful first result. The current flow has two critical gaps:

  • oura-cli login uses a visible terminal prompt for a sensitive Personal Access Token.
  • Local commands on a new or empty database render blank score tables rather than explaining that a sync is required.

Goal

A first-time user should securely connect their account and understand the next action at every expected state.

Scope

First increment

  • Replace visible interactive token entry with hidden terminal input.
  • Keep non-interactive login --token behavior for scripts.
  • Add a clear empty state to oura-cli report with a next-step command.
  • Add regression tests for both behaviours.

Follow-up

  • Add empty states to db today and db week.
  • Make first sync explicit about its 30-day default, date range, progress, and result counts.
  • Offer a guided setup or doctor flow that validates the token and guides the first sync.
  • Rewrite the README “first five minutes” around a concrete human outcome and common recovery paths.

Acceptance criteria

  • Interactive token characters are not echoed to the terminal.
  • An empty report tells the user why no insight is available and gives the exact next command.
  • Tests cover the new first-run behaviour.
  • Existing machine-readable output and non-interactive authentication remain compatible.

Out of scope

Changing Oura API coverage, storage format, or the package distribution model.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions