@trawlme/cli 2.4.0 → 3.1.0

package/README.md

@@ -18,6 +18,15 @@ Requires Node.js >= 20.
 npm install -g @trawlme/cli
 ```
 
+Already installed? Update the CLI itself with:
+
+```bash
+trawl upgrade          # install the latest version (old → new)
+trawl upgrade --check  # only report if an update is available (exit 1 if so)
+```
+
+(`trawl upgrade` updates the CLI on your machine — distinct from `trawl scraps update <id>`, which updates a *scrap*.)
+
 ## Authentication
 
 Three methods:
@@ -46,8 +55,6 @@ 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
 ```
@@ -56,7 +63,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`). On a successful first run (human mode) it prints a small **data sample** (item count + first-item fields + one truncated value) as proof of value — best-effort, silent if the sample can't be fetched — and points `Next step` at `trawl data <id>` (the data), with `trawl get <id>` as the secondary detail view. `--json` skips the sample fetch and prints the raw wizard payload verbatim. `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 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 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`.
 
 - `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.
@@ -70,6 +77,7 @@ 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]
@@ -134,6 +142,14 @@ trawl telemetry off [--json]      Disable usage telemetry
 trawl telemetry status [--json]   Show current state, telemetry ID, and opt-out instructions
 ```
 
+### Upgrade the CLI
+
+```
+trawl upgrade [--check] [--json]  Update @trawlme/cli to the latest published version
+```
+
+Compares the running version against the npm registry and runs `npm install -g @trawlme/cli@latest` when a newer one exists. `--check` reports without installing (exit `1` when an update is available). A permission error on a system-owned global prefix is surfaced with the manual command.
+
 ## Telemetry
 
 `@trawlme/cli` collects anonymous usage data to help us improve the CLI based on real usage patterns. Telemetry is enabled by default.

package/dist/commands/create.d.ts

@@ -30,8 +30,7 @@ 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 update <id> --cron <expr>` / `--no-cron` (#120
-         * — `update` is now a promoted top-level verb, same as `get`/`run`/…).
+         * disable it with `trawl scraps update <id> --cron <expr>` / `--no-cron`.
          */
         cron?: string | null;
         cronTimezone?: string;

package/dist/commands/scraps.d.ts

@@ -140,7 +140,6 @@ 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,132 +583,129 @@ scraps
     if (refused)
         process.exitCode = 1;
 });
-// 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;
+// 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');
         }
-        if (opts.forceTier !== undefined && !VALID_TIERS.includes(opts.forceTier)) {
-            usageError(`Invalid --force-tier "${opts.forceTier}" (allowed: ${VALID_TIERS.join(', ')})`, { json: opts.json });
-            return;
+        else {
+            raw = opts.params;
         }
-        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;
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
         }
-        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;
+        catch (e) {
+            usageError(`Invalid JSON for --params: ${e.message}`, { json: opts.json });
+            return;
         }
-        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.'));
+        if (!Array.isArray(parsed)) {
+            usageError('--params must be a JSON array of objects', { json: opts.json });
             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);
+        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) {
         if (opts.json) {
-            if (refused) {
-                process.exitCode = reportTierRefusal(data, true);
-                return;
-            }
-            json(withTierUnconfirmed(data, tierWasRequested));
+            process.exitCode = reportError(new UsageError('Nothing to update. Provide at least one option.'), { json: 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 ?? '—'));
-        }
-        renderTierOverrideHuman(data);
-        if (refused)
-            process.exitCode = 1;
+        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)}`,
     });
-}
-attachUpdateCommand(scraps, { hidden: true });
+    // #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;
+        }
+        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;
+});
 // run — promoted to a top-level verb (#108)
 export function attachRunCommand(parent, attachOpts = {}) {
     return parent

package/dist/commands/upgrade.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const upgrade: Command;

package/dist/commands/upgrade.js

@@ -0,0 +1,58 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { json } from '../lib/format.js';
+import { PKG_NAME, currentVersion, fetchLatestVersion } from '../lib/version.js';
+const execFileP = promisify(execFile);
+export const upgrade = new Command('upgrade')
+    .description('Update the trawl CLI itself to the latest published version')
+    .option('--check', 'Only report whether an update is available — do not install')
+    .option('--json', 'Output as JSON')
+    .action(async (opts) => {
+    const current = currentVersion();
+    const latest = await fetchLatestVersion();
+    const upToDate = current === latest;
+    if (upToDate) {
+        if (opts.json)
+            return json({ package: PKG_NAME, current, latest, upToDate: true, upgraded: false });
+        console.log(`${chalk.green('✓')} Already on the latest version (${chalk.bold(current)}).`);
+        return;
+    }
+    if (opts.check) {
+        if (opts.json)
+            return json({ package: PKG_NAME, current, latest, upToDate: false, upgraded: false });
+        console.log(`${chalk.yellow('↑')} Update available: ${chalk.bold(current)} → ${chalk.bold(latest)}. Run ${chalk.cyan('trawl upgrade')} to install.`);
+        // Honest exit code so a script can gate on "is an update available".
+        process.exitCode = 1;
+        return;
+    }
+    // Install the latest globally. This shells out to the same npm the user
+    // installed the CLI with; a permission error (EACCES on a system-owned
+    // global prefix) is surfaced with the manual command rather than swallowed.
+    if (!opts.json)
+        console.log(chalk.dim(`Upgrading ${PKG_NAME}: ${current} → ${latest}…`));
+    try {
+        await execFileP('npm', ['install', '-g', `${PKG_NAME}@latest`], { timeout: 180_000 });
+    }
+    catch (err) {
+        const e = err;
+        const hint = e.code === 'ENOENT'
+            ? 'npm was not found on PATH.'
+            : /EACCES|permission/i.test(String(e.stderr ?? e.message))
+                ? 'permission denied on the global npm prefix — retry with sudo, or use a Node version manager.'
+                : (e.stderr?.trim() || e.message);
+        if (opts.json) {
+            console.log(JSON.stringify({ error: { message: `upgrade failed: ${hint}`, kind: 'upgrade_failed' } }));
+        }
+        else {
+            console.error(chalk.red(`✗ Upgrade failed: ${hint}`));
+            console.error(chalk.dim(`  Install manually: npm install -g ${PKG_NAME}@latest`));
+        }
+        process.exitCode = 1;
+        return;
+    }
+    if (opts.json)
+        return json({ package: PKG_NAME, current, latest, upToDate: false, upgraded: true });
+    console.log(`${chalk.green('✓')} Upgraded ${PKG_NAME}: ${chalk.bold(current)} → ${chalk.bold(latest)}.`);
+});

package/dist/index.js

@@ -4,10 +4,11 @@ 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, attachUpdateCommand, } from './commands/scraps.js';
+import { scraps, attachListCommand, attachGetCommand, attachRunCommand, attachDataCommand, attachHistoryCommand, attachRunInfoCommand, attachTriggerCommand, } from './commands/scraps.js';
 import { skills } from './commands/skills.js';
 import { telemetry } from './commands/telemetry.js';
 import { token } from './commands/token.js';
+import { upgrade } from './commands/upgrade.js';
 import { create } from './commands/create.js';
 import { whoami } from './commands/whoami.js';
 import { ping } from './commands/ping.js';
@@ -15,6 +16,7 @@ import { autoUpdateInstalledSkills } from './lib/skills.js';
 import { initPostHog, captureCommand, shutdown, registerAllowedCommands } from './lib/posthog.js';
 import { classifyError, reportError } 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));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
 /**
@@ -108,14 +110,11 @@ 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/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.
+    // holds every pre-#108 management command (create/update/delete/banner/
+    // watch/account.*/session.*/doctor/autofix/snapshot) exactly as before.
     program.commandsGroup(MANAGEMENT_GROUP);
     program.addCommand(scraps);
     program.addCommand(skills);
@@ -123,6 +122,7 @@ export function createProgram() {
     program.addCommand(logout);
     program.addCommand(token);
     program.addCommand(telemetry);
+    program.addCommand(upgrade);
     return program;
 }
 /**
@@ -369,6 +369,23 @@ export async function runCli(argv = process.argv) {
         // Flush + close telemetry before the process exits. A `process.on('exit')`
         // handler cannot reliably run async work, so this must happen here.
         await shutdown();
+        // Passive "update available" notifier (#129) — never on a help/version
+        // query, and each half individually guarded so a notifier bug can never
+        // turn a successful command into a failure or change its exit code.
+        if (!isHelpOrVersion(argv)) {
+            try {
+                maybeNotifyUpdate();
+            }
+            catch {
+                // swallow — see updateNotifier.ts, this is already self-guarded too.
+            }
+            try {
+                scheduleUpdateCheck();
+            }
+            catch {
+                // swallow — background refresh must never affect this invocation.
+            }
+        }
     }
 }
 if (isEntryPoint(process.argv[1], import.meta.url)) {

package/dist/lib/config.d.ts

@@ -4,6 +4,11 @@ interface TrawlConfig {
     token: string;
     telemetry: boolean;
     telemetryUserId: string;
+    /** Opt-out switch for the passive "update available" notifier
+     * (src/lib/updateNotifier.ts). Optional — absent/undefined means enabled;
+     * only an explicit `false` disables it. No default entry needed since it's
+     * optional. (#129) */
+    updateNotifier?: boolean;
 }
 declare const config: Conf<TrawlConfig>;
 /**

package/dist/lib/updateCheckWorker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/updateCheckWorker.js

@@ -0,0 +1,30 @@
+/**
+ * Standalone worker script spawned DETACHED by scheduleUpdateCheck()
+ * (updateNotifier.ts) to refresh the update-check cache in the background —
+ * this never runs on the CLI's hot path. Invoked as
+ * `node dist/lib/updateCheckWorker.js <cachePath>`, it queries the npm
+ * registry for the latest published version, writes
+ * `{ latest, checkedAt }` to `<cachePath>`, and exits. The NEXT `trawl`
+ * invocation picks up the refreshed cache — this run never waits on it.
+ *
+ * Any failure (npm missing, registry unreachable, cache dir unwritable) exits
+ * silently (code 0) — a failed background refresh must never surface to the
+ * user; the cache simply stays stale until the next stale-check fires.
+ */
+import { execFile } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+import { PKG_NAME } from './version.js';
+const cachePath = process.argv[2];
+if (cachePath) {
+    execFile('npm', ['view', PKG_NAME, 'version'], { timeout: 30_000 }, (err, stdout) => {
+        if (!err) {
+            try {
+                writeFileSync(cachePath, JSON.stringify({ latest: String(stdout).trim(), checkedAt: Date.now() }));
+            }
+            catch {
+                // Best-effort — a write failure just means the next invocation retries.
+            }
+        }
+        process.exit(0);
+    });
+}

package/dist/lib/updateNotifier.d.ts

@@ -0,0 +1,20 @@
+/** The cache file lives beside the CLI's own `conf` config file — same
+ * directory, no extra config-dir resolution logic to duplicate. */
+export declare function updateCachePath(): string;
+/**
+ * Synchronous, instant — safe to call on every invocation's hot path. Prints
+ * ONE line to stderr when a cached "latest" version is a valid semver
+ * strictly greater than the running version, and every gate holds:
+ * an interactive stderr TTY, no `--json` flag, not a help/version query, and
+ * not opted out (env or config). Any error (bad cache, etc.) is swallowed —
+ * this must never throw.
+ */
+export declare function maybeNotifyUpdate(argv?: string[]): void;
+/**
+ * Non-blocking background refresh. When the cache is missing or older than
+ * CHECK_INTERVAL_MS, spawns a fully detached child (updateCheckWorker.ts)
+ * that queries npm and writes the refreshed cache, then exits — this
+ * invocation never waits on it (`.unref()`), so the refreshed cache is only
+ * ever used by the NEXT invocation. Never throws.
+ */
+export declare function scheduleUpdateCheck(): void;

package/dist/lib/updateNotifier.js

@@ -0,0 +1,150 @@
+/**
+ * Passive "update available" notifier (#129) — follows the `update-notifier`
+ * model: notify from a CACHE, refresh the cache in the BACKGROUND, never
+ * block or slow down the command it hitches a ride on.
+ *
+ * - `maybeNotifyUpdate()` is synchronous and instant — it only ever reads a
+ *   cache file that already exists on disk and prints at most one line to
+ *   stderr. It never talks to the network and never throws.
+ * - `scheduleUpdateCheck()` refreshes that cache for the NEXT invocation by
+ *   spawning a fully detached, unref'd child process
+ *   (src/lib/updateCheckWorker.ts) — this invocation never awaits it.
+ *
+ * Both are called from src/index.ts's `runCli()` finally block, after
+ * `shutdown()`, wrapped so a notifier failure can never turn a successful
+ * command into a failed one.
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+import chalk from 'chalk';
+import config from './config.js';
+import { currentVersion } from './version.js';
+/** Refresh cadence for the background worker — a cache younger than this is
+ * left alone; older (or missing) triggers a detached refresh. */
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+/** Sibling compiled worker script (dist/lib/updateCheckWorker.js next to this
+ * module's own dist/lib/updateNotifier.js) — resolved relative to THIS
+ * module so it works regardless of cwd or how the CLI was installed. */
+const WORKER_PATH = fileURLToPath(new URL('./updateCheckWorker.js', import.meta.url));
+/** The cache file lives beside the CLI's own `conf` config file — same
+ * directory, no extra config-dir resolution logic to duplicate. */
+export function updateCachePath() {
+    return join(dirname(config.path), 'update-check.json');
+}
+function readCache() {
+    try {
+        const raw = readFileSync(updateCachePath(), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.latest !== 'string' || typeof parsed.checkedAt !== 'number')
+            return undefined;
+        return { latest: parsed.latest, checkedAt: parsed.checkedAt };
+    }
+    catch {
+        // Missing file, corrupt JSON, unreadable — treat all the same: no cache.
+        return undefined;
+    }
+}
+/** Opted out via env (presence-based, mirrors NO_COLOR) or an explicit
+ * `false` config value. Absent/undefined config key means enabled. */
+function isOptedOut() {
+    if (process.env['TRAWL_NO_UPDATE_NOTIFIER'] !== undefined)
+        return true;
+    return config.get('updateNotifier') === false;
+}
+const SEMVER_RE = /^\d+\.\d+\.\d+$/;
+function isValidSemver(v) {
+    return SEMVER_RE.test(v);
+}
+/** Plain MAJOR.MINOR.PATCH comparison — no prerelease/build-metadata support,
+ * consistent with this package's own version scheme (see version.ts). */
+function isGreaterSemver(a, b) {
+    if (!isValidSemver(a) || !isValidSemver(b))
+        return false;
+    const pa = a.split('.').map(Number);
+    const pb = b.split('.').map(Number);
+    for (let i = 0; i < 3; i++) {
+        if (pa[i] > pb[i])
+            return true;
+        if (pa[i] < pb[i])
+            return false;
+    }
+    return false;
+}
+/** Best-effort `--json` argv scan — same "argv scan, never trust flag
+ * values" caveat as index.ts's hasJsonFlag: positional values never equal
+ * the literal `--json` string. Kept local (not imported from index.ts) so
+ * this module has no reverse dependency on the entrypoint. */
+function hasJsonFlag(argv) {
+    return argv.includes('--json');
+}
+/** Same shape as index.ts's isHelpOrVersion (bare invocation, `help`,
+ * -h/--help/-V/--version) — kept local for the same reason as hasJsonFlag
+ * above. Belt-and-suspenders: src/index.ts already skips calling this
+ * function entirely on a help/version invocation. */
+function isHelpOrVersionInvocation(argv) {
+    if (argv.some((a) => a === '-h' || a === '--help' || a === '-V' || a === '--version'))
+        return true;
+    const args = argv.slice(2);
+    if (args.length === 0)
+        return true;
+    if (args[0] === 'help')
+        return true;
+    return false;
+}
+/**
+ * Synchronous, instant — safe to call on every invocation's hot path. Prints
+ * ONE line to stderr when a cached "latest" version is a valid semver
+ * strictly greater than the running version, and every gate holds:
+ * an interactive stderr TTY, no `--json` flag, not a help/version query, and
+ * not opted out (env or config). Any error (bad cache, etc.) is swallowed —
+ * this must never throw.
+ */
+export function maybeNotifyUpdate(argv = process.argv) {
+    try {
+        if (!process.stderr.isTTY)
+            return;
+        if (hasJsonFlag(argv))
+            return;
+        if (isHelpOrVersionInvocation(argv))
+            return;
+        if (isOptedOut())
+            return;
+        const cache = readCache();
+        if (!cache)
+            return;
+        const current = currentVersion();
+        if (!isGreaterSemver(cache.latest, current))
+            return;
+        console.error(chalk.dim(`↑ Update available: ${current} → ${cache.latest}. Run \`trawl upgrade\`.`));
+    }
+    catch {
+        // Never let the notifier turn a successful command into a failure.
+    }
+}
+/**
+ * Non-blocking background refresh. When the cache is missing or older than
+ * CHECK_INTERVAL_MS, spawns a fully detached child (updateCheckWorker.ts)
+ * that queries npm and writes the refreshed cache, then exits — this
+ * invocation never waits on it (`.unref()`), so the refreshed cache is only
+ * ever used by the NEXT invocation. Never throws.
+ */
+export function scheduleUpdateCheck() {
+    try {
+        if (isOptedOut())
+            return;
+        const cache = readCache();
+        const isStale = !cache || Date.now() - cache.checkedAt > CHECK_INTERVAL_MS;
+        if (!isStale)
+            return;
+        const child = spawn(process.execPath, [WORKER_PATH, updateCachePath()], {
+            detached: true,
+            stdio: 'ignore',
+        });
+        child.unref();
+    }
+    catch {
+        // A failed background-refresh spawn must never affect the caller.
+    }
+}

package/dist/lib/version.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared version plumbing — the package name + "what version am I" + "what's
+ * published" primitives, used by BOTH `trawl upgrade` (src/commands/upgrade.ts)
+ * and the passive update notifier (src/lib/updateNotifier.ts). Extracted so
+ * neither duplicates the npm-registry lookup or the package.json read (#129).
+ */
+export declare const PKG_NAME = "@trawlme/cli";
+/** The version currently RUNNING — read from this package's own package.json.
+ * (At publish time semantic-release stamps the real version into the tarball's
+ * package.json, so at runtime this is the installed version; the repo's
+ * checked-in value is vestigial.) */
+export declare function currentVersion(): string;
+/** Latest published version from the npm registry. Throws with a friendly
+ * message when npm is missing or the registry is unreachable. */
+export declare function fetchLatestVersion(): Promise<string>;

package/dist/lib/version.js

@@ -0,0 +1,36 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+const execFileP = promisify(execFile);
+/**
+ * Shared version plumbing — the package name + "what version am I" + "what's
+ * published" primitives, used by BOTH `trawl upgrade` (src/commands/upgrade.ts)
+ * and the passive update notifier (src/lib/updateNotifier.ts). Extracted so
+ * neither duplicates the npm-registry lookup or the package.json read (#129).
+ */
+export const PKG_NAME = '@trawlme/cli';
+/** The version currently RUNNING — read from this package's own package.json.
+ * (At publish time semantic-release stamps the real version into the tarball's
+ * package.json, so at runtime this is the installed version; the repo's
+ * checked-in value is vestigial.) */
+export function currentVersion() {
+    const here = dirname(fileURLToPath(import.meta.url)); // dist/lib
+    const pkg = JSON.parse(readFileSync(join(here, '..', '..', 'package.json'), 'utf8'));
+    return pkg.version;
+}
+/** Latest published version from the npm registry. Throws with a friendly
+ * message when npm is missing or the registry is unreachable. */
+export async function fetchLatestVersion() {
+    try {
+        const { stdout } = await execFileP('npm', ['view', PKG_NAME, 'version'], { timeout: 30_000 });
+        return stdout.trim();
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === 'ENOENT')
+            throw new Error('npm was not found on PATH — install Node.js/npm, then run: npm install -g @trawlme/cli@latest');
+        throw new Error(`could not reach the npm registry to check for updates (${e.message})`);
+    }
+}

package/docs/agent-quickstart.md

@@ -20,7 +20,7 @@ agent should never need them.)
 
 ## Core commands (agent + human)
 
-These eleven commands are the CLI's agent+human surface — `--json` is
+These ten 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,8 +34,6 @@ 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
 ```
@@ -61,7 +59,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 update <id> --no-cron` (or `--cron <expr>`). Finally,
+> scrap: `trawl scraps 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`.
@@ -71,10 +69,9 @@ 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` (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`, …)
+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`, …)
 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.4.0",
+  "version": "3.1.0",
   "description": "Trawl CLI — manage scraps from the terminal",
   "type": "module",
   "bin": {