@trawlme/cli 2.3.0 → 3.0.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/create.js

@@ -5,6 +5,7 @@ import { api, LONG_RUN_TIMEOUT_MS, NetworkError } from '../lib/api.js';
 import { json } from '../lib/format.js';
 import { requireUrl, requireString } from '../lib/validate.js';
 import { UsageError } from '../lib/errors.js';
+import { renderPinch, pinchEnabled } from '../lib/pinch.js';
 /** Best-effort, honest first-run summary — never claims a background retry
  * happened when auto-fix was disabled for this call, and never claims a
  * scrap was persisted when the response carries none (#114-F3 — a hard
@@ -129,6 +130,14 @@ export const create = new Command('create')
         data = await call();
     }
     else {
+        // #122 — Pinch shows up front, working, while the server-side wizard
+        // runs (legitimately 30-250s+, see LONG_RUN_TIMEOUT_MS above). Belt-
+        // and-suspenders `!opts.json` alongside pinchEnabled(): we're already
+        // inside the non-`--json` branch, but the check is kept explicit here
+        // too so stdout purity under `--json` (#106-F2/#121) never depends on
+        // this code staying inside that branch.
+        if (!opts.json && pinchEnabled())
+            console.log(renderPinch('thinking'));
         try {
             data = await spin(call, {
                 text: `Creating a scrap from ${url}…`,
@@ -192,6 +201,13 @@ export const create = new Command('create')
             console.log(chalk.yellow(`  Note:       `) +
                 `Auto-fix is retrying in the background — do NOT re-run create; poll ${pollTarget}.`);
         }
+        // #122 — Pinch reacts to the HONEST first-run outcome (same signal the
+        // ✓/✗ line above already renders): celebrates a real success, looks
+        // confused on a genuine failure. Belt-and-suspenders `!opts.json`
+        // alongside pinchEnabled() — see the 'thinking' print above for why.
+        if (!opts.json && pinchEnabled()) {
+            console.log(data.success ? renderPinch('celebrating') : renderPinch('confused'));
+        }
     }
     // Honest exit code alongside the honest payload — a --json caller gets
     // the raw body regardless (never wrapped/altered), but a script checking

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,84 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+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';
+import { json } from '../lib/format.js';
+const execFileP = promisify(execFile);
+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.) */
+function currentVersion() {
+    const here = dirname(fileURLToPath(import.meta.url)); // dist/commands
+    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. */
+async function latestVersion() {
+    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})`);
+    }
+}
+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 latestVersion();
+    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';
@@ -108,14 +109,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 +121,7 @@ export function createProgram() {
     program.addCommand(logout);
     program.addCommand(token);
     program.addCommand(telemetry);
+    program.addCommand(upgrade);
     return program;
 }
 /**

package/dist/lib/pinch.d.ts

@@ -3,15 +3,21 @@
  * art. Distinct from Clawd's 8-bit lane: Pinch is drawn with full 24-bit
  * (`\x1b[38;2;r;g;bm` / `\x1b[48;2;r;g;bm`) color blocks, not a fixed palette.
  *
- * The 12×9 cube-grid (AVGRID proto v11.4, locked 2026-07-16) is packed two
- * grid rows into one terminal row: the upper row's color becomes the
- * half-block's foreground, the lower row's becomes its background, using the
- * upper-half-block glyph '▀' (or '▄' when only the lower half is filled). A
- * 9-row grid therefore renders in 5 terminal rows, 12 columns wide. '.' cells
- * are transparent — no color escape is emitted for that half, so the
- * terminal's own background shows through.
+ * The 14×9 cube-grid is packed two grid rows into one terminal row: the
+ * upper row's color becomes the half-block's foreground, the lower row's
+ * becomes its background, using the upper-half-block glyph '▀' (or '▄' when
+ * only the lower half is filled). A 9-row grid therefore renders in 5
+ * terminal rows, 14 columns wide. '.' cells are transparent — no color
+ * escape is emitted for that half, so the terminal's own background shows
+ * through.
  *
- * See comes-io/trawl_cli#94.
+ * Grids + palette are mirrored from trawl_vue
+ * `src/modules/trawl/assets/mascot/_src/pinch.model.mjs` (AVCOLORS +
+ * AVATAR_GRIDS, rev r6f) — no cross-repo import (cli is a standalone npm
+ * package). Claws are 2×2 'O' blocks at cols 0-1 / 12-13, fully outside the
+ * body silhouette (on the sides), per r6f.
+ *
+ * See comes-io/trawl_cli#94, comes-io/trawl_cli#122.
  */
 export type PinchState = 'wave' | 'thinking' | 'celebrating' | 'confused';
 /**
@@ -19,8 +25,8 @@ export type PinchState = 'wave' | 'thinking' | 'celebrating' | 'confused';
  * one-line caption. Pure — never touches process.env/stdout; callers must
  * gate on `pinchEnabled()` before printing the result.
  *
- * `frame` only affects 'thinking' (2-frame spinner alternation); every other
- * state ignores it.
+ * `frame` is accepted for signature stability but currently unused — every
+ * state's grid is static (see `gridForState`).
  */
 export declare function renderPinch(state: PinchState, frame?: number): string;
 /**

package/dist/lib/pinch.js

@@ -3,76 +3,98 @@
  * art. Distinct from Clawd's 8-bit lane: Pinch is drawn with full 24-bit
  * (`\x1b[38;2;r;g;bm` / `\x1b[48;2;r;g;bm`) color blocks, not a fixed palette.
  *
- * The 12×9 cube-grid (AVGRID proto v11.4, locked 2026-07-16) is packed two
- * grid rows into one terminal row: the upper row's color becomes the
- * half-block's foreground, the lower row's becomes its background, using the
- * upper-half-block glyph '▀' (or '▄' when only the lower half is filled). A
- * 9-row grid therefore renders in 5 terminal rows, 12 columns wide. '.' cells
- * are transparent — no color escape is emitted for that half, so the
- * terminal's own background shows through.
+ * The 14×9 cube-grid is packed two grid rows into one terminal row: the
+ * upper row's color becomes the half-block's foreground, the lower row's
+ * becomes its background, using the upper-half-block glyph '▀' (or '▄' when
+ * only the lower half is filled). A 9-row grid therefore renders in 5
+ * terminal rows, 14 columns wide. '.' cells are transparent — no color
+ * escape is emitted for that half, so the terminal's own background shows
+ * through.
  *
- * See comes-io/trawl_cli#94.
+ * Grids + palette are mirrored from trawl_vue
+ * `src/modules/trawl/assets/mascot/_src/pinch.model.mjs` (AVCOLORS +
+ * AVATAR_GRIDS, rev r6f) — no cross-repo import (cli is a standalone npm
+ * package). Claws are 2×2 'O' blocks at cols 0-1 / 12-13, fully outside the
+ * body silhouette (on the sides), per r6f.
+ *
+ * See comes-io/trawl_cli#94, comes-io/trawl_cli#122.
  */
-/** Grid-char → RGB. 'C' (cyan) is a "thinking" blip, not present in BASE_GRID. */
+/** Grid-char → RGB, ported from AVCOLORS (pinch.model.mjs, rev r6f). */
 const PALETTE = {
-    B: [0x3b, 0x82, 0xf6], // blue — shell
-    O: [0xee, 0x90, 0x18], // orange — antennae / claws
+    B: [0x29, 0x79, 0xff], // blue — shell
+    O: [0xfb, 0x92, 0x3c], // orange — antennae / claws
     W: [0xff, 0xff, 0xff], // white — eye whites
-    K: [0x12, 0x30, 0x33], // navy — pupils / mouth
-    P: [0xf9, 0xa8, 0xd4], // pink — claw tips
-    C: [0x08, 0x91, 0xb2], // cyan — thinking-spinner antenna blip
+    K: [0x12, 0x30, 0x33], // navy — pupils / mouth / blush-adjacent mouth corner
+    P: [0xf4, 0x72, 0xb6], // pink — blush
 };
 const TRANSPARENT = '.';
-/** Base 12×9 grid — Pinch waving (also the 'wave' state, unmodified). */
-const BASE_GRID = [
-    '...O....O...',
-    '...O....O...',
-    '.BBBBBBBBBB.',
-    '.BWWBBBBWWB.',
-    '.BWKBBBBKWB.',
-    '.PBBBBBBBBP.',
-    '.BBBKBBKBBB.',
-    '.BBBBKKBBBB.',
-    'OO........OO',
-];
+/**
+ * Explicit per-state 14×9 grids, ported verbatim from trawl_vue's
+ * AVATAR_GRIDS (pinch.model.mjs, rev r6f) — no derivation/mutation from a
+ * shared base, so each state stays a straight, auditable copy of its source
+ * grid. CLI state → source grid: wave→wave, thinking→working (a.k.a.
+ * AVGRID/idle), celebrating→celebrating, confused→confused.
+ */
+const GRIDS = {
+    wave: [
+        '....O....O....',
+        '....O....O....',
+        '..BBBBBBBBBB..',
+        '..BWWBBBBWWBOO',
+        '..BWKBBBBKWBOO',
+        '..BBBBBBBBBB..',
+        'OOBBPKBBKPBB..',
+        'OOBBBBKKBBBB..',
+        '..............',
+    ],
+    // 'thinking' maps to the source's 'working' grid (identical to 'idle').
+    // The frame param is accepted for signature compatibility but ignored — a
+    // static working frame rather than an animated blip (#122, simplified;
+    // the source has no per-frame "thinking" animation to port).
+    thinking: [
+        '....O....O....',
+        '....O....O....',
+        '..BBBBBBBBBB..',
+        '..BWWBBBBWWB..',
+        '..BWKBBBBKWB..',
+        '..BBBBBBBBBB..',
+        'OOBBPKBBKPBBOO',
+        'OOBBBBKKBBBBOO',
+        '..............',
+    ],
+    celebrating: [
+        '....O....O....',
+        '....O....O....',
+        '..BBBBBBBBBB..',
+        'OOBWWBBBBWWBOO',
+        'OOBWKBBBBKWBOO',
+        '..BBBBBBBBBB..',
+        '..BBPKKKKPBB..',
+        '..BBBKKKKBBB..',
+        '..............',
+    ],
+    confused: [
+        '..............',
+        '...O......O...',
+        '..BBBBBBBBBB..',
+        '..BWWBBBBWWB..',
+        '..BWKBBBBKWB..',
+        '..BBBBBBBBBB..',
+        'OOBBPBBBBPBBOO',
+        'OOBBBBKKBBBBOO',
+        '..............',
+    ],
+};
 const CAPTIONS = {
     wave: 'Pinch says hi.',
     thinking: 'Pinch is thinking…',
     celebrating: 'Pinch is celebrating!',
     confused: 'Pinch looks confused.',
 };
-/** Replace the chars at `indices` in `row` with `ch` — never mutates `row`. */
-function setCells(row, indices, ch) {
-    const chars = row.split('');
-    for (const i of indices)
-        chars[i] = ch;
-    return chars.join('');
-}
-/** Derive the per-state grid from BASE_GRID (which is never mutated). */
-function gridForState(state, frame) {
-    const rows = [...BASE_GRID];
-    switch (state) {
-        case 'thinking':
-            // Odd frames: both antenna tips (row 0, cols 3 & 8) blip cyan — a
-            // 2-frame spinner alternation with no layout shift.
-            if (frame % 2 === 1) {
-                rows[0] = setCells(rows[0], [3, 8], 'C');
-            }
-            return rows;
-        case 'celebrating':
-            // Fists up: the row-8 corner claws move up to row 7's corners; row 8's
-            // corners go transparent (arms raised, no longer at the sides).
-            rows[7] = setCells(rows[7], [0, 11], 'O');
-            rows[8] = setCells(rows[8], [0, 1, 10, 11], TRANSPARENT);
-            return rows;
-        case 'confused':
-            // Pupils removed (row 4, cols 3 & 8) — blank white eyes.
-            rows[4] = setCells(rows[4], [3, 8], 'W');
-            return rows;
-        case 'wave':
-        default:
-            return rows;
-    }
+/** Look up the grid for `state`. `frame` is accepted (signature stability
+ * for `renderPinch`) but unused — every current state's grid is static. */
+function gridForState(state, _frame) {
+    return GRIDS[state];
 }
 const RESET = '\x1b[0m';
 const fgCode = ([r, g, b]) => `\x1b[38;2;${r};${g};${b}m`;
@@ -117,15 +139,17 @@ function renderGrid(rows) {
  * one-line caption. Pure — never touches process.env/stdout; callers must
  * gate on `pinchEnabled()` before printing the result.
  *
- * `frame` only affects 'thinking' (2-frame spinner alternation); every other
- * state ignores it.
+ * `frame` is accepted for signature stability but currently unused — every
+ * state's grid is static (see `gridForState`).
  */
 export function renderPinch(state, frame = 0) {
     const grid = gridForState(state, frame);
     const lines = renderGrid(grid);
     if (state === 'confused') {
         // "beside the art" — a bold '?' to the right of the eye row (grid rows
-        // 4-5 pack into terminal line index 2).
+        // 4-5 pack into terminal line index 2, unchanged by the r6f grid — the
+        // antenna/shell/eye/claw row layout stayed the same, only width + claw
+        // placement changed).
         lines[2] = `${lines[2]}  \x1b[1m?${RESET}`;
     }
     return [...lines, CAPTIONS[state]].join('\n');

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.3.0",
+  "version": "3.0.0",
   "description": "Trawl CLI — manage scraps from the terminal",
   "type": "module",
   "bin": {