@betterness/cli 1.3.2 → 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

@@ -419,7 +419,7 @@ var ApiClient = class {
           headers: {
             "Authorization": `Bearer ${this.apiKey}`,
             "Content-Type": "application/json",
-            "User-Agent": `betterness-cli/${"1.3.2"}`,
+            "User-Agent": `betterness-cli/${"1.3.4"}`,
             "Accept": "application/json"
           },
           body: body ? JSON.stringify(body) : void 0,
@@ -483,7 +483,7 @@ var ApiClient = class {
         method: "POST",
         headers: {
           "Authorization": `Bearer ${this.apiKey}`,
-          "User-Agent": `betterness-cli/${"1.3.2"}`,
+          "User-Agent": `betterness-cli/${"1.3.4"}`,
           "Accept": "application/json"
         },
         body: formData,
@@ -848,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) {
@@ -2151,7 +2175,7 @@ function registerDebugCommands(program2) {
     const parentOpts = cmd.optsWithGlobals();
     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.2",
+      version: "1.3.4",
       apiUrl: "https://api.betterness.ai",
       auth0Domain: "betterness.us.auth0.com",
       auth0ClientId: "g4lqYHRQb2QMgdRKIlKwoTJl6eu41pWn",
@@ -2677,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.2").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);
@@ -2701,6 +2790,7 @@ function createProgram() {
   registerDebugCommands(program2);
   registerHealthProfileCommands(program2);
   registerMcpCommands(program2);
+  registerKnowledgeCommands(program2);
   return program2;
 }
 
@@ -2708,7 +2798,7 @@ function createProgram() {
 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 = 24 * 60 * 60 * 1e3;
+var CHECK_INTERVAL_MS = 60 * 60 * 1e3;
 var REGISTRY_TIMEOUT_MS = 3e3;
 function loadCache() {
   if (!existsSync5(CACHE_FILE)) return null;
@@ -2750,7 +2840,7 @@ async function fetchLatestVersion() {
   }
 }
 function scheduleUpdateCheck() {
-  const currentVersion = "1.3.2";
+  const currentVersion = "1.3.4";
   if (currentVersion === "0.0.0") return;
   const cache = loadCache();
   if (cache && Date.now() - cache.lastCheck < CHECK_INTERVAL_MS) {
@@ -2769,10 +2859,13 @@ function scheduleUpdateCheck() {
   });
 }
 function printNotice(current, latest) {
+  const yellow = "\x1B[33m";
+  const bold = "\x1B[1m";
+  const reset = "\x1B[0m";
   process.stderr.write(
     `
-Update available: ${current} \u2192 ${latest}
-Run \`npm i -g @betterness/cli\` to update.
+${yellow}Update available: ${bold}${current}${reset}${yellow} \u2192 ${bold}${latest}${reset}
+${yellow}Run \`npm i -g @betterness/cli\` to update.${reset}
 
 `
   );

package/package.json

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