@betterness/cli 1.0.0 → 1.1.0

package/CLI_REFERENCE.md

@@ -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

@@ -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](https://github.com/Betterness/betterness-cli/blob/main/CLI_REFERENCE.md) for the complete list of commands, options, and descriptions.
+
+## License
+
+Proprietary.

package/dist/index.js

@@ -92,10 +92,10 @@ var ApiClient = class {
   constructor(options = {}) {
     const credentials = resolveCredentials(options.apiKey);
     this.apiKey = credentials.apiKey;
-    const apiUrl = process.env.BETTERNESS_API_URL || "";
+    const apiUrl = "https://api.betterness.com";
     if (!apiUrl) {
       throw new CliError(
-        "No API URL configured. Set BETTERNESS_API_URL or rebuild with BETTERNESS_BUILD_API_URL.",
+        "No API URL configured. This is a build error \u2014 BETTERNESS_API_URL should be baked in at build time.",
         "CONFIG_MISSING"
       );
     }
@@ -125,7 +125,7 @@ var ApiClient = class {
           headers: {
             "Authorization": `Bearer ${this.apiKey}`,
             "Content-Type": "application/json",
-            "User-Agent": "betterness-cli/0.1.0",
+            "User-Agent": `betterness-cli/${"1.1.0"}`,
             "Accept": "application/json"
           },
           body: body ? JSON.stringify(body) : void 0,
@@ -189,7 +189,7 @@ var ApiClient = class {
         method: "POST",
         headers: {
           "Authorization": `Bearer ${this.apiKey}`,
-          "User-Agent": "betterness-cli/0.1.0",
+          "User-Agent": `betterness-cli/${"1.1.0"}`,
           "Accept": "application/json"
         },
         body: formData,
@@ -1341,10 +1341,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: existsSync2 } = await import("fs");
+      const { existsSync: existsSync3 } = await import("fs");
       const { resolve } = await import("path");
       const filePath = resolve(opts.file);
-      if (!existsSync2(filePath)) {
+      if (!existsSync3(filePath)) {
         console.error(`File not found: ${filePath}`);
         process.exit(1);
       }
@@ -1806,10 +1806,47 @@ function registerSchemaCommand(program2) {
   });
 }
 
+// src/commands/debug.ts
+import { homedir as homedir2 } from "os";
+import { join as join2 } from "path";
+import { existsSync as existsSync2 } 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 = join2(homedir2(), ".betterness", "credentials.json");
+    const stored = loadCredentials();
+    const envKey = process.env.BETTERNESS_API_KEY;
+    const parentOpts = cmd.optsWithGlobals();
+    const authSource = parentOpts.apiKey ? "--api-key flag" : envKey ? "BETTERNESS_API_KEY env" : stored ? "~/.betterness/credentials.json" : "none";
+    const config = {
+      version: "1.1.0",
+      apiUrl: "https://api.betterness.com",
+      authSource,
+      credentialsFile: credentialsPath,
+      credentialsExists: String(existsSync2(credentialsPath))
+    };
+    if (stored?.email) {
+      config.storedEmail = stored.email;
+    }
+    if (stored?.savedAt) {
+      config.credentialsSavedAt = stored.savedAt;
+    }
+    const parentFormat = parentOpts.json ? "json" : parentOpts.markdown ? "markdown" : "table";
+    if (parentFormat === "json") {
+      console.log(JSON.stringify(config, null, 2));
+    } else {
+      const maxKey = Math.max(...Object.keys(config).map((k) => k.length));
+      for (const [key, value] of Object.entries(config)) {
+        console.log(`${key.padEnd(maxKey)}  ${value}`);
+      }
+    }
+  });
+}
+
 // src/program.ts
 function createProgram() {
   const program2 = new Command();
-  program2.name("betterness").description("Betterness CLI - Agent-first terminal interface for the Betterness platform").version("0.1.0").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.1.0").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);
@@ -1827,6 +1864,7 @@ function createProgram() {
   registerSmartListingsCommands(program2);
   registerWorkflowCommands(program2);
   registerSchemaCommand(program2);
+  registerDebugCommands(program2);
   return program2;
 }
 

package/package.json

@@ -1,27 +1,27 @@
 {
   "name": "@betterness/cli",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "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"
   },
   "scripts": {
-    "dev": "tsx src/index.ts",
-    "dev:watch": "tsup --watch",
+    "dev": "npm run build && ln -sf $(pwd)/dist/index.js /usr/local/bin/bttr && chmod +x /usr/local/bin/bttr",
     "build": "tsup",
     "lint": "eslint src/",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "test:watch": "vitest",
     "docs": "tsx scripts/generate-docs.ts",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "NODE_ENV=production npm run build"
   },
   "engines": {
     "node": ">=20.0.0"