@betterness/cli

Terminal interface for the Betterness health & wellness platform. Access your biomarkers, lab results, wearable data, and more from the command line — or let AI agents work with your health data programmatically.

Installation

npm install -g @betterness/cli

Requires Node.js 20+.

Authentication

OAuth (default)

betterness auth login      # Opens browser for OAuth login
betterness auth whoami     # Verify

The CLI opens a browser window for secure authentication via OAuth. Tokens are stored in ~/.betterness/tokens.json and refreshed automatically.

API Key

Get your API key from either:

• app.betti.bot/settings/betterness-mcp
• betterness.ai/mcp/keys

The same key works for both the CLI and the Betterness MCP server.

betterness auth login --key bk_your_api_key
betterness auth whoami   # verify

You can also set the BETTERNESS_API_KEY environment variable instead of storing credentials.

Credential priority

--api-key flag > BETTERNESS_API_KEY env var > OAuth tokens > stored API key.

Only one auth method is active at a time — logging in with one clears the other.

Quick Start

# Your profile
betterness profile get

# Daily health summary
betterness workflow daily-brief

# Recent biomarker results
betterness biomarkers search --limit 10

# Activity from your wearable
betterness activity get --from 2025-01-01

# Recommended next actions
betterness workflow next-actions

Output Formats

Every command supports three output modes via global flags:

| Flag | Format | Use case | |------|--------|----------| | (default) | Formatted table | Human reading | | --json | JSON | Scripting, piping to jq | | --markdown | Markdown | AI agents, documentation |

betterness biomarkers search --json | jq '.[] | .name'
betterness profile get --markdown

Commands

Profile

betterness profile get                              # View profile
betterness profile update --city "New York" --state NY  # Update fields

Biomarkers & Biological Age

betterness biomarkers search                        # All recent results
betterness biomarkers search --name cholesterol      # Filter by name
betterness biomarkers search --range OUT_OF_RANGE    # Out-of-range only
betterness biomarkers loinc-codes                    # Available LOINC codes
betterness biological-age get                        # Age calculation history

Wearable Data

Requires a connected device (Apple Health, Garmin, Oura, Withings, etc.).

betterness activity get --from 2025-01-01 --to 2025-01-31
betterness sleep get --from 2025-01-01
betterness sleep stages --from 2025-01-01
betterness vitals get --from 2025-01-01
betterness body-composition get --from 2025-01-01

Connected Devices

betterness connected-devices list                    # Active connections
betterness connected-devices available               # Available integrations
betterness connected-devices link --integration-key GARMIN
betterness connected-devices apple-health-code       # Apple HealthKit code
betterness connected-devices disconnect --integration-key OURA

Lab Tests & Orders

# Browse and purchase
betterness lab-tests list --popular
betterness purchases buy --test-key <key> --payment-method-id <id>
betterness purchases checkout --test-key <key> --success-url <url> --cancel-url <url>

# Manage orders
betterness lab-orders initialize --order-id <id>
betterness lab-orders service-centers --zip-code 10001 --order-id <id>
betterness lab-orders slots --site-code <code> --order-id <id> --timezone America/New_York
betterness lab-orders book --order-id <id> --booking-key <key> --timezone America/New_York

# Upload results
betterness lab-results upload --file ./bloodwork.pdf

Lab Records & Results

betterness lab-records list
betterness lab-records detail --record-id <id>
betterness lab-results update-status --result-id <id> --action APPROVE
betterness lab-results update-biomarker --biomarker-id <id> --result 5.2 --unit "mg/dL"
betterness lab-results update-metadata --result-id <id> --patient-name "Jane Doe"

Health Profile

betterness health-profile schema                    # List all sections
betterness health-profile schema --section HWP      # Questions in a section
betterness health-profile get                       # Full profile (flat map)
betterness health-profile get-section --section DA  # Single section answers
betterness health-profile summary                   # Human-readable summary
betterness health-profile update --data '{"HWP_HAB_do_you_smoke_cigarettes_or_use_tobacco_products": false}'
betterness health-profile reset-section --section DA

Knowledge Library

betterness knowledge search -s "nutrition"              # Full-text search
betterness knowledge search --type VIDEO                # Only videos
betterness knowledge search --type FILE --sort ASC      # Files A-Z
betterness knowledge search -s "sleep" --page-size 5    # Paginate

Smart Listings (Wellness Providers)

betterness smart-listings search --query "yoga" --lat 40.7 --lng -74.0 --radius 10
betterness smart-listings detail --id <externalId>

Workflow (Composite Commands)

betterness workflow daily-brief       # Full health snapshot
betterness workflow next-actions      # AI-driven recommendations

MCP Integration

One-command setup for the Betterness MCP server in your AI client:

# Install into Claude Desktop, Claude Code, Cursor, or Windsurf
betterness mcp install claude
betterness mcp install claude-code
betterness mcp install claude-code --scope project    # project-level .mcp.json
betterness mcp install cursor
betterness mcp install windsurf

# Preview without writing
betterness mcp install claude --dry-run

# Check status across all clients
betterness mcp status

# Remove
betterness mcp uninstall claude

The install command reads your stored credentials, merges the MCP config into the client's config file (preserving existing entries), and creates a .bak backup.

Schema Discovery

betterness schema                     # All commands, options, and response formats as JSON

Useful for AI agents to discover capabilities at runtime.

Agent & MCP Integration

The CLI is designed to be consumed by AI agents. Key features:

• --json output for structured data parsing
• --markdown output optimized for LLM context windows
• betterness schema for runtime capability discovery
• --quiet mode for exit-code-only checks
• --dry-run on destructive commands for safe planning
• betterness mcp install <client> for one-command MCP setup

Skills

Agent skills teach your AI coding agent the Betterness API surface — endpoints, schemas, and workflows — so it can build integrations without guessing. Available in the betterness-cli repo under skills/:

Core skills:

| Skill | Description | |-------|-------------| | betterness-shared | Shared CLI setup, auth, and output format patterns | | betterness-auth | Authentication and credential management | | betterness-profile | User profile access and updates | | betterness-biomarkers | Biomarker results and biological age | | betterness-health-data | Activity, sleep, vitals, body composition | | betterness-connected-devices | Wearable device integrations | | betterness-lab-tests | Lab test catalog and browsing | | betterness-lab-orders | Lab order scheduling and booking | | betterness-lab-records | Lab record management | | betterness-lab-results | Lab result uploads and updates | | betterness-purchases | Purchases and Stripe checkout | | betterness-smart-listings | Wellness provider search | | betterness-workflow | Composite commands (daily brief, next actions) | | betterness-health-profile | Health profile questionnaire management | | betterness-knowledge | Knowledge library search (files and videos) | | betterness-mcp | MCP server integration for AI clients |

Persona skills:

| Skill | Description | |-------|-------------| | persona-health-coach | Health coach persona for wellness guidance | | persona-lab-manager | Lab manager persona for test ordering workflows |

Recipe skills:

| Skill | Description | |-------|-------------| | recipe-health-checkup | Step-by-step health checkup workflow | | recipe-order-lab-test | End-to-end lab test ordering | | recipe-track-biomarker | Biomarker tracking over time |

Installing skills

Install all skills into your agent with a single command (auto-detects Claude Code, Codex, Cursor, Windsurf, Cline, OpenClaw, and 40+ more):

npx skills add https://github.com/Betterness/betterness-cli

Or install a specific skill:

npx skills add https://github.com/Betterness/betterness-cli --skill betterness-biomarkers
npx skills add https://github.com/Betterness/betterness-cli --skill persona-health-coach

Each skill folder contains a SKILL.md with activation rules, patterns, and API reference.

Full CLI Reference

See CLI_REFERENCE.md for the complete list of commands, options, and descriptions.

License

Proprietary.