@purveyors/cli 0.8.3 → 0.9.0

package/dist/commands/context.js

@@ -1,294 +1,224 @@
 import { Command } from 'commander';
-// ─── Agent Context Reference ──────────────────────────────────────────────────
-//
-// This text is optimized for token efficiency: dense, structured, no fluff.
-// An agent reading this once should be able to use every CLI command correctly.
+// This text is intentionally dense. An agent should be able to read it once,
+// then use the CLI correctly without hunting through help output.
 const CONTEXT_TEXT = `
-PURVEY CLI — Agent Reference v0.7
-==================================
-CLI for purveyors.io coffee marketplace. Node >=20 required.
-Credentials: ~/.config/purvey/credentials.json (auto-refreshed, do not edit)
+PURVEY CLI - Agent Reference
+============================
+Official CLI for purveyors.io. Node.js 20+.
+Credentials file: ~/.config/purvey/credentials.json
+Config file: ~/.config/purvey/config.json
 
 ROLES
 -----
-viewer  — catalog commands only (no login required for catalog search/get/stats)
-member  — all commands; required for inventory, roast, sales, tasting
+viewer  valid authenticated session; required for catalog commands
+member  required for inventory, roast, sales, and tasting commands
 
-AUTHENTICATION
---------------
-Browser login (interactive):
+AUTH
+----
+Interactive login:
   purvey auth login
 
-Headless login (agents/CI — no browser):
+Headless login:
   purvey auth login --headless
-  → prints Google OAuth URL
-  → user opens URL, signs in, copies callback URL
-  → paste callback URL back at prompt
-  Token auto-refreshes; no action needed between sessions.
+  1. CLI prints a Google OAuth URL
+  2. User opens it in any browser and signs in
+  3. User pastes the full callback URL back into the terminal
 
-Check status:
-  purvey auth status           # human-readable in terminal; compact JSON when piped
-  purvey auth status --pretty  # indented/colorized JSON (human reading)
-  purvey auth status | jq '.email'  # compact JSON on stdout
+Status:
+  purvey auth status
+  purvey auth status --pretty
 
 Logout:
   purvey auth logout
 
-OUTPUT FORMATS
+OUTPUT
+------
+Most commands emit compact JSON to stdout by default.
+Use --json to request compact JSON explicitly.
+Use --pretty for indented JSON.
+Use --csv for array-shaped results that support CSV output.
+User feedback goes to stderr.
+
+Important exception:
+- auth status prints human-readable output in an interactive TTY unless --json, --pretty, or --csv is passed; otherwise it emits structured output
+
+ID MAP
+------
+catalog_id      coffee_catalog row; used by catalog get, inventory add --catalog-id, tasting get, roast list --catalog-id
+inventory_id    green_coffee_inv row; used by inventory get/update/delete, roast --coffee-id, roast list --coffee-id, tasting rate
+roast_id        roast_data row; used by roast get/delete, roast list --roast-id, sales --roast-id
+sale_id         coffee_sales row; used by sales update/delete
+
+COMMANDS
+--------
+auth
+  login [--headless]
+  status
+  logout
+
+catalog
+  search [options]
+    --origin <text>
+    --process <method>
+    --price-min <n>
+    --price-max <n>
+    --flavor <keywords>
+    --name <text>
+    --supplier <name>
+    --ids <n,n,...>
+    --variety <text>
+    --drying-method <text>
+    --stocked-days <n>
+    --stocked
+    --sort <price|price-desc|name|origin|newest>
+    --offset <n>
+    --limit <n>
+  get <catalog_id>
+  stats
+  similar <catalog_id>
+    --threshold <0-1>     default 0.70
+    --limit <n>           default 10
+    --stocked-only
+
+inventory (member)
+  list [--stocked] [--limit <n>]
+  get <inventory_id>
+  add
+    --catalog-id <id>     required in flag mode
+    --qty <lbs>           required in flag mode
+    --cost <dollars>
+    --tax-ship <dollars>
+    --notes <text>
+    --purchase-date <YYYY-MM-DD>
+    --form
+  update <inventory_id>
+    --qty <lbs>
+    --cost <dollars>
+    --tax-ship <dollars>
+    --notes <text>
+    --stocked <true|false>
+  delete <inventory_id> [--yes]
+
+roast (member)
+  list
+    --coffee-id <inventory_id>
+    --roast-id <roast_id>
+    --batch-name <text>
+    --date-start <YYYY-MM-DD>
+    --date-end <YYYY-MM-DD>
+    --stocked
+    --catalog-id <catalog_id>
+    --limit <n>
+  get <roast_id>
+    --include-temps
+    --include-events
+  create
+    --coffee-id <inventory_id>   required in flag mode
+    --batch-name <name>
+    --oz-in <oz>
+    --oz-out <oz>
+    --roast-date <YYYY-MM-DD>
+    --notes <text>
+    --form
+  update <roast_id>
+    --notes <text>
+    --oz-out <oz>
+    --batch-name <name>
+    --targets <text>
+  delete <roast_id> [--yes]
+  import [file]
+    --coffee-id <inventory_id>   required in flag mode
+    --batch-name <name>
+    --oz-in <oz>
+    --roast-notes <text>
+    --form
+  watch [directory]
+    --coffee-id <inventory_id>   required unless --auto-match
+    --batch-prefix <name>
+    --prompt-each
+    --auto-match                 mutually exclusive with --coffee-id
+    --resume
+    --form
+
+sales (member)
+  list [--limit <n>]
+  record
+    --roast-id <roast_id>   required in flag mode
+    --oz <amount>           required in flag mode
+    --price <dollars>       required in flag mode
+    --buyer <name>
+    --sell-date <YYYY-MM-DD>
+    --form
+  update <sale_id>
+    --oz <amount>
+    --price <dollars>
+    --buyer <name>
+    --sell-date <YYYY-MM-DD>
+  delete <sale_id> [--yes]
+
+tasting (member)
+  get <catalog_id>
+    --filter <user|supplier|both>   default both
+  rate [inventory_id]
+    --aroma <1-5>        required in flag mode
+    --body <1-5>         required in flag mode
+    --acidity <1-5>      required in flag mode
+    --sweetness <1-5>    required in flag mode
+    --aftertaste <1-5>   required in flag mode
+    --brew-method <method>
+    --notes <text>
+    --form
+
+config
+  list
+  get <key>
+  set <key> <value>
+  reset
+
+Current config keys:
+  form-mode  true|false
+
+WORKFLOWS
+---------
+Catalog -> inventory:
+  purvey catalog search --origin "Ethiopia" --stocked --pretty
+  purvey inventory add --catalog-id 128 --qty 10 --cost 8.50
+
+Import a roast from Artisan:
+  purvey inventory list --stocked --pretty
+  purvey roast import ~/artisan/ethiopia.alog --coffee-id 7 --pretty
+
+Watch a folder for new roasts:
+  purvey roast watch ~/artisan/ --coffee-id 7
+  purvey roast watch ~/artisan/ --auto-match
+  purvey roast watch --resume
+
+Rate coffee and record a sale:
+  purvey tasting rate 7 --aroma 4 --body 3 --acidity 5 --sweetness 4 --aftertaste 4
+  purvey sales record --roast-id 123 --oz 12 --price 22.00 --buyer "Jane Smith"
+
+ERROR PATTERNS
 --------------
-Default: compact single-line JSON (machine-readable, pipeable to jq)
---pretty: indented + colorized JSON (human-readable)
---csv:    CSV rows (pipeable to spreadsheets)
-User feedback (spinners, success/error) → stderr only; stdout is always clean data.
-
-DATA MODEL
-----------
-coffee_catalog (catalog_id)
-  └─ green_coffee_inv (id, user, catalog_id)   ← your inventory
-       ├─ roast_data (roast_id, coffee_id)      ← your roast profiles
-       │    ├─ roast_temperatures               ← temperature curve
-       │    └─ roast_events                     ← FC, drop, etc.
-       ├─ coffee_sales (id, roast_id)           ← your sales
-       └─ cupping notes stored on green_coffee_inv (aroma/body/acidity/sweetness/aftertaste)
-
-CATALOG COMMANDS (no auth required)
--------------------------------------
-Search the public catalog:
-  purvey catalog search [options]
-  Options (all optional):
-    --origin <text>      country/region (e.g. "Ethiopia", "Colombia")
-    --process <method>   natural|washed|honey
-    --price-min <n>      min USD/lb (filters on price_per_lb)
-    --price-max <n>      max USD/lb (filters on price_per_lb)
-    --flavor <keywords>  comma-separated (e.g. "blueberry,citrus")
-    --name <text>        filter by coffee name (partial match, case-insensitive)
-    --supplier <name>    filter by supplier/source name (partial match, case-insensitive)
-    --ids <n,n,...>      fetch specific catalog IDs (comma-separated, ignores limit)
-    --stocked            only currently stocked
-    --sort <field>       price|price-desc|name|origin|newest
-    --offset <n>         skip N results for pagination (default: 0)
-    --limit <n>          max results (default: 10)
-  Returns: array of catalog items with id, name, origin, process, flavor_notes, price_per_lb, cost_lb, stocked
-
-Get one catalog item by ID:
-  purvey catalog get <catalog_id>
-  Returns: single catalog item object
-
-Catalog statistics:
-  purvey catalog stats
-  Returns: aggregate stats (count, avg_price, origins, processes, etc.)
-
-INVENTORY COMMANDS (member role required)
-------------------------------------------
-List your green coffee inventory:
-  purvey inventory list [options]
-  Options:
-    --stocked         only stocked beans
-    --limit <n>       max results (default: 20)
-  Returns: array with id, catalog_id, qty, cost, stocked, purchase_date, plus joined catalog fields
-
-Get one inventory item:
-  purvey inventory get <id>
-  Returns: single inventory item
-
-Add bean to inventory (REQUIRED: --catalog-id, --qty):
-  purvey inventory add --catalog-id <id> --qty <lbs> [options]
-  Options:
-    --catalog-id <id>    [REQUIRED] coffee_catalog id
-    --qty <lbs>          [REQUIRED] pounds purchased
-    --cost <dollars>     cost per lb
-    --tax-ship <dollars> tax + shipping cost
-    --notes <text>       notes
-    --purchase-date <YYYY-MM-DD>  defaults to today
-    --form               interactive wizard
-  Returns: created inventory item
-
-Update inventory item:
-  purvey inventory update <id> [options]
-  Options (at least one required):
-    --qty <lbs>          updated quantity
-    --cost <dollars>     updated cost
-    --tax-ship <dollars> updated tax/shipping
-    --notes <text>       updated notes
-    --stocked <true|false>  mark as stocked/unstocked
-  Returns: updated inventory item
-
-Delete inventory item:
-  purvey inventory delete <id> [-y]
-  -y skips confirmation prompt
-
-ROAST COMMANDS (member role required)
----------------------------------------
-List roast profiles:
-  purvey roast list [options]
-  Options:
-    --coffee-id <id>  filter by inventory item id
-    --limit <n>       max results (default: 20)
-  Returns: array of roast profiles with roast_id, batch_name, roast_date, oz_in, oz_out
-
-Get roast profile:
-  purvey roast get <roast_id> [options]
-  Options:
-    --include-temps    include temperature curve data
-    --include-events   include roast events (FC, drop, etc.)
-  Returns: roast profile object
-
-Create roast profile (REQUIRED: --coffee-id):
-  purvey roast create --coffee-id <id> [options]
-  Options:
-    --coffee-id <id>       [REQUIRED] green_coffee_inv id
-    --batch-name <name>    defaults to "CoffeeName YYYY-MM-DD"
-    --oz-in <oz>           green weight in ounces
-    --oz-out <oz>          roasted weight in ounces
-    --roast-date <YYYY-MM-DD>  defaults to today
-    --notes <text>         roast notes
-    --form                 interactive wizard
-  Returns: created roast profile
-
-Delete roast profile:
-  purvey roast delete <roast_id> [-y]
-
-Update roast profile:
-  purvey roast update <roast_id> [options]
-  Options:
-    --notes <text>         updated roast notes
-    --oz-out <oz>          updated roasted weight (recalculates weight_loss_percent)
-    --batch-name <name>    updated batch name
-    --targets <text>       updated roast targets (planning/goals)
-  At least one flag required.
+Not logged in:
+  run purvey auth login or purvey auth login --headless
 
-Import Artisan .alog file (REQUIRED: <file>, --coffee-id):
-  purvey roast import <file.alog> --coffee-id <id> [options]
-  Options:
-    --coffee-id <id>       [REQUIRED] green_coffee_inv id
-    --batch-name <name>    auto-generated if omitted
-    --oz-in <oz>           extracted from .alog if omitted
-    --roast-notes <text>   additional notes
-    --form                 interactive wizard
-  Returns: roast profile + milestone_events + control_events counts
-
-Watch directory for new .alog files (REQUIRED: <directory>):
-  purvey roast watch <directory> [options]
-  Options:
-    --coffee-id <id>    [REQUIRED unless --auto-match] green_coffee_inv id
-    --batch-prefix <name>  prefix for batch names
-    --auto-match           AI matches bean per file (requires member role; mutually exclusive with --coffee-id)
-    --prompt-each          prompt for bean on each new file
-    --resume               resume previous watch session
-    --form                 interactive wizard
-  Runs continuously (Ctrl+C to stop). Persists session for --resume.
-
-SALES COMMANDS (member role required)
----------------------------------------
-List sales:
-  purvey sales list [--limit <n>]
-  Returns: array with id, roast_id, oz, price, buyer, sell_date
-
-Record sale (REQUIRED: --roast-id, --oz, --price):
-  purvey sales record --roast-id <id> --oz <amount> --price <dollars> [options]
-  Options:
-    --roast-id <id>        [REQUIRED] roast_data id
-    --oz <amount>          [REQUIRED] ounces sold
-    --price <dollars>      [REQUIRED] sale price
-    --buyer <name>         buyer name/identifier
-    --sell-date <YYYY-MM-DD>  defaults to today
-    --form                 interactive wizard
-  Returns: created sale record
-
-Update sale:
-  purvey sales update <id> [--oz <n>] [--price <n>] [--buyer <name>] [--sell-date <date>]
-
-Delete sale:
-  purvey sales delete <id> [-y]
-
-TASTING COMMANDS (member role required)
------------------------------------------
-Get tasting notes for a catalog item:
-  purvey tasting get <catalog_id> [--filter user|supplier|both]
-  --filter both (default): returns {supplier: {...}, user: {...}}
-  --filter user:     only your cupping notes from green_coffee_inv
-  --filter supplier: only the supplier's flavor notes from coffee_catalog
-
-Rate a bean (REQUIRED: <inventory_id>, all score flags):
-  purvey tasting rate <inventory_id> --aroma <1-5> --body <1-5> --acidity <1-5> --sweetness <1-5> --aftertaste <1-5> [options]
-  Options:
-    --aroma <1-5>       [REQUIRED in flag mode] integer 1-5
-    --body <1-5>        [REQUIRED in flag mode] integer 1-5
-    --acidity <1-5>     [REQUIRED in flag mode] integer 1-5
-    --sweetness <1-5>   [REQUIRED in flag mode] integer 1-5
-    --aftertaste <1-5>  [REQUIRED in flag mode] integer 1-5
-    --brew-method       pour_over|french_press|espresso|etc
-    --notes <text>      tasting notes
-    --form              interactive wizard
-  Note: <inventory_id> is green_coffee_inv.id, NOT catalog_id.
-  Scores are stored on the green_coffee_inv row.
-
-CONFIG COMMANDS
----------------
-  purvey config list                      show all config
-  purvey config get form-mode             get a value
-  purvey config set form-mode true|false  set a value
-  purvey config reset                     clear all config
-
-Config keys:
-  form-mode   true|false — when true, write commands auto-enter interactive
-              wizard if required args are missing (default: false)
-
-COMMON WORKFLOWS
-----------------
-1. Import a roast and rate it:
-   purvey inventory list --stocked --pretty          # find your bean id
-   purvey roast import roast.alog --coffee-id 42     # import
-   purvey tasting rate 42 --aroma 4 --body 3 --acidity 5 --sweetness 4 --aftertaste 4
-
-2. Full workflow: buy → roast → sell:
-   purvey catalog search --origin "Ethiopia" --stocked --pretty
-   purvey inventory add --catalog-id 128 --qty 10 --cost 8.50
-   purvey roast create --coffee-id 7 --oz-in 16 --batch-name "Ethiopia Guji Light"
-   purvey sales record --roast-id 123 --oz 12 --price 22.00 --buyer "Jane"
-
-3. Watch directory and auto-import roasts:
-   purvey roast watch ~/artisan/ --coffee-id 7
-   # or with AI bean matching:
-   purvey roast watch ~/artisan/ --auto-match
-
-4. Find a coffee and check tasting notes:
-   purvey catalog search --flavor "blueberry,floral" --pretty
-   purvey tasting get 128 --filter both --pretty
-
-ERROR HANDLING
---------------
-Exit 0: success
-Exit 1: error (auth failure, not found, validation error, API error)
-Errors go to stderr as: Error: <message>
+Wrong ID type:
+  verify whether the command wants catalog_id, inventory_id, roast_id, or sale_id
 
-Common errors:
-  "Not logged in"        → run: purvey auth login [--headless]
-  "Not found"            → check the ID; must be yours (RLS enforced)
-  "INVALID_ARGUMENT"     → check flags; use --form for interactive mode
-  "--auto-match and --coffee-id are mutually exclusive" → use one or the other
+Missing required args in write commands:
+  pass the required flags or use --form
 
-ID TYPES (avoid confusion)
----------------------------
-catalog_id       → coffee_catalog table; used with: catalog get, inventory add --catalog-id, tasting get
-inventory_id     → green_coffee_inv table (your beans); used with: inventory get/update/delete, roast --coffee-id, tasting rate
-roast_id         → roast_data table; used with: roast get/delete, sales --roast-id
-sale_id          → coffee_sales table; used with: sales update/delete
+Mutually exclusive watch flags:
+  roast watch forbids using --auto-match together with --coffee-id
 `.trim();
-// ─── Command builder ──────────────────────────────────────────────────────────
-/**
- * `purvey context`
- * Outputs a comprehensive CLI reference for AI agent onboarding.
- * Optimized for token efficiency — dense, structured, no fluff.
- */
 export function buildContextCommand() {
     return new Command('context')
         .description('Output full CLI reference for AI agent onboarding')
         .addHelpText('after', `
 Examples:
-  purvey context                  # print full reference to stdout
-  purvey context | head -50       # preview first section
-  purvey context > cli-ref.txt    # save to file
+  purvey context
+  purvey context | head -50
+  purvey context > cli-reference.txt
 `)
         .action(() => {
         console.log(CONTEXT_TEXT);

package/dist/commands/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/commands/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,iFAAiF;AACjF,EAAE;AACF,4EAA4E;AAC5E,gFAAgF;AAEhF,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+QpB,CAAC,IAAI,EAAE,CAAC;AAET,iFAAiF;AAEjF;;;;GAIG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO,IAAI,OAAO,CAAC,SAAS,CAAC;SAC1B,WAAW,CAAC,mDAAmD,CAAC;SAChE,WAAW,CACV,OAAO,EACP;;;;;CAKL,CACI;SACA,MAAM,CAAC,GAAG,EAAE;QACX,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAC5B,CAAC,CAAC,CAAC;AACP,CAAC"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/commands/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,6EAA6E;AAC7E,kEAAkE;AAElE,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiNpB,CAAC,IAAI,EAAE,CAAC;AAET,MAAM,UAAU,mBAAmB;IACjC,OAAO,IAAI,OAAO,CAAC,SAAS,CAAC;SAC1B,WAAW,CAAC,mDAAmD,CAAC;SAChE,WAAW,CACV,OAAO,EACP;;;;;CAKL,CACI;SACA,MAAM,CAAC,GAAG,EAAE;QACX,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAC5B,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/commands/roast.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"roast.d.ts","sourceRoot":"","sources":["../../src/commands/roast.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgBpC,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAChB,eAAe,EAEhB,MAAM,iBAAiB,CAAC;AAOzB,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,CAAC;AAIhE;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAmuB3C"}
+{"version":3,"file":"roast.d.ts","sourceRoot":"","sources":["../../src/commands/roast.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgBpC,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAChB,eAAe,EAEhB,MAAM,iBAAiB,CAAC;AAOzB,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,CAAC;AAIhE;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAgyB3C"}

package/dist/commands/roast.js

@@ -22,24 +22,70 @@ export function buildRoastCommand() {
         .command('list')
         .description('List your roast profiles, sorted by date (newest first)')
         .option('--coffee-id <id>', 'Filter by green_coffee_inv ID')
+        .option('--roast-id <id>', 'Filter by roast profile ID')
+        .option('--batch-name <text>', 'Filter by batch name (partial match, case-insensitive)')
+        .option('--date-start <YYYY-MM-DD>', 'Only show roasts on or after this date')
+        .option('--date-end <YYYY-MM-DD>', 'Only show roasts on or before this date')
+        .option('--stocked', 'Only show roasts for currently stocked beans')
+        .option('--catalog-id <id>', 'Filter by coffee_catalog ID')
         .option('--limit <n>', 'Maximum results to return', '20')
         .addHelpText('after', `
 Examples:
   purvey roast list --pretty
   purvey roast list --coffee-id 7 --pretty
+  purvey roast list --roast-id 123 --pretty
+  purvey roast list --batch-name "Ethiopia Guji" --pretty
+  purvey roast list --date-start 2026-03-01 --date-end 2026-03-31
+  purvey roast list --stocked --limit 10
+  purvey roast list --catalog-id 128 --pretty
   purvey roast list --limit 5 | jq '.[].roast_id'
   purvey roast list --csv > roasts.csv
 
 Notes:
   --coffee-id filters by inventory item (green_coffee_inv.id), not catalog_id.
+  --roast-id filters by the exact roast profile ID while preserving list output shape.
+  --catalog-id filters by coffee_catalog ID (cross-reference from catalog search).
+  --batch-name accepts partial matches (case-insensitive).
+  --date-start and --date-end accept YYYY-MM-DD format; use together for a range.
+  --stocked only returns roasts for beans currently marked as stocked in inventory.
   Returns roast_id, batch_name, roast_date, oz_in, oz_out, and bean details.
   Requires authentication (member role).
 `)
         .action(withErrorHandling(async (opts, cmd) => {
         const globalOpts = cmd.optsWithGlobals();
         const { supabase, userId } = await requireAuth('member');
+        // Parse --date-start and --date-end format
+        const dateStart = opts.dateStart;
+        const dateEnd = opts.dateEnd;
+        if (dateStart && !/^\d{4}-\d{2}-\d{2}$/.test(dateStart)) {
+            throw new PrvrsError('INVALID_ARGUMENT', `Invalid --date-start: "${dateStart}". Must be YYYY-MM-DD format.`);
+        }
+        if (dateEnd && !/^\d{4}-\d{2}-\d{2}$/.test(dateEnd)) {
+            throw new PrvrsError('INVALID_ARGUMENT', `Invalid --date-end: "${dateEnd}". Must be YYYY-MM-DD format.`);
+        }
+        // Parse exact-id filters
+        let roastId;
+        if (opts.roastId !== undefined) {
+            roastId = parseInt(opts.roastId, 10);
+            if (isNaN(roastId) || roastId <= 0) {
+                throw new PrvrsError('INVALID_ARGUMENT', `Invalid --roast-id: "${opts.roastId}". Must be a positive integer.`);
+            }
+        }
+        let catalogId;
+        if (opts.catalogId !== undefined) {
+            catalogId = parseInt(opts.catalogId, 10);
+            if (isNaN(catalogId) || catalogId <= 0) {
+                throw new PrvrsError('INVALID_ARGUMENT', `Invalid --catalog-id: "${opts.catalogId}". Must be a positive integer.`);
+            }
+        }
         const data = await listRoasts(supabase, userId, {
             coffee_id: opts.coffeeId !== undefined ? parseInt(opts.coffeeId, 10) : undefined,
+            roast_id: roastId,
+            batch_name: opts.batchName,
+            date_start: dateStart,
+            date_end: dateEnd,
+            stocked_only: opts.stocked === true ? true : undefined,
+            catalog_id: catalogId,
             limit: Math.max(1, parseInt(opts.limit, 10)),
         });
         if (data.length === 0) {