@trawlme/cli 3.7.0 → 3.7.1

package/README.md

@@ -48,14 +48,15 @@ All commands accept a global `--debug` flag to show full error stack traces on f
 ```
 trawl create <url> --prompt <goal> [--no-autofix] [--json]   # url also accepted as --url <url> (#116)
                                                               Create a persistent, self-healing scrap from a URL + a goal (AI-generated)
-trawl run <id> [--watch] [--json]              Run a scrap (blocks until finished)
 trawl list|ls [--json] [--status <success|failure|never|running|regression>] [--limit <n>] [--page <n>]
 trawl get <id> [--json]                        Get scrap details
+trawl run <id> [--watch] [--json]              Run a scrap (blocks until finished)
+trawl trigger <id> [--watch] [--wait] [--json] Launch a scrap as a background worker (returns immediately)
 trawl data <id> [--json] [--fresh] [--errors]  Get scrap data (last persisted run — read-only, no quota; --fresh to launch one)
 trawl history <id> [--json] [-n <limit>]       List past runs for a scrap (newest first)
 trawl run-info <hid> [--json]                  Show details of a single run
-trawl trigger <id> [--watch] [--wait] [--json] Launch a scrap as a background worker (returns immediately)
 trawl whoami [--json]                          Show the authenticated user's identity
+trawl token [--json]                           Print the stored session JWT (for MCP Bearer auth)
 trawl ping [--json]                            Health/version handshake against the Trawl API
 ```
 
@@ -131,10 +132,9 @@ You can also install skills standalone (without the CLI): `npx @trawlme/skills i
 ```
 trawl login [--url <url>] [--token <jwt>] [--email <email>] [--password <pass>] [--json]
 trawl logout [--json]
-trawl token [--json]                         Print the stored session JWT (for MCP Bearer auth)
 ```
 
-`login --json` prints `{"ok":true,"apiUrl","config",email?}` on success — never the raw token (that's `token`'s job). `token --json` prints `{"token","exp","expiresAt"}` instead of the bare JWT + stderr advisories. See [Non-interactive rule](#non-interactive-rule) below: a missing `--email`/`--password` refuses immediately (usage error, exit 2) instead of prompting when `--json` is set or stdin/stdout isn't a real TTY.
+`login --json` prints `{"ok":true,"apiUrl","config",email?}` on success — never the raw token (that's `trawl token`'s job, in the [Core commands](#core-commands-agent--human) section above — non-interactive/agent-consumable, unlike `login`/`logout`). `token --json` prints `{"token","exp","expiresAt"}` instead of the bare JWT + stderr advisories. See [Non-interactive rule](#non-interactive-rule) below: a missing `--email`/`--password` refuses immediately (usage error, exit 2) instead of prompting when `--json` is set or stdin/stdout isn't a real TTY.
 
 ### Telemetry
 

package/dist/commands/scraps.js

@@ -340,6 +340,10 @@ export async function pollRunProgress(id, before, opts = {}) {
     }
     process.exitCode = 1;
 }
+// #149 item 3 — same shared-enum shape as VALID_TIERS below (~line 603):
+// keeps `--status`'s allowed values and its error message in one place,
+// mirrored from lastStatus()'s own return type so the two can never drift.
+const VALID_LAST_STATUSES = ['success', 'failure', 'never', 'running', 'regression'];
 // list — promoted to a top-level verb (#108, see the AttachOptions comment above)
 export function attachListCommand(parent, attachOpts = {}) {
     return parent
@@ -358,6 +362,14 @@ export function attachListCommand(parent, attachOpts = {}) {
         .option('--limit <n>', 'Show only the first N results')
         .option('--page <n>', 'Fetch a specific page only (50 per page, no auto-pagination)')
         .action(async (opts, cmd) => {
+        // #149 item 3 — validate --status against its enum the same way
+        // --tier already validates (usageError + return, checked first, before
+        // any other guard/async work — mirrors `create`/`update`'s --tier
+        // check below).
+        if (opts.status !== undefined && !VALID_LAST_STATUSES.includes(opts.status)) {
+            usageError(`Invalid --status "${opts.status}" (allowed: ${VALID_LAST_STATUSES.join(', ')})`, { json: opts.json });
+            return;
+        }
         // Guard: --limit and --page are mutually exclusive
         if (opts.limit !== undefined && opts.page !== undefined) {
             usageError('--limit and --page are mutually exclusive. Use one or the other.', { json: opts.json });
@@ -1118,7 +1130,7 @@ export function attachTriggerCommand(parent, attachOpts = {}) {
         .command('trigger <id>', attachOpts)
         .description('Launch a scrap as a background worker (returns immediately)')
         .option('-w, --watch', 'Poll for progress after triggering (#91 — the default async run happens in a separate cron pod; activities SSE never reaches it)')
-        .option('--wait', 'Run synchronously and wait for the result (legacy behaviour)')
+        .option('--wait', 'Run synchronously and wait for the result (legacy behaviour — prefer `trawl run` instead)')
         .option('--json', 'Output the raw trigger payload as JSON')
         .action(async (id, opts) => {
         validateObjectId(id);

package/dist/index.d.ts

@@ -95,6 +95,24 @@ export declare function hasJsonFlag(argv: string[]): boolean;
  * walks the whole tree and installs it everywhere. (#86 finding 3)
  */
 export declare function applyExitOverride(cmd: Command): void;
+/**
+ * #149 item 1 — commander's own usage-error line (unknown option, missing
+ * required arg, unknown command, …) is written via `Command#error()` ->
+ * `outputError()` straight to `process.stderr` BEFORE the exitOverride throw
+ * below is ever caught — in commander's own plain, uncolored `"error: …"`
+ * format, a visibly different convention from every other error this CLI
+ * prints (`reportError`'s `chalk.red('✗ ' + message)`). `configureOutput`'s
+ * `outputError` hook is exactly the one commander documents for reformatting
+ * the error text itself (`writeErr` also carries unrelated help output, e.g.
+ * `showHelpAfterError` — never enabled in this CLI, but out of scope to
+ * touch here). Overriding it on every node in the tree (same walk shape as
+ * applyExitOverride, for the same reason: addCommand()-attached subtrees
+ * don't otherwise inherit a parent's configureOutput) reformats that one line
+ * through the same red ✗ convention, stripping the redundant "error: " prefix
+ * first (stripCommanderErrorPrefix — the same prefix also leaks verbatim
+ * into the --json envelope's `message` field, see runCli's catch below).
+ */
+export declare function applyOutputConfiguration(cmd: Command): void;
 /**
  * #88 item 6 — best-effort command-name recovery for a commander parse error
  * that happened BEFORE any action ran, so `currentCommand` (the preAction

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { Command, CommanderError } from 'commander';
+import chalk from 'chalk';
 import { readFileSync, realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
@@ -14,7 +15,7 @@ import { whoami } from './commands/whoami.js';
 import { ping } from './commands/ping.js';
 import { autoUpdateInstalledSkills } from './lib/skills.js';
 import { initPostHog, captureCommand, shutdown, registerAllowedCommands } from './lib/posthog.js';
-import { classifyError, reportError } from './lib/errors.js';
+import { classifyError, reportError, stripCommanderErrorPrefix } from './lib/errors.js';
 import { renderPinch, pinchEnabled } from './lib/pinch.js';
 import { maybeNotifyUpdate, scheduleUpdateCheck } from './lib/updateNotifier.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -91,26 +92,39 @@ export function createProgram() {
         .description('Trawl CLI — manage scraps from the terminal')
         .version(pkg.version)
         .option('--debug', 'Show full error stack traces');
-    // Core verbs (#108) — promoted/listed first: create, run, list, get, data,
-    // history, run-info, trigger, whoami, ping. `list`/`get`/`run`/`data`/
-    // `history`/`run-info`/`trigger` are built via scraps.ts's exported
-    // attachXCommand() factories — the SAME definition also stays wired
-    // (hidden) under `scraps` there, so every pre-#108 `trawl scraps <verb>`
-    // invocation keeps resolving (no breaking change).
+    // Core verbs (#108) — promoted/listed first, registration order now
+    // follows the guided flow a new user (or agent) actually walks: create it
+    // → list/get to see it → run/trigger to execute it → data to read the
+    // result → history/run-info for deeper diagnostics → whoami/token/ping as
+    // standalone identity/credential/health utilities (#149 item 6 — the
+    // pre-#149 order had `run` wedged between `create` and `list`, and
+    // `trigger` stranded after `run-info`, both ahead of ever having listed or
+    // inspected anything). `list`/`get`/`run`/`data`/`history`/`run-info`/
+    // `trigger` are built via scraps.ts's exported attachXCommand() factories —
+    // the SAME definition also stays wired (hidden) under `scraps` there, so
+    // every pre-#108 `trawl scraps <verb>` invocation keeps resolving (no
+    // breaking change).
     //
     // #114 — `create` replaced `fetch` in this slot: `POST /api/ai/wizard`
     // (AI-generate + persist + first-run + autofix), a distinct command from
     // the still-untouched `trawl scraps create` (raw-script management verb).
+    //
+    // #149 item 5 — `token` promoted from Management into Core: it satisfies
+    // every criterion the CORE_GROUP heading itself claims (agent + human,
+    // `--json` first-class, never interactive) at least as well as `whoami`/
+    // `ping` do, and exists specifically to feed an agent's MCP Bearer auth
+    // header (`$(trawl token)`) — a Management/human-CI bucket undersells that.
     program.commandsGroup(CORE_GROUP);
     program.addCommand(create);
-    attachRunCommand(program);
     attachListCommand(program);
     attachGetCommand(program);
+    attachRunCommand(program);
+    attachTriggerCommand(program);
     attachDataCommand(program);
     attachHistoryCommand(program);
     attachRunInfoCommand(program);
-    attachTriggerCommand(program);
     program.addCommand(whoami);
+    program.addCommand(token);
     program.addCommand(ping);
     // Management (#108) — human/CI surface, grouped below. `scraps` still
     // holds every pre-#108 management command (create/update/delete/banner/
@@ -120,7 +134,6 @@ export function createProgram() {
     program.addCommand(skills);
     program.addCommand(login);
     program.addCommand(logout);
-    program.addCommand(token);
     program.addCommand(telemetry);
     program.addCommand(upgrade);
     return program;
@@ -216,6 +229,33 @@ export function applyExitOverride(cmd) {
     for (const sub of cmd.commands)
         applyExitOverride(sub);
 }
+/**
+ * #149 item 1 — commander's own usage-error line (unknown option, missing
+ * required arg, unknown command, …) is written via `Command#error()` ->
+ * `outputError()` straight to `process.stderr` BEFORE the exitOverride throw
+ * below is ever caught — in commander's own plain, uncolored `"error: …"`
+ * format, a visibly different convention from every other error this CLI
+ * prints (`reportError`'s `chalk.red('✗ ' + message)`). `configureOutput`'s
+ * `outputError` hook is exactly the one commander documents for reformatting
+ * the error text itself (`writeErr` also carries unrelated help output, e.g.
+ * `showHelpAfterError` — never enabled in this CLI, but out of scope to
+ * touch here). Overriding it on every node in the tree (same walk shape as
+ * applyExitOverride, for the same reason: addCommand()-attached subtrees
+ * don't otherwise inherit a parent's configureOutput) reformats that one line
+ * through the same red ✗ convention, stripping the redundant "error: " prefix
+ * first (stripCommanderErrorPrefix — the same prefix also leaks verbatim
+ * into the --json envelope's `message` field, see runCli's catch below).
+ */
+export function applyOutputConfiguration(cmd) {
+    cmd.configureOutput({
+        outputError: (str, write) => {
+            const withoutNewline = str.endsWith('\n') ? str.slice(0, -1) : str;
+            write(chalk.red('✗ ' + stripCommanderErrorPrefix(withoutNewline)) + '\n');
+        },
+    });
+    for (const sub of cmd.commands)
+        applyOutputConfiguration(sub);
+}
 /** Commander's own codes for a successful --help/--version/`help` query —
  * these already printed their own output (to stdout) via commander itself;
  * runCli's catch must treat them as a clean exit, not an error. (#86 finding 3) */
@@ -264,6 +304,9 @@ export async function runCli(argv = process.argv) {
     // including subcommands added via addCommand() that don't otherwise
     // inherit it. (#86 finding 3)
     applyExitOverride(program);
+    // Same tree-walk requirement as applyExitOverride, same reason — installs
+    // the unified red ✗ error formatting on every node. (#149 item 1)
+    applyOutputConfiguration(program);
     const commandNames = collectCommandNames(program);
     // #88 item 6 — 'unknown' is a legitimate resolveCommandName() output (the
     // fallback for "no command resolved at all"), not free-form user input —
@@ -334,16 +377,22 @@ export async function runCli(argv = process.argv) {
             else {
                 // A usage error (unknown option/command, missing required arg, …) —
                 // commander already wrote its own human-readable line to stderr via
-                // Command#error(), so this never duplicates it. Force exit code 2
-                // (usage) regardless of whichever code commander suggests (it
-                // defaults these to 1), and add the --json machine envelope when
-                // resolvable — parsing failed before any command's own --json flag
-                // could be read off `currentCommand` (preAction never fired), so
-                // scan raw argv instead. (#86 finding 3)
+                // Command#error() (now reformatted through the same red ✗ convention
+                // by applyOutputConfiguration, #149 item 1), so this never duplicates
+                // it. Force exit code 2 (usage) regardless of whichever code
+                // commander suggests (it defaults these to 1), and add the --json
+                // machine envelope when resolvable — parsing failed before any
+                // command's own --json flag could be read off `currentCommand`
+                // (preAction never fired), so scan raw argv instead. (#86 finding 3)
                 if (isDebug)
                     console.error(err);
                 if (hasJsonFlag(argv)) {
-                    console.log(JSON.stringify({ error: { message: err.message, kind: 'usage' } }));
+                    // #149 item 2 — err.message still carries commander's own literal
+                    // "error: " prefix (set on the CommanderError itself, independent
+                    // of the outputError override above, which only reformats what
+                    // gets WRITTEN to stderr) — strip it so the envelope's `message`
+                    // stays clean for a machine parser.
+                    console.log(JSON.stringify({ error: { message: stripCommanderErrorPrefix(err.message), kind: 'usage' } }));
                 }
                 process.exitCode = 2;
                 // #88 item 6 — currentCommand is still undefined here whenever the

package/dist/lib/errors.d.ts

@@ -21,6 +21,18 @@ export declare class UsageError extends Error {
 export declare class RefusalError extends Error {
     constructor(message: string);
 }
+/**
+ * Commander prefixes every one of its own usage-error messages with the
+ * literal `"error: "` (see `missingArgument`/`unknownOption`/`unknownCommand`
+ * etc. in commander's `command.js`) — harmless for its own plain default
+ * line, but redundant once this CLI reuses that message itself: (1) baked
+ * into a `--json` envelope's `message` field, a human-facing "error: " prefix
+ * is dead weight for a machine parser that already reads `kind:"usage"`; (2)
+ * reformatted through the app's own `chalk.red('✗ ' + message)` convention it
+ * would double up as "✗ error: unknown option …". Idempotent — a message
+ * that never had the prefix passes through unchanged. (#149 items 1/2)
+ */
+export declare function stripCommanderErrorPrefix(message: string): string;
 export interface ErrorEnvelope {
     message: string;
     status?: number;

package/dist/lib/errors.js

@@ -29,6 +29,20 @@ export class RefusalError extends Error {
         this.name = 'RefusalError';
     }
 }
+/**
+ * Commander prefixes every one of its own usage-error messages with the
+ * literal `"error: "` (see `missingArgument`/`unknownOption`/`unknownCommand`
+ * etc. in commander's `command.js`) — harmless for its own plain default
+ * line, but redundant once this CLI reuses that message itself: (1) baked
+ * into a `--json` envelope's `message` field, a human-facing "error: " prefix
+ * is dead weight for a machine parser that already reads `kind:"usage"`; (2)
+ * reformatted through the app's own `chalk.red('✗ ' + message)` convention it
+ * would double up as "✗ error: unknown option …". Idempotent — a message
+ * that never had the prefix passes through unchanged. (#149 items 1/2)
+ */
+export function stripCommanderErrorPrefix(message) {
+    return message.startsWith('error: ') ? message.slice('error: '.length) : message;
+}
 /**
  * Central status → exit-code map (#71 findings 13/14/60). Agents driving this
  * CLI unattended need to tell "you're not logged in" (3) from "that id

package/docs/agent-quickstart.md

@@ -20,21 +20,22 @@ agent should never need them.)
 
 ## Core commands (agent + human)
 
-These ten commands are the CLI's agent+human surface — `--json` is
+These eleven commands are the CLI's agent+human surface — `--json` is
 first-class on every one, and none of them ever blocks on a prompt (see
 [Non-interactive contract](#non-interactive-contract) below):
 
 ```
 trawl create <url> --prompt <goal> [--no-autofix] [--json]   # url also accepted as --url <url> (#116)
                                                               Create a persistent, self-healing scrap from a URL + a goal (AI-generated)
-trawl run <id> [--watch] [--json]              Run a scrap (blocks until finished)
 trawl list|ls [--json] [--status <s>] [--limit <n>] [--page <n>]   List all scraps
 trawl get <id> [--json]                        Get scrap details
+trawl run <id> [--watch] [--json]              Run a scrap (blocks until finished)
+trawl trigger <id> [--watch] [--wait] [--json] Launch a scrap as a background worker
 trawl data <id> [--json] [--fresh] [--errors]  Get scrap data (last persisted run, or --fresh to launch one)
 trawl history <id> [--json] [-n <limit>]       List past runs for a scrap
 trawl run-info <hid> [--json]                  Show details of a single run
-trawl trigger <id> [--watch] [--wait] [--json] Launch a scrap as a background worker
 trawl whoami [--json]                          Show the authenticated user's identity
+trawl token [--json]                           Print the stored session JWT (for MCP Bearer auth)
 trawl ping [--json]                            Health/version handshake against the Trawl API
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trawlme/cli",
-  "version": "3.7.0",
+  "version": "3.7.1",
   "description": "Trawl CLI — manage scraps from the terminal",
   "type": "module",
   "bin": {