npm - @betterness/cli - Versions diffs - 1.0.0 → 1.0.1 - Mend

@betterness/cli 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/CLI_REFERENCE.md ADDED Viewed

@@ -0,0 +1,493 @@
+# Betterness CLI Reference
+> Auto-generated from command definitions — do not edit manually.
+> Run `npm run docs` in `modules/betterness-cli` to regenerate.
+Version: 0.1.0
+## 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](#auth)** — Manage authentication
+  - `auth login` — Save API key for authentication
+  - `auth logout` — Remove stored credentials
+  - `auth whoami` — Show the currently authenticated user
+- **[profile](#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](#biomarkers)** — Biomarker lab results and LOINC codes
+  - `biomarkers search` — Search and filter biomarker lab results
+  - `biomarkers loinc-codes` — List all available LOINC codes for biomarker identification
+- **[biological-age](#biological-age)** — Biological age calculations and history
+  - `biological-age get` — Get biological age history with biomarker values
+- **[activity](#activity)** — Activity and workout data from connected wearables
+  - `activity get` — Retrieve activity and workout data (steps, distance, calories, VO2 max, workouts)
+- **[sleep](#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](#vitals)** — Vital signs from connected wearables
+  - `vitals get` — Retrieve vital signs (heart rate, HRV, blood pressure, SpO2, glucose, respiratory rate)
+- **[body-composition](#body-composition)** — Body composition data from connected wearables
+  - `body-composition get` — Retrieve body composition (weight, body fat %, muscle mass, BMI, waist circumference)
+- **[connected-devices](#connected-devices)** — Health device integrations and wearable connections
+  - `connected-devices list` — List all connected health devices and wearables
+  - `connected-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 integration
+  - `connected-devices apple-health-code` — Generate connection code for Apple HealthKit via Junction app
+  - `connected-devices disconnect` — Disconnect a health device integration
+- **[lab-tests](#lab-tests)** — Available lab tests for ordering
+  - `lab-tests list` — List available lab tests with prices and included markers
+- **[lab-records](#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-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 code
+  - `lab-orders slots` — Get available appointment time slots at a service center
+  - `lab-orders book` — Book a blood draw appointment at a service center
+  - `lab-orders reschedule` — Reschedule an existing blood draw appointment
+  - `lab-orders cancel` — Cancel a blood draw appointment (run without --reason-id to see available reasons)
+- **[lab-results](#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 result
+  - `lab-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](#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 method
+  - `purchases checkout` — Generate a Stripe Checkout payment link for a lab test (for users without saved cards)
+- **[smart-listings](#smart-listings)** — Search and browse wellness providers (SmartListings)
+  - `smart-listings search` — Search SmartListings by name, description, tags, or location
+  - `smart-listings detail` — Get full details of a SmartListing by ID
+- **[workflow](#workflow)** — Composite commands that aggregate data from multiple endpoints
+  - `workflow daily-brief` — Daily health summary — profile, biological age, biomarkers, devices
+  - `workflow next-actions` — Recommended next actions based on biomarkers and health data
+- **[schema](#schema)** — Discover available commands, options, and response formats
+---
+## auth
+Manage authentication
+### `betterness auth login`
+Save API key for authentication
+| Option | Description |
+|--------|-------------|
+| `--key <apiKey>` | API key to save (if not provided, will prompt) |
+### `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-13`) |
+| `--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-13`) |
+| `--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-13`) |
+| `--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-13`) |
+| `--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-13`) |
+| `--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 with prices and included markers
+| Option | Description |
+|--------|-------------|
+| `--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

package/README.md ADDED Viewed

@@ -0,0 +1,198 @@
+# @betterness/cli
+Terminal interface for the [Betterness](https://betterness.com) 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
+```bash
+npm install -g @betterness/cli
+```
+Requires Node.js 20+.
+## Authentication
+Get your API key from either:
+- [app.betti.bot/settings/betterness-mcp](https://app.betti.bot/settings/betterness-mcp)
+- [betterness.ai/mcp/keys](https://www.betterness.ai/mcp/keys)
+The same key works for both the CLI and the [Betterness MCP server](https://www.betterness.ai/mcp).
+```bash
+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.
+Priority: `--api-key` flag > `BETTERNESS_API_KEY` env var > stored credentials.
+## Quick Start
+```bash
+# 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 |
+```bash
+betterness biomarkers search --json | jq '.[] | .name'
+betterness profile get --markdown
+```
+## Commands
+### Profile
+```bash
+betterness profile get                              # View profile
+betterness profile update --city "New York" --state NY  # Update fields
+```
+### Biomarkers & Biological Age
+```bash
+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.).
+```bash
+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
+```bash
+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
+```bash
+# 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
+```bash
+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"
+```
+### Smart Listings (Wellness Providers)
+```bash
+betterness smart-listings search --query "yoga" --lat 40.7 --lng -74.0 --radius 10
+betterness smart-listings detail --id <externalId>
+```
+### Workflow (Composite Commands)
+```bash
+betterness workflow daily-brief       # Full health snapshot
+betterness workflow next-actions      # AI-driven recommendations
+```
+### Schema Discovery
+```bash
+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
+### 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](https://github.com/Betterness/betterness-cli) repo under `.agents/skills/`:
+| Skill | Description |
+|-------|-------------|
+| [biomarkers-api](https://github.com/Betterness/betterness-cli/tree/main/.agents/skills/biomarkers-api) | Biomarkers, lab tests, lab orders, health records, biological age, purchases, Stripe flows |
+| [perks-api](https://github.com/Betterness/betterness-cli/tree/main/.agents/skills/perks-api) | Perks management, browsing, partner profiles, collaboration workflow |
+#### Installing skills
+Install all skills into your agent with a single command (auto-detects Claude Code, Codex, Cursor, Windsurf, Cline, OpenClaw, and [40+ more](https://github.com/vercel-labs/skills)):
+```bash
+npx skills add https://github.com/Betterness/betterness-cli
+```
+Or install a specific skill:
+```bash
+npx skills add https://github.com/Betterness/betterness-cli --skill biomarkers-api
+npx skills add https://github.com/Betterness/betterness-cli --skill perks-api
+```
+Each skill folder contains a `SKILL.md` (activation rules and patterns) and a `references/` directory with full API specs.
+## Full CLI Reference
+See [CLI_REFERENCE.md](./CLI_REFERENCE.md) for the complete list of commands, options, and descriptions.
+## License
+Proprietary.

package/package.json CHANGED Viewed

@@ -1,13 +1,15 @@
 {
   "name": "@betterness/cli",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Betterness CLI - Agent-first terminal interface for the Betterness platform",
   "type": "module",
   "bin": {
     "betterness": "./dist/index.js"
   },
   "files": [
-    "dist/"
+    "dist/",
+    "README.md",
+    "CLI_REFERENCE.md"
   ],
   "publishConfig": {
     "access": "public"