@betterness/cli 1.3.1 → 1.3.4

package/CLI_REFERENCE.md

@@ -0,0 +1,648 @@
+# Betterness CLI Reference
+
+> Auto-generated from command definitions — do not edit manually.
+> Run `npm run docs` in `modules/betterness-cli` to regenerate.
+
+Version: 0.0.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` — Authenticate with Betterness (OAuth by default, or --key for API key)
+  - `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
+- **[debug](#debug)** — Internal debug utilities
+  - `debug config` — Show resolved configuration
+- **[health-profile](#health-profile)** — Health profile questionnaire (read, update, schema)
+  - `health-profile schema` — List all sections and question IDs available in the health profile
+  - `health-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 section
+  - `health-profile update` — Update health profile questions (only provided fields are changed)
+  - `health-profile reset-section` — Clear all answers in a section
+  - `health-profile summary` — Human-readable summary of answered health profile questions
+- **[knowledge](#knowledge)** — Search the Betterness knowledge library
+  - `knowledge search` — Search Betterness-published knowledge (files and videos)
+- **[mcp](#mcp)** — MCP server integration for AI agents (Claude, Cursor, Windsurf)
+  - `mcp install` — Install Betterness MCP integration into an AI client
+  - `mcp uninstall` — Remove Betterness MCP integration from an AI client
+  - `mcp 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 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
+
+## 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: `FILE` 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:**
+```bash
+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
+
+```bash
+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:**
+1. Resolves stored credentials (or `--api-key` override)
+2. Reads the client's config file (if it exists), merges `mcpServers.betterness` entry
+3. Backs up original file as `.bak`
+4. 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
+
+```bash
+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.
+
+```bash
+betterness mcp status --json
+```
+
+Returns: `client`, `status`, `apiKey` (truncated), `configFile`
+

package/README.md

@@ -158,6 +158,15 @@ betterness health-profile update --data '{"HWP_HAB_do_you_smoke_cigarettes_or_us
 betterness health-profile reset-section --section DA
 ```
 
+### Knowledge Library
+
+```bash
+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)
 
 ```bash
@@ -237,6 +246,7 @@ Agent skills teach your AI coding agent the Betterness API surface — endpoints
 | [betterness-smart-listings](https://github.com/Betterness/betterness-cli/tree/main/skills/betterness-smart-listings) | Wellness provider search |
 | [betterness-workflow](https://github.com/Betterness/betterness-cli/tree/main/skills/betterness-workflow) | Composite commands (daily brief, next actions) |
 | [betterness-health-profile](https://github.com/Betterness/betterness-cli/tree/main/skills/betterness-health-profile) | Health profile questionnaire management |
+| [betterness-knowledge](https://github.com/Betterness/betterness-cli/tree/main/skills/betterness-knowledge) | Knowledge library search (files and videos) |
 | [betterness-mcp](https://github.com/Betterness/betterness-cli/tree/main/skills/betterness-mcp) | MCP server integration for AI clients |
 
 **Persona skills:**

package/dist/index.js

@@ -3,12 +3,25 @@
 // src/program.ts
 import { Command } from "commander";
 
+// src/commands/auth.ts
+import { join as join4 } from "path";
+
 // src/auth/credentialStore.ts
 import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync } from "fs";
+import { join as join2 } from "path";
+
+// src/paths.ts
 import { join } from "path";
 import { homedir } from "os";
-var CONFIG_DIR = join(homedir(), ".betterness");
-var CREDENTIALS_FILE = join(CONFIG_DIR, "credentials.json");
+function resolveConfigDir() {
+  const apiUrl = "https://api.betterness.ai";
+  const isDev = apiUrl.includes("localhost") || apiUrl.includes("127.0.0.1");
+  return join(homedir(), isDev ? ".betterness-dev" : ".betterness");
+}
+var CONFIG_DIR = resolveConfigDir();
+
+// src/auth/credentialStore.ts
+var CREDENTIALS_FILE = join2(CONFIG_DIR, "credentials.json");
 function ensureConfigDir() {
   if (!existsSync(CONFIG_DIR)) {
     mkdirSync(CONFIG_DIR, { recursive: true, mode: 448 });
@@ -43,13 +56,11 @@ function deleteCredentials() {
 
 // src/auth/tokenStore.ts
 import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2, existsSync as existsSync2, unlinkSync as unlinkSync2 } from "fs";
-import { join as join2 } from "path";
-import { homedir as homedir2 } from "os";
-var CONFIG_DIR2 = join2(homedir2(), ".betterness");
-var TOKENS_FILE = join2(CONFIG_DIR2, "tokens.json");
+import { join as join3 } from "path";
+var TOKENS_FILE = join3(CONFIG_DIR, "tokens.json");
 function ensureConfigDir2() {
-  if (!existsSync2(CONFIG_DIR2)) {
-    mkdirSync2(CONFIG_DIR2, { recursive: true, mode: 448 });
+  if (!existsSync2(CONFIG_DIR)) {
+    mkdirSync2(CONFIG_DIR, { recursive: true, mode: 448 });
   }
 }
 function loadTokens() {
@@ -408,7 +419,7 @@ var ApiClient = class {
           headers: {
             "Authorization": `Bearer ${this.apiKey}`,
             "Content-Type": "application/json",
-            "User-Agent": `betterness-cli/${"1.3.1"}`,
+            "User-Agent": `betterness-cli/${"1.3.4"}`,
             "Accept": "application/json"
           },
           body: body ? JSON.stringify(body) : void 0,
@@ -456,9 +467,9 @@ var ApiClient = class {
     return this.unwrap(raw, schema);
   }
   async upload(path, filePath, fieldName = "file", schema) {
-    const { readFileSync: readFileSync4 } = await import("fs");
+    const { readFileSync: readFileSync5 } = await import("fs");
     const { basename, extname } = await import("path");
-    const buffer = readFileSync4(filePath);
+    const buffer = readFileSync5(filePath);
     const fileName = basename(filePath);
     const ext = extname(filePath).toLowerCase();
     const mimeType = ext === ".pdf" ? "application/pdf" : "application/octet-stream";
@@ -472,7 +483,7 @@ var ApiClient = class {
         method: "POST",
         headers: {
           "Authorization": `Bearer ${this.apiKey}`,
-          "User-Agent": `betterness-cli/${"1.3.1"}`,
+          "User-Agent": `betterness-cli/${"1.3.4"}`,
           "Accept": "application/json"
         },
         body: formData,
@@ -837,6 +848,30 @@ var healthProfileResponseSchema = z.object({
   userId: z.string(),
   questionsData: z.record(z.unknown()).nullable().optional()
 }).passthrough();
+var expertSmallSchema = z.object({
+  externalId: z.string(),
+  name: z.string().nullable().optional()
+});
+var tagSmallSchema = z.object({
+  externalId: z.string(),
+  name: z.string().nullable().optional()
+});
+var knowledgeSearchResultSchema = z.object({
+  externalId: z.string(),
+  title: z.string().nullable().optional(),
+  coverImageUrl: z.string().nullable().optional(),
+  url: z.string().nullable().optional(),
+  type: z.string().nullable().optional(),
+  authors: z.array(expertSmallSchema).nullable().optional(),
+  tags: z.array(tagSmallSchema).nullable().optional(),
+  releaseDate: z.string().nullable().optional(),
+  betternessKnowledge: z.boolean().nullable().optional(),
+  averageScore: z.number().nullable().optional(),
+  reviewCount: z.number().nullable().optional(),
+  avatarUrl: z.string().nullable().optional(),
+  permission: z.string().nullable().optional(),
+  showOnProfile: z.boolean().nullable().optional()
+});
 
 // src/commands/auth.ts
 function registerAuthCommands(program2) {
@@ -892,7 +927,7 @@ async function loginWithApiKey(apiKey) {
     name: user.firstName ?? void 0
   });
   console.log(`Logged in as: ${user.firstName ?? "Unknown"} (${user.email ?? "no email"})`);
-  console.log("Credentials saved to ~/.betterness/credentials.json");
+  console.log(`Credentials saved to ${join4(CONFIG_DIR, "credentials.json")}`);
 }
 async function loginWithOAuth() {
   const result = await startOAuthLogin();
@@ -922,7 +957,7 @@ async function loginWithOAuth() {
     name: user.firstName ?? result.name
   });
   console.log(`Logged in as: ${user.firstName ?? "Unknown"} (${user.email ?? "no email"})`);
-  console.log("Credentials saved to ~/.betterness/tokens.json");
+  console.log(`Credentials saved to ${join4(CONFIG_DIR, "tokens.json")}`);
 }
 
 // src/commands/profile.ts
@@ -1661,10 +1696,10 @@ function registerLabResultsCommands(program2) {
   });
   labResults.command("upload").description("Upload a lab result PDF for processing").requiredOption("--file <path>", "Path to the PDF file").action(async (opts, cmd) => {
     try {
-      const { existsSync: existsSync5 } = await import("fs");
+      const { existsSync: existsSync6 } = await import("fs");
       const { resolve } = await import("path");
       const filePath = resolve(opts.file);
-      if (!existsSync5(filePath)) {
+      if (!existsSync6(filePath)) {
         console.error(`File not found: ${filePath}`);
         process.exit(1);
       }
@@ -2127,21 +2162,20 @@ function registerSchemaCommand(program2) {
 }
 
 // src/commands/debug.ts
-import { homedir as homedir3 } from "os";
-import { join as join3 } from "path";
+import { join as join5 } from "path";
 import { existsSync as existsSync3 } from "fs";
 function registerDebugCommands(program2) {
   const debug = program2.command("debug", { hidden: true }).description("Internal debug utilities");
   debug.command("config").description("Show resolved configuration").action((_, cmd) => {
-    const credentialsPath = join3(homedir3(), ".betterness", "credentials.json");
-    const tokensPath = join3(homedir3(), ".betterness", "tokens.json");
+    const credentialsPath = join5(CONFIG_DIR, "credentials.json");
+    const tokensPath = join5(CONFIG_DIR, "tokens.json");
     const stored = loadCredentials();
     const tokens = loadTokens();
     const envKey = process.env.BETTERNESS_API_KEY;
     const parentOpts = cmd.optsWithGlobals();
-    const authSource = parentOpts.apiKey ? "--api-key flag" : envKey ? "BETTERNESS_API_KEY env" : tokens && !isTokenExpired(tokens) ? "OAuth tokens (~/.betterness/tokens.json)" : stored ? "API key (~/.betterness/credentials.json)" : "none";
+    const authSource = parentOpts.apiKey ? "--api-key flag" : envKey ? "BETTERNESS_API_KEY env" : tokens && !isTokenExpired(tokens) ? `OAuth tokens (${tokensPath})` : stored ? `API key (${credentialsPath})` : "none";
     const config = {
-      version: "1.3.1",
+      version: "1.3.4",
       apiUrl: "https://api.betterness.ai",
       auth0Domain: "betterness.us.auth0.com",
       auth0ClientId: "g4lqYHRQb2QMgdRKIlKwoTJl6eu41pWn",
@@ -2449,17 +2483,17 @@ function formatAnswerValue(value) {
 
 // src/commands/mcp.ts
 import { readFileSync as readFileSync3, writeFileSync as writeFileSync3, existsSync as existsSync4, mkdirSync as mkdirSync3, copyFileSync } from "fs";
-import { join as join4, dirname } from "path";
-import { homedir as homedir4, platform } from "os";
+import { join as join6, dirname } from "path";
+import { homedir as homedir2, platform } from "os";
 var CLIENTS = {
   claude: {
     name: "Claude Desktop",
     supportsScope: false,
     configPath: () => {
       if (platform() === "darwin") {
-        return join4(homedir4(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+        return join6(homedir2(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
       }
-      return join4(homedir4(), ".config", "Claude", "claude_desktop_config.json");
+      return join6(homedir2(), ".config", "Claude", "claude_desktop_config.json");
     }
   },
   "claude-code": {
@@ -2467,20 +2501,20 @@ var CLIENTS = {
     supportsScope: true,
     configPath: (scope) => {
       if (scope === "project") {
-        return join4(process.cwd(), ".mcp.json");
+        return join6(process.cwd(), ".mcp.json");
       }
-      return join4(homedir4(), ".claude", "settings.json");
+      return join6(homedir2(), ".claude", "settings.json");
     }
   },
   cursor: {
     name: "Cursor",
     supportsScope: false,
-    configPath: () => join4(process.cwd(), ".cursor", "mcp.json")
+    configPath: () => join6(process.cwd(), ".cursor", "mcp.json")
   },
   windsurf: {
     name: "Windsurf",
     supportsScope: false,
-    configPath: () => join4(homedir4(), ".codeium", "windsurf", "mcp_config.json")
+    configPath: () => join6(homedir2(), ".codeium", "windsurf", "mcp_config.json")
   }
 };
 var VALID_CLIENTS = Object.keys(CLIENTS).join(", ");
@@ -2667,10 +2701,75 @@ Restart ${client.name} to activate. Then try asking:
   });
 }
 
+// src/commands/knowledge.ts
+var knowledgeColumns = [
+  { key: "title", label: "Title", width: 35 },
+  { key: "type", label: "Type", width: 10 },
+  { key: "authors", label: "Authors", width: 20 },
+  { key: "score", label: "Score", width: 6, align: "right" },
+  { key: "date", label: "Date", width: 12 }
+];
+var responseSchema = simplePageSchema(knowledgeSearchResultSchema);
+function mapRows(results) {
+  return results.map((r) => ({
+    externalId: r.externalId,
+    title: r.title ?? "",
+    type: r.type ?? "",
+    authors: r.authors?.map((a) => a.name).join(", ") ?? "",
+    score: r.averageScore ?? "-",
+    date: r.releaseDate ?? "",
+    url: r.url ?? "",
+    coverImageUrl: r.coverImageUrl ?? "",
+    reviewCount: r.reviewCount ?? 0
+  }));
+}
+function registerKnowledgeCommands(program2) {
+  const knowledge = program2.command("knowledge").description("Search the Betterness knowledge library");
+  knowledge.command("search").description("Search Betterness-published knowledge (files and videos)").option("-s, --search <text>", "Full-text search query").option("--type <type>", "Filter by type: FILE or VIDEO (default: both)").option("--sort <method>", "Sort: ASC, DESC, LATEST, OLDEST", "LATEST").option("--page <n>", "Page number (0-indexed)", "0").option("--page-size <n>", "Results per page", "10").action(async (opts, cmd) => {
+    try {
+      const globalOpts = cmd.optsWithGlobals();
+      const client = await createApiClient({ apiKey: globalOpts.apiKey });
+      const params = {
+        page: opts.page,
+        pageSize: opts.pageSize
+      };
+      const body = {
+        sortMethod: opts.sort.toUpperCase()
+      };
+      if (opts.search) body.search = opts.search;
+      if (opts.type) {
+        const t = opts.type.toUpperCase();
+        if (t !== "FILE" && t !== "VIDEO") {
+          process.stderr.write("Error: --type must be FILE or VIDEO\n");
+          process.exitCode = 1;
+          return;
+        }
+        body.knowledgeType = t;
+      }
+      const response = await client.post(
+        "/api/library-knowledge/betterness",
+        body,
+        params,
+        responseSchema
+      );
+      const rows = mapRows(response.content);
+      if (!globalOpts.json && !globalOpts.quiet) {
+        const showing = response.content.length;
+        const total = response.totalResults;
+        process.stderr.write(`Page ${response.number + 1} \u2014 ${showing} of ${total} results${response.last ? " (last page)" : ""}
+`);
+      }
+      outputList(cmd, rows, knowledgeColumns);
+    } catch (error) {
+      outputError(error);
+    }
+  });
+}
+
 // src/program.ts
 function createProgram() {
   const program2 = new Command();
-  program2.name("betterness").description("Betterness CLI - Agent-first terminal interface for the Betterness platform").version("1.3.1").option("--api-key <key>", "API key (overrides env and stored credentials)").option("--json", "Output as JSON").option("--markdown", "Output as Markdown").option("--quiet", "Suppress output (exit code only)");
+  program2.name("betterness").description("Betterness CLI - Agent-first terminal interface for the Betterness platform").version("1.3.4").option("--api-key <key>", "API key (overrides env and stored credentials)").option("--json", "Output as JSON").option("--markdown", "Output as Markdown").option("--quiet", "Suppress output (exit code only)");
   registerAuthCommands(program2);
   registerProfileCommands(program2);
   registerBiomarkersCommands(program2);
@@ -2691,9 +2790,88 @@ function createProgram() {
   registerDebugCommands(program2);
   registerHealthProfileCommands(program2);
   registerMcpCommands(program2);
+  registerKnowledgeCommands(program2);
   return program2;
 }
 
+// src/updateCheck.ts
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync4, mkdirSync as mkdirSync4, existsSync as existsSync5 } from "fs";
+import { join as join7 } from "path";
+var CACHE_FILE = join7(CONFIG_DIR, "update-check.json");
+var CHECK_INTERVAL_MS = 60 * 60 * 1e3;
+var REGISTRY_TIMEOUT_MS = 3e3;
+function loadCache() {
+  if (!existsSync5(CACHE_FILE)) return null;
+  try {
+    return JSON.parse(readFileSync4(CACHE_FILE, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function saveCache(cache) {
+  if (!existsSync5(CONFIG_DIR)) {
+    mkdirSync4(CONFIG_DIR, { recursive: true, mode: 448 });
+  }
+  writeFileSync4(CACHE_FILE, JSON.stringify(cache), { mode: 384 });
+}
+function isNewer(latest, current) {
+  const parse = (v) => v.replace(/^v/, "").split(".").map(Number);
+  const [lMaj, lMin, lPat] = parse(latest);
+  const [cMaj, cMin, cPat] = parse(current);
+  if (lMaj !== cMaj) return lMaj > cMaj;
+  if (lMin !== cMin) return lMin > cMin;
+  return lPat > cPat;
+}
+async function fetchLatestVersion() {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), REGISTRY_TIMEOUT_MS);
+  try {
+    const res = await fetch("https://registry.npmjs.org/@betterness/cli/latest", {
+      headers: { Accept: "application/json" },
+      signal: controller.signal
+    });
+    clearTimeout(timeoutId);
+    if (!res.ok) return null;
+    const data = await res.json();
+    return data.version ?? null;
+  } catch {
+    clearTimeout(timeoutId);
+    return null;
+  }
+}
+function scheduleUpdateCheck() {
+  const currentVersion = "1.3.4";
+  if (currentVersion === "0.0.0") return;
+  const cache = loadCache();
+  if (cache && Date.now() - cache.lastCheck < CHECK_INTERVAL_MS) {
+    if (isNewer(cache.latestVersion, currentVersion)) {
+      printNotice(currentVersion, cache.latestVersion);
+    }
+    return;
+  }
+  fetchLatestVersion().then((latest) => {
+    if (!latest) return;
+    saveCache({ lastCheck: Date.now(), latestVersion: latest });
+    if (isNewer(latest, currentVersion)) {
+      printNotice(currentVersion, latest);
+    }
+  }).catch(() => {
+  });
+}
+function printNotice(current, latest) {
+  const yellow = "\x1B[33m";
+  const bold = "\x1B[1m";
+  const reset = "\x1B[0m";
+  process.stderr.write(
+    `
+${yellow}Update available: ${bold}${current}${reset}${yellow} \u2192 ${bold}${latest}${reset}
+${yellow}Run \`npm i -g @betterness/cli\` to update.${reset}
+
+`
+  );
+}
+
 // src/index.ts
+scheduleUpdateCheck();
 var program = createProgram();
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@betterness/cli",
-  "version": "1.3.1",
+  "version": "1.3.4",
   "description": "Betterness CLI - Agent-first terminal interface for the Betterness platform",
   "type": "module",
   "bin": {