Command Reference
Auto-generated from the CLI source. Loaded directly from the public CLI repo — always reflects the latest published version.
Betterness CLI Reference
Version: 1.4.2
Global Options
These options apply to all commands:
| Option | Description |
|---|---|
-V, --version | output the version number |
--api-key <key> | API key (overrides env and stored credentials) |
--json | Output as JSON |
--markdown | Output as Markdown |
--quiet | Suppress output (exit code only) |
Commands
- auth — Manage authentication
auth login— Authenticate with Betterness (OAuth by default, or --key for API key)auth logout— Remove stored credentialsauth whoami— Show the currently authenticated user
- profile — User profile information
profile get— Retrieve current user profile (name, email, phone, gender, DOB, address)profile update— Update profile information (only provided fields are changed)
- biomarkers — Biomarker lab results and LOINC codes
biomarkers search— Search and filter biomarker lab resultsbiomarkers loinc-codes— List all available LOINC codes for biomarker identification
- biological-age — Biological age calculations and history
biological-age get— Get biological age history with biomarker values
- activity — Activity and workout data from connected wearables
activity get— Retrieve activity and workout data (steps, distance, calories, VO2 max, workouts)
- sleep — Sleep data from connected wearables
sleep get— Retrieve nightly sleep data (time in bed, total sleep, sleep stage breakdown)sleep stages— Retrieve minute-by-minute sleep stage transitions (Deep, Core, REM, Awake)
- vitals — Vital signs from connected wearables
vitals get— Retrieve vital signs (heart rate, HRV, blood pressure, SpO2, glucose, respiratory rate)
- body-composition — Body composition data from connected wearables
body-composition get— Retrieve body composition (weight, body fat %, muscle mass, BMI, waist circumference)
- connected-devices — Health device integrations and wearable connections
connected-devices list— List all connected health devices and wearablesconnected-devices available— List health device integrations the user can connect (not currently active)connected-devices link— Generate connection link for a web-based health device integrationconnected-devices apple-health-code— Generate connection code for Apple HealthKit via Junction appconnected-devices disconnect— Disconnect a health device integration
- lab-tests — Available lab tests for ordering
lab-tests list— List available lab tests purchasable in the user's confirmed US state (requires--us-state)
- lab-records — Lab records — uploaded results and purchased test orders
lab-records list— List lab records (both uploaded results and lab orders)lab-records detail— Get full detail of a lab record by external ID
- lab-orders — Lab order management — scheduling, appointments, and service centers
lab-orders initialize— Initialize a lab order for processing (order must be in Paid status)lab-orders service-centers— Search lab service centers near a ZIP codelab-orders slots— Get available appointment time slots at a service centerlab-orders book— Book a blood draw appointment at a service centerlab-orders reschedule— Reschedule an existing blood draw appointmentlab-orders cancel— Cancel a blood draw appointment (run without --reason-id to see available reasons)
- lab-results — Lab result management — approve, update biomarkers, update metadata
lab-results update-status— Update lab result status (APPROVE, ROLLBACK, or REPROCESS)lab-results update-biomarker— Update or delete a biomarker value within an uploaded lab resultlab-results update-metadata— Update metadata of an uploaded lab result (patient info and test details)lab-results upload— Upload a lab result PDF for processing
- purchases — Lab test purchases and payment methods
purchases payment-methods— List saved payment methods (credit/debit cards)purchases buy— Purchase a lab test using a saved payment methodpurchases checkout— Generate a Stripe Checkout payment link for a lab test (for users without saved cards)
- smart-listings — Search and browse wellness providers (SmartListings)
smart-listings search— Search SmartListings by name, description, tags, or locationsmart-listings detail— Get full details of a SmartListing by ID
- workflow — Composite commands that aggregate data from multiple endpoints
workflow daily-brief— Daily health summary — profile, biological age, biomarkers, devicesworkflow next-actions— Recommended next actions based on biomarkers and health data
- schema — Discover available commands, options, and response formats
- debug — Internal debug utilities
debug config— Show resolved configuration
- health-profile — Health profile questionnaire (read, update, schema)
health-profile schema— List all sections and question IDs available in the health profilehealth-profile get— Retrieve the full health profile (all answered questions as a flat map)health-profile get-section— Retrieve health profile answers for a specific sectionhealth-profile update— Update health profile questions (only provided fields are changed)health-profile reset-section— Clear all answers in a sectionhealth-profile summary— Human-readable summary of answered health profile questions
- knowledge — Search the Betterness knowledge library
knowledge search— Search Betterness-published knowledge (files and videos)
- mcp — MCP server integration for AI agents (Claude, Cursor, Windsurf)
mcp install— Install Betterness MCP integration into an AI clientmcp uninstall— Remove Betterness MCP integration from an AI clientmcp status— Show MCP integration status across all supported clients
auth
Manage authentication
betterness auth login
Authenticate with Betterness (OAuth by default, or --key for API key)
| Option | Description |
|---|---|
--key <apiKey> | Use an API key instead of OAuth |
betterness auth logout
Remove stored credentials
betterness auth whoami
Show the currently authenticated user
profile
User profile information
betterness profile get
Retrieve current user profile (name, email, phone, gender, DOB, address)
betterness profile update
Update profile information (only provided fields are changed)
| Option | Description |
|---|---|
--first-name <name> | First name |
--last-name <name> | Last name |
--phone <number> | Phone number without dial code |
--phone-dial-code <code> | Phone dial code (e.g. +1, +44) |
--gender <value> | Gender: MALE, FEMALE, OTHER, or PREF_NOT |
--birth-date <YYYY-MM-DD> | Date of birth |
--address <street> | Home street address |
--city <city> | City |
--state <state> | State or province |
--zip-code <zip> | ZIP or postal code |
--country <code> | Country (e.g. US, GB) |
--dry-run | Preview changes without applying |
biomarkers
Biomarker lab results and LOINC codes
betterness biomarkers search
Search and filter biomarker lab results
| Option | Description |
|---|---|
--name <text> | Filter by biomarker name |
--loinc-code <code> | Filter by LOINC code |
--start-date <YYYY-MM-DD> | Start date (ISO-8601) |
--end-date <YYYY-MM-DD> | End date (ISO-8601) |
--categories <list> | Comma-separated category filter |
--range <type> | Range filter: OPTIMAL, AVERAGE, OUT_OF_RANGE, UNKNOWN |
--limit <n> | Maximum number of results (default: 20) |
betterness biomarkers loinc-codes
List all available LOINC codes for biomarker identification
biological-age
Biological age calculations and history
betterness biological-age get
Get biological age history with biomarker values
| Option | Description |
|---|---|
--limit <n> | Maximum number of results (default: 10) |
activity
Activity and workout data from connected wearables
betterness activity get
Retrieve activity and workout data (steps, distance, calories, VO2 max, workouts)
| Option | Description |
|---|---|
--from <YYYY-MM-DD> | Start date (default: 2026-03-17) |
--to <YYYY-MM-DD> | End date |
--timezone <tz> | IANA timezone (default: America/Mendoza) |
sleep
Sleep data from connected wearables
betterness sleep get
Retrieve nightly sleep data (time in bed, total sleep, sleep stage breakdown)
| Option | Description |
|---|---|
--from <YYYY-MM-DD> | Start date (default: 2026-03-17) |
--to <YYYY-MM-DD> | End date |
--timezone <tz> | IANA timezone (default: America/Mendoza) |
betterness sleep stages
Retrieve minute-by-minute sleep stage transitions (Deep, Core, REM, Awake)
| Option | Description |
|---|---|
--from <YYYY-MM-DD> | Start date (default: 2026-03-17) |
--to <YYYY-MM-DD> | End date |
--timezone <tz> | IANA timezone (default: America/Mendoza) |
vitals
Vital signs from connected wearables
betterness vitals get
Retrieve vital signs (heart rate, HRV, blood pressure, SpO2, glucose, respiratory rate)
| Option | Description |
|---|---|
--from <YYYY-MM-DD> | Start date (default: 2026-03-17) |
--to <YYYY-MM-DD> | End date |
--timezone <tz> | IANA timezone (default: America/Mendoza) |
body-composition
Body composition data from connected wearables
betterness body-composition get
Retrieve body composition (weight, body fat %, muscle mass, BMI, waist circumference)
| Option | Description |
|---|---|
--from <YYYY-MM-DD> | Start date (default: 2026-03-17) |
--to <YYYY-MM-DD> | End date |
--timezone <tz> | IANA timezone (default: America/Mendoza) |
connected-devices
Health device integrations and wearable connections
betterness connected-devices list
List all connected health devices and wearables
betterness connected-devices available
List health device integrations the user can connect (not currently active)
betterness connected-devices link
Generate connection link for a web-based health device integration
| Option | Description |
|---|---|
--integration-key <key> | Integration provider (GARMIN, OURA, WITHINGS, PELOTON, WAHOO, EIGHT_SLEEP) (required) |
betterness connected-devices apple-health-code
Generate connection code for Apple HealthKit via Junction app
betterness connected-devices disconnect
Disconnect a health device integration
| Option | Description |
|---|---|
--integration-key <key> | Integration provider to disconnect (required) |
--dry-run | Preview the disconnection without executing |
lab-tests
Available lab tests for ordering
betterness lab-tests list
List available lab tests purchasable in the user's confirmed US state. --us-state is required — lab availability and price are state-specific (NY/NJ have different catalogs than other states).
| Option | Description |
|---|---|
--us-state <code> | Required. Two-letter US state code (e.g. NY, NJ, FL). |
--query <text> | Search by name or description |
--popular | Only show popular tests |
--loinc-slug <slug> | Filter by LOINC slug |
lab-records
Lab records — uploaded results and purchased test orders
betterness lab-records list
List lab records (both uploaded results and lab orders)
| Option | Description |
|---|---|
--limit <n> | Results per page (default: 20) |
--page <n> | Page number (zero-based) (default: 0) |
betterness lab-records detail
Get full detail of a lab record by external ID
| Option | Description |
|---|---|
--record-id <id> | Lab record external ID (required) |
lab-orders
Lab order management — scheduling, appointments, and service centers
betterness lab-orders initialize
Initialize a lab order for processing (order must be in Paid status)
| Option | Description |
|---|---|
--order-id <id> | Lab order external ID (required) |
--dry-run | Preview the action without executing |
betterness lab-orders service-centers
Search lab service centers near a ZIP code
| Option | Description |
|---|---|
--zip-code <zip> | ZIP code to search near (required) |
--order-id <id> | Lab order external ID (required) |
--limit <n> | Maximum results (default: 6) |
--offset <n> | Pagination offset (default: 0) |
betterness lab-orders slots
Get available appointment time slots at a service center
| Option | Description |
|---|---|
--site-code <code> | Service center site code (required) |
--order-id <id> | Lab order external ID (required) |
--timezone <tz> | IANA timezone (required) |
--start-date <YYYY-MM-DD> | Start date for slot search |
--range-days <n> | Number of days to search (default: 7) |
betterness lab-orders book
Book a blood draw appointment at a service center
| Option | Description |
|---|---|
--order-id <id> | Lab order external ID (required) |
--booking-key <key> | Booking key from slots command (required) |
--timezone <tz> | IANA timezone (required) |
--dry-run | Preview the booking without executing |
betterness lab-orders reschedule
Reschedule an existing blood draw appointment
| Option | Description |
|---|---|
--order-id <id> | Lab order external ID (required) |
--booking-key <key> | New booking key from slots command (required) |
--timezone <tz> | IANA timezone (required) |
--dry-run | Preview the reschedule without executing |
betterness lab-orders cancel
Cancel a blood draw appointment (run without --reason-id to see available reasons)
| Option | Description |
|---|---|
--order-id <id> | Lab order external ID (required) |
--reason-id <id> | Cancellation reason ID |
--dry-run | Preview the cancellation without executing |
lab-results
Lab result management — approve, update biomarkers, update metadata
betterness lab-results update-status
Update lab result status (APPROVE, ROLLBACK, or REPROCESS)
| Option | Description |
|---|---|
--result-id <id> | Lab result external ID (required) |
--action <action> | Action: APPROVE, ROLLBACK, or REPROCESS (required) |
betterness lab-results update-biomarker
Update or delete a biomarker value within an uploaded lab result
| Option | Description |
|---|---|
--biomarker-id <id> | Biomarker external ID (required) |
--action <action> | Set to DELETE to remove the biomarker |
--name <name> | Biomarker name |
--result <value> | Biomarker value (e.g. '5.2', '120') |
--unit <unit> | Unit (e.g. 'mg/dL', 'ng/mL') |
--min-range <n> | Minimum range value |
--max-range <n> | Maximum range value |
betterness lab-results update-metadata
Update metadata of an uploaded lab result (patient info and test details)
| Option | Description |
|---|---|
--result-id <id> | Lab result external ID (required) |
--patient-name <name> | Patient name |
--patient-sex <sex> | Patient sex: MALE or FEMALE |
--dob <date> | Date of birth |
--lab-name <name> | Lab name |
--ordering-physician <name> | Ordering physician |
--date-collected <date> | Date collected (ISO-8601) |
--fasting | Mark as fasting test |
betterness lab-results upload
Upload a lab result PDF for processing
| Option | Description |
|---|---|
--file <path> | Path to the PDF file (required) |
purchases
Lab test purchases and payment methods
betterness purchases payment-methods
List saved payment methods (credit/debit cards)
betterness purchases buy
Purchase a lab test using a saved payment method
| Option | Description |
|---|---|
--test-key <key> | Lab test object key (required) |
--payment-method-id <id> | Payment method external ID (required) |
--promo-code <code> | Promotion code |
--dry-run | Preview what would be purchased without executing |
betterness purchases checkout
Generate a Stripe Checkout payment link for a lab test (for users without saved cards)
| Option | Description |
|---|---|
--test-key <key> | Lab test object key (required) |
--success-url <url> | URL to redirect after successful payment (required) |
--cancel-url <url> | URL to redirect if checkout is cancelled (required) |
--promo-code <code> | Promotion code |
--dry-run | Preview the checkout request without executing |
smart-listings
Search and browse wellness providers (SmartListings)
betterness smart-listings search
Search SmartListings by name, description, tags, or location
| Option | Description |
|---|---|
--query <text> | Text search query |
--lat <n> | Latitude for proximity search |
--lng <n> | Longitude for proximity search |
--radius <km> | Radius in km (1, 2, 5, 10, 20) |
--following | Only show followed providers |
--limit <n> | Results per page (default: 10) |
--page <n> | Page number (zero-based) (default: 0) |
betterness smart-listings detail
Get full details of a SmartListing by ID
| Option | Description |
|---|---|
--id <externalId> | SmartListing external ID (required) |
workflow
Composite commands that aggregate data from multiple endpoints
betterness workflow daily-brief
Daily health summary — profile, biological age, biomarkers, devices
| Option | Description |
|---|---|
--biomarker-limit <n> | Maximum biomarkers to fetch (default: 20) |
betterness workflow next-actions
Recommended next actions based on biomarkers and health data
| Option | Description |
|---|---|
--biomarker-limit <n> | Maximum biomarkers to analyze (default: 50) |
betterness schema
Discover available commands, options, and response formats
debug
Internal debug utilities
betterness debug config
Show resolved configuration
health-profile
Health profile questionnaire (read, update, schema)
betterness health-profile schema
List all sections and question IDs available in the health profile
| Option | Description |
|---|---|
--section <acronym> | Show questions for a specific section only |
betterness health-profile get
Retrieve the full health profile (all answered questions as a flat map)
betterness health-profile get-section
Retrieve health profile answers for a specific section
| Option | Description |
|---|---|
--section <acronym> | Section acronym (e.g. HWP, DMH, DA) (required) |
betterness health-profile update
Update health profile questions (only provided fields are changed)
| Option | Description |
|---|---|
--data <json> | JSON object with question IDs as keys and answers as values (required) |
--dry-run | Preview changes without applying |
betterness health-profile reset-section
Clear all answers in a section
| Option | Description |
|---|---|
--section <acronym> | Section acronym (e.g. HWP, DMH, DA) (required) |
--dry-run | Preview without applying |
betterness health-profile summary
Human-readable summary of answered health profile questions
| Option | Description |
|---|---|
--section <acronym> | Summarize a specific section only |
knowledge
Search the Betterness knowledge library
betterness knowledge search
Search Betterness-published knowledge (files and videos). Uses OpenSearch full-text search on title and summary fields.
| Option | Description |
|---|---|
-s, --search <text> | Full-text search query |
--type <type> | Filter by type: DOCUMENT or VIDEO (default: both) |
--sort <method> | Sort: ASC, DESC, LATEST, OLDEST (default: LATEST) |
--page <n> | Page number (0-indexed) (default: 0) |
--page-size <n> | Results per page (default: 10) |
Response fields: externalId, title, type, authors, score (0-100), date, url, coverImageUrl, reviewCount
Examples:
betterness knowledge search -s "nutrition" --json
betterness knowledge search --type VIDEO --page-size 5
betterness knowledge search --sort OLDEST --page 2
mcp
MCP server integration for AI agents (Claude, Cursor, Windsurf)
betterness mcp install
Install Betterness MCP integration into an AI client
betterness mcp install <client> [--scope <scope>] [--dry-run]
| Argument / Option | Description |
|---|---|
<client> | Client to configure: claude, claude-code, cursor, windsurf (required) |
--scope <scope> | Config scope: global or project (claude-code only, default: global) |
--dry-run | Print config without writing |
Behavior:
- Resolves stored credentials (or
--api-keyoverride) - Reads the client's config file (if it exists), merges
mcpServers.betternessentry - Backs up original file as
.bak - Writes updated config
Client config file locations:
| Client | macOS | Linux |
|---|---|---|
claude | ~/Library/Application Support/Claude/claude_desktop_config.json | ~/.config/Claude/claude_desktop_config.json |
claude-code (global) | ~/.claude/settings.json | ~/.claude/settings.json |
claude-code (project) | .mcp.json | .mcp.json |
cursor | .cursor/mcp.json | .cursor/mcp.json |
windsurf | ~/.codeium/windsurf/mcp_config.json | ~/.codeium/windsurf/mcp_config.json |
betterness mcp uninstall
Remove Betterness MCP integration from an AI client
betterness mcp uninstall <client> [--scope <scope>]
| Argument / Option | Description |
|---|---|
<client> | Client to unconfigure: claude, claude-code, cursor, windsurf (required) |
--scope <scope> | Config scope: global or project (claude-code only, default: global) |
betterness mcp status
Show MCP integration status across all supported clients. Scans all known config file paths and reports which clients have Betterness MCP configured.
betterness mcp status --json
Returns: client, status, apiKey (truncated), configFile