@trawlme/cli 2.1.1 → 2.2.0

package/README.md

@@ -46,6 +46,8 @@ trawl data <id> [--json] [--fresh] [--errors]  Get scrap data (last persisted ru
 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 update <id> [-t <title>] [-u <url>] [-r <request>] [-d <description>] [--cron <expr>|--no-cron] [--alert <email>|--no-alert] [--autofix|--no-autofix] [-p <json>|--params-file <path>] [--tier <tier0|tier1|tier2|tier3|tier4>] [--force-tier <tier0|tier1|tier2|tier3|tier4>] [--json]
+                                                Update an existing scrap
 trawl whoami [--json]                          Show the authenticated user's identity
 trawl ping [--json]                            Health/version handshake against the Trawl API
 ```
@@ -54,7 +56,7 @@ trawl ping [--json]                            Health/version handshake against
 
 `create`/`whoami`/`ping` are fully non-interactive — all three read auth only from `TRAWL_TOKEN`/the stored login token, never prompt. `trawl create` runs the AI wizard server-side (`POST /api/ai/wizard`): generate scrap code from `--prompt` via LLM, persist the scrap, trigger its FIRST run, and auto-fix on failure (default on — `--no-autofix` disables it, sending `autoFix:false`). `success` is an honest outcome of that first run, not "did the HTTP call succeed" — a failed first run is still a 200 response (the scrap was still created; auto-fix, when enabled, retries in the background), and the CLI exits 1 in that case (both human and `--json` modes) even though `--json` always prints the raw payload verbatim. The call legitimately takes 30–250s+ server-side (AI generation + a real run), same long-run timeout as `run`/`data --fresh`/`trigger --wait` below. `trawl whoami`/`trawl ping` mirror the MCP `trawl_whoami`/`trawl_health_ping` tools as closely as the REST surface allows (`GET /api/users/me` / `GET /api/health`) — `ping`'s `--json` payload is admin-enriched (version/uptime/db) and just `{"status":"ok"}` for anyone else.
 
-> **`create` is NOT idempotent, and every wizard-created scrap runs on a DAILY cron by default.** A client-side timeout (exit `5`, a `NetworkError`) does not mean the wizard failed server-side — scrap creation + the first run keep going after the CLI gives up waiting, so the scrap may already exist. Run `trawl list` and look for a matching URL/title **before** retrying — a blind retry creates a DUPLICATE scrap and burns AI-generation quota a second time for the same goal. Separately, the scrap the wizard creates is scheduled to re-run every day at 07:00 UTC (`cron: "0 7 * * *"`, hardcoded server-side, unrelated to `--no-autofix`) — each of those recurring runs consumes execute quota like any other run. Review the generated scrap, then change or disable the schedule with `trawl scraps update <id> --cron <expr>` (or `--no-cron` to disable it). Because the call can legitimately run 250s+, also confirm `TRAWL_TIMEOUT` isn't set to something tighter than `create` needs — the env var always wins over `create`'s own 300s default (see [Environment variables](#environment-variables)), so a value set for another purpose (e.g. a tight CI smoke-test budget) silently clamps `create` too; unset it or raise it before running `create`.
+> **`create` is NOT idempotent, and every wizard-created scrap runs on a DAILY cron by default.** A client-side timeout (exit `5`, a `NetworkError`) does not mean the wizard failed server-side — scrap creation + the first run keep going after the CLI gives up waiting, so the scrap may already exist. Run `trawl list` and look for a matching URL/title **before** retrying — a blind retry creates a DUPLICATE scrap and burns AI-generation quota a second time for the same goal. Separately, the scrap the wizard creates is scheduled to re-run every day at 07:00 UTC (`cron: "0 7 * * *"`, hardcoded server-side, unrelated to `--no-autofix`) — each of those recurring runs consumes execute quota like any other run. Review the generated scrap, then change or disable the schedule with `trawl update <id> --cron <expr>` (or `--no-cron` to disable it). Because the call can legitimately run 250s+, also confirm `TRAWL_TIMEOUT` isn't set to something tighter than `create` needs — the env var always wins over `create`'s own 300s default (see [Environment variables](#environment-variables)), so a value set for another purpose (e.g. a tight CI smoke-test budget) silently clamps `create` too; unset it or raise it before running `create`.
 
 - `list` has a short alias, `ls` (matches `trawl --help`'s `list|ls`).
 - `history` lists past runs (newest first); `run-info <hid>` shows details of a single run from that history.
@@ -68,7 +70,6 @@ trawl ping [--json]                            Health/version handshake against
 
 ```
 trawl scraps create -t <title> [-u <url>] [-r <request>] [-d <description>] [--tier <tier0|tier1|tier2|tier3|tier4>] [--json]
-trawl scraps update <id> [-t <title>] [-u <url>] [-r <request>] [-d <description>] [--cron <expr>|--no-cron] [--alert <email>|--no-alert] [--autofix|--no-autofix] [-p <json>|--params-file <path>] [--tier <tier0|tier1|tier2|tier3|tier4>] [--force-tier <tier0|tier1|tier2|tier3|tier4>] [--json]
 trawl scraps watch <id> [--json]
 trawl scraps doctor <id> [--json] [--autofix]
 trawl scraps autofix <id> [--json]

package/dist/commands/create.d.ts

@@ -30,7 +30,8 @@ export interface WizardResponse {
          * 'UTC'` — unconditionally, regardless of `--prompt`/`--no-autofix`.
          * Present on the scrap object returned here (the wizard controller
          * passes the created scrap straight through, no stripping) — change or
-         * disable it with `trawl scraps update <id> --cron <expr>` / `--no-cron`.
+         * disable it with `trawl update <id> --cron <expr>` / `--no-cron` (#120
+         * — `update` is now a promoted top-level verb, same as `get`/`run`/…).
          */
         cron?: string | null;
         cronTimezone?: string;

package/dist/commands/scraps.d.ts

@@ -140,6 +140,7 @@ export declare function pollRunProgress(id: string, before: BeforeRunState | und
 }): Promise<void>;
 export declare function attachListCommand(parent: Command, attachOpts?: AttachOptions): Command;
 export declare function attachGetCommand(parent: Command, attachOpts?: AttachOptions): Command;
+export declare function attachUpdateCommand(parent: Command, attachOpts?: AttachOptions): Command;
 export declare function attachRunCommand(parent: Command, attachOpts?: AttachOptions): Command;
 export declare function attachDataCommand(parent: Command, attachOpts?: AttachOptions): Command;
 export declare function attachHistoryCommand(parent: Command, attachOpts?: AttachOptions): Command;

package/dist/commands/scraps.js

@@ -583,129 +583,132 @@ scraps
     if (refused)
         process.exitCode = 1;
 });
-// update
-scraps
-    .command('update <id>')
-    .description('Update an existing scrap')
-    .option('-t, --title <title>', 'New title')
-    .option('-u, --url <url>', 'New target URL')
-    .option('-r, --request <request>', 'New request')
-    .option('-d, --description <text>', 'New description')
-    .option('--cron <expression>', 'Cron expression (empty string to disable)')
-    .option('--no-cron', 'Disable cron (set to null)')
-    .option('--alert <email>', 'Failure alert email (empty string to clear)')
-    .option('--no-alert', 'Disable failure alert email (set to null)')
-    .option('--autofix', 'Enable AI Fix (auto-recovery on selector breakage)')
-    .option('--no-autofix', 'Disable AI Fix')
-    .option('-p, --params <json>', 'Runtime params as JSON array of objects (e.g. \'[{"TRAWL.paramName":"value"}]\')')
-    .option('--params-file <path>', 'Runtime params from a JSON file')
-    .option('--tier <tier>', `Force proxy tier (${VALID_TIERS.join('|')})`)
-    .option('--force-tier <tier>', `Raise the proxy-tier ceiling PAST the auto-cap (${VALID_TIERS.join('|')}) — history-gated: may be refused or cost more`)
-    .option('--json', 'Output as JSON')
-    .action(async (id, opts) => {
-    validateObjectId(id);
-    if (opts.tier !== undefined && !VALID_TIERS.includes(opts.tier)) {
-        usageError(`Invalid --tier "${opts.tier}" (allowed: ${VALID_TIERS.join(', ')})`, { json: opts.json });
-        return;
-    }
-    if (opts.forceTier !== undefined && !VALID_TIERS.includes(opts.forceTier)) {
-        usageError(`Invalid --force-tier "${opts.forceTier}" (allowed: ${VALID_TIERS.join(', ')})`, { json: opts.json });
-        return;
-    }
-    const body = {};
-    if (opts.title !== undefined)
-        body.title = opts.title;
-    if (opts.url !== undefined)
-        body.url = opts.url;
-    if (opts.request !== undefined)
-        body.request = opts.request;
-    if (opts.description !== undefined)
-        body.description = opts.description;
-    if (opts.cron === false)
-        body.cron = null;
-    else if (typeof opts.cron === 'string')
-        body.cron = opts.cron === '' ? null : opts.cron;
-    if (opts.alert === false)
-        body.alert = null;
-    else if (typeof opts.alert === 'string')
-        body.alert = opts.alert === '' ? null : opts.alert;
-    if (opts.autofix === true)
-        body.autoFix = true;
-    else if (opts.autofix === false)
-        body.autoFix = false;
-    if (opts.params !== undefined || opts.paramsFile !== undefined) {
-        let raw;
-        if (opts.paramsFile) {
-            const { readFileSync } = await import('fs');
-            raw = readFileSync(opts.paramsFile, 'utf8');
+// update — promoted to a top-level verb (#108/#120)
+export function attachUpdateCommand(parent, attachOpts = {}) {
+    return parent
+        .command('update <id>', attachOpts)
+        .description('Update an existing scrap')
+        .option('-t, --title <title>', 'New title')
+        .option('-u, --url <url>', 'New target URL')
+        .option('-r, --request <request>', 'New request')
+        .option('-d, --description <text>', 'New description')
+        .option('--cron <expression>', 'Cron expression (empty string to disable)')
+        .option('--no-cron', 'Disable cron (set to null)')
+        .option('--alert <email>', 'Failure alert email (empty string to clear)')
+        .option('--no-alert', 'Disable failure alert email (set to null)')
+        .option('--autofix', 'Enable AI Fix (auto-recovery on selector breakage)')
+        .option('--no-autofix', 'Disable AI Fix')
+        .option('-p, --params <json>', 'Runtime params as JSON array of objects (e.g. \'[{"TRAWL.paramName":"value"}]\')')
+        .option('--params-file <path>', 'Runtime params from a JSON file')
+        .option('--tier <tier>', `Force proxy tier (${VALID_TIERS.join('|')})`)
+        .option('--force-tier <tier>', `Raise the proxy-tier ceiling PAST the auto-cap (${VALID_TIERS.join('|')}) — history-gated: may be refused or cost more`)
+        .option('--json', 'Output as JSON')
+        .action(async (id, opts) => {
+        validateObjectId(id);
+        if (opts.tier !== undefined && !VALID_TIERS.includes(opts.tier)) {
+            usageError(`Invalid --tier "${opts.tier}" (allowed: ${VALID_TIERS.join(', ')})`, { json: opts.json });
+            return;
         }
-        else {
-            raw = opts.params;
+        if (opts.forceTier !== undefined && !VALID_TIERS.includes(opts.forceTier)) {
+            usageError(`Invalid --force-tier "${opts.forceTier}" (allowed: ${VALID_TIERS.join(', ')})`, { json: opts.json });
+            return;
         }
-        let parsed;
-        try {
-            parsed = JSON.parse(raw);
+        const body = {};
+        if (opts.title !== undefined)
+            body.title = opts.title;
+        if (opts.url !== undefined)
+            body.url = opts.url;
+        if (opts.request !== undefined)
+            body.request = opts.request;
+        if (opts.description !== undefined)
+            body.description = opts.description;
+        if (opts.cron === false)
+            body.cron = null;
+        else if (typeof opts.cron === 'string')
+            body.cron = opts.cron === '' ? null : opts.cron;
+        if (opts.alert === false)
+            body.alert = null;
+        else if (typeof opts.alert === 'string')
+            body.alert = opts.alert === '' ? null : opts.alert;
+        if (opts.autofix === true)
+            body.autoFix = true;
+        else if (opts.autofix === false)
+            body.autoFix = false;
+        if (opts.params !== undefined || opts.paramsFile !== undefined) {
+            let raw;
+            if (opts.paramsFile) {
+                const { readFileSync } = await import('fs');
+                raw = readFileSync(opts.paramsFile, 'utf8');
+            }
+            else {
+                raw = opts.params;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch (e) {
+                usageError(`Invalid JSON for --params: ${e.message}`, { json: opts.json });
+                return;
+            }
+            if (!Array.isArray(parsed)) {
+                usageError('--params must be a JSON array of objects', { json: opts.json });
+                return;
+            }
+            body.params = parsed;
         }
-        catch (e) {
-            usageError(`Invalid JSON for --params: ${e.message}`, { json: opts.json });
-            return;
+        if (opts.tier !== undefined)
+            body.proxyTier = opts.tier;
+        if (opts.forceTier !== undefined) {
+            // Raise the ceiling; also start the run at that tier unless --tier says otherwise.
+            body.proxyMaxTier = opts.forceTier;
+            if (opts.tier === undefined)
+                body.proxyTier = opts.forceTier;
         }
-        if (!Array.isArray(parsed)) {
-            usageError('--params must be a JSON array of objects', { json: opts.json });
+        if (Object.keys(body).length === 0) {
+            if (opts.json) {
+                process.exitCode = reportError(new UsageError('Nothing to update. Provide at least one option.'), { json: true });
+                return;
+            }
+            console.log(chalk.yellow('Nothing to update. Provide at least one option.'));
             return;
         }
-        body.params = parsed;
-    }
-    if (opts.tier !== undefined)
-        body.proxyTier = opts.tier;
-    if (opts.forceTier !== undefined) {
-        // Raise the ceiling; also start the run at that tier unless --tier says otherwise.
-        body.proxyMaxTier = opts.forceTier;
-        if (opts.tier === undefined)
-            body.proxyTier = opts.forceTier;
-    }
-    if (Object.keys(body).length === 0) {
+        const data = await spin(() => api.put(`/api/scraps/${id}`, body), {
+            text: 'Updating scrap…',
+            successText: (d) => `Scrap updated: ${chalk.bold(d._id)}`,
+        });
+        // #1559 / #86 findings 4b/5 — surface the effective tier + clamp/refuse
+        // reason (fixes the silent-clamp: the server may persist a lower tier
+        // than requested), and NEVER echo the requested value as applied when
+        // the server doesn't confirm it (old-server fallback below).
+        const tierWasRequested = opts.tier !== undefined || opts.forceTier !== undefined;
+        warnIfUnconfirmedTier(data, tierWasRequested, id);
+        const refused = Boolean(data._tierOverride?.refused);
         if (opts.json) {
-            process.exitCode = reportError(new UsageError('Nothing to update. Provide at least one option.'), { json: true });
+            if (refused) {
+                process.exitCode = reportTierRefusal(data, true);
+                return;
+            }
+            json(withTierUnconfirmed(data, tierWasRequested));
             return;
         }
-        console.log(chalk.yellow('Nothing to update. Provide at least one option.'));
-        return;
-    }
-    const data = await spin(() => api.put(`/api/scraps/${id}`, body), {
-        text: 'Updating scrap…',
-        successText: (d) => `Scrap updated: ${chalk.bold(d._id)}`,
-    });
-    // #1559 / #86 findings 4b/5 — surface the effective tier + clamp/refuse
-    // reason (fixes the silent-clamp: the server may persist a lower tier
-    // than requested), and NEVER echo the requested value as applied when
-    // the server doesn't confirm it (old-server fallback below).
-    const tierWasRequested = opts.tier !== undefined || opts.forceTier !== undefined;
-    warnIfUnconfirmedTier(data, tierWasRequested, id);
-    const refused = Boolean(data._tierOverride?.refused);
-    if (opts.json) {
-        if (refused) {
-            process.exitCode = reportTierRefusal(data, true);
-            return;
+        const shown = data;
+        for (const key of Object.keys(body)) {
+            // Tier keys are rendered exclusively by renderTierOverrideHuman /
+            // warnIfUnconfirmedTier above — never echo them here, whether or not
+            // _tierOverride came back (an old-server echo of the REQUESTED value
+            // is exactly the silent-clamp lie #1559 fixed).
+            if (key === 'proxyTier' || key === 'proxyMaxTier')
+                continue;
+            const src = key in shown ? shown[key] : body[key];
+            console.log(chalk.dim(`  ${key}: `) + String(src ?? '—'));
         }
-        json(withTierUnconfirmed(data, tierWasRequested));
-        return;
-    }
-    const shown = data;
-    for (const key of Object.keys(body)) {
-        // Tier keys are rendered exclusively by renderTierOverrideHuman /
-        // warnIfUnconfirmedTier above — never echo them here, whether or not
-        // _tierOverride came back (an old-server echo of the REQUESTED value
-        // is exactly the silent-clamp lie #1559 fixed).
-        if (key === 'proxyTier' || key === 'proxyMaxTier')
-            continue;
-        const src = key in shown ? shown[key] : body[key];
-        console.log(chalk.dim(`  ${key}: `) + String(src ?? '—'));
-    }
-    renderTierOverrideHuman(data);
-    if (refused)
-        process.exitCode = 1;
-});
+        renderTierOverrideHuman(data);
+        if (refused)
+            process.exitCode = 1;
+    });
+}
+attachUpdateCommand(scraps, { hidden: true });
 // run — promoted to a top-level verb (#108)
 export function attachRunCommand(parent, attachOpts = {}) {
     return parent

package/dist/index.js

@@ -4,7 +4,7 @@ import { readFileSync, realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 import { login, logout } from './commands/login.js';
-import { scraps, attachListCommand, attachGetCommand, attachRunCommand, attachDataCommand, attachHistoryCommand, attachRunInfoCommand, attachTriggerCommand, } from './commands/scraps.js';
+import { scraps, attachListCommand, attachGetCommand, attachRunCommand, attachDataCommand, attachHistoryCommand, attachRunInfoCommand, attachTriggerCommand, attachUpdateCommand, } from './commands/scraps.js';
 import { skills } from './commands/skills.js';
 import { telemetry } from './commands/telemetry.js';
 import { token } from './commands/token.js';
@@ -108,11 +108,14 @@ export function createProgram() {
     attachHistoryCommand(program);
     attachRunInfoCommand(program);
     attachTriggerCommand(program);
+    attachUpdateCommand(program);
     program.addCommand(whoami);
     program.addCommand(ping);
     // Management (#108) — human/CI surface, grouped below. `scraps` still
-    // holds every pre-#108 management command (create/update/delete/banner/
-    // watch/account.*/session.*/doctor/autofix/snapshot) exactly as before.
+    // holds every pre-#108 management command (create/delete/banner/
+    // watch/account.*/session.*/doctor/autofix/snapshot) exactly as before —
+    // `update` is now a promoted core verb (#120), still reachable (hidden)
+    // under `scraps` for backward compatibility.
     program.commandsGroup(MANAGEMENT_GROUP);
     program.addCommand(scraps);
     program.addCommand(skills);

package/docs/agent-quickstart.md

@@ -20,7 +20,7 @@ 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):
 
@@ -34,6 +34,8 @@ trawl data <id> [--json] [--fresh] [--errors]  Get scrap data (last persisted ru
 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 update <id> [-t <title>] [-u <url>] [-r <request>] [-d <description>] [--cron <expr>|--no-cron] [--alert <email>|--no-alert] [--autofix|--no-autofix] [-p <json>|--params-file <path>] [--tier <t>] [--force-tier <t>] [--json]
+                                                Update an existing scrap
 trawl whoami [--json]                          Show the authenticated user's identity
 trawl ping [--json]                            Health/version handshake against the Trawl API
 ```
@@ -59,7 +61,7 @@ default.
 > scheduled to re-run every day at 07:00 UTC by default
 > (`cron: "0 7 * * *"`, unrelated to `--no-autofix`) — each recurring run
 > consumes execute quota. Disable or change it once you've reviewed the
-> scrap: `trawl scraps update <id> --no-cron` (or `--cron <expr>`). Finally,
+> scrap: `trawl update <id> --no-cron` (or `--cron <expr>`). Finally,
 > if `TRAWL_TIMEOUT` is set globally for a tighter budget than 300s, it
 > clamps `create`'s ceiling too (env always wins) — unset it or raise it
 > before calling `create`.
@@ -69,9 +71,10 @@ default.
 > a hidden alias. Prefer the bare top-level form above; it's what
 > `trawl --help` now shows.
 
-For the full flag reference (tier overrides on `scraps create`/`scraps
-update` — the core `create` verb above has no `--tier` of its own, the
-`--watch` polling mechanics, retention/regression semantics on `data`, …)
+For the full flag reference (tier overrides on `scraps create` (management)
+and the core `update` verb above — note the core `create` verb has no
+`--tier` of its own, unlike `scraps create`, the `--watch` polling mechanics,
+retention/regression semantics on `data`, …)
 see the README's [Core commands](../README.md#core-commands-agent--human) section
 — this doc intentionally stays minimal.
 

package/package.json

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