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

@@ -1,6 +1,6 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
-import { oraPromise } from 'ora';
+import { spin } from '../lib/spinner.js';
 import { api, LONG_RUN_TIMEOUT_MS, NetworkError } from '../lib/api.js';
 import { json } from '../lib/format.js';
 import { requireUrl, requireString } from '../lib/validate.js';
@@ -53,8 +53,8 @@ function scheduleLabel(scrap) {
 export const create = new Command('create')
     .description('Create a persistent, self-healing scrap from a URL + a goal (AI-generated)')
     .argument('[url]', 'Target public URL (http/https)')
-    .requiredOption('--prompt <goal>', 'What to extract/scrape, in plain language')
-    .option('--url <url>', 'Target public URL — alias of the positional argument (#116)')
+    .requiredOption('--prompt <goal>', 'What to extract/scrape, in plain language (required)')
+    .option('--url <url>', 'Target public URL — alias of the positional argument')
     .option('--no-autofix', 'Disable AI auto-fix on first-run failure (default: on)')
     .option('--json', 'Output the raw API payload')
     .action(async (rawUrl, opts) => {
@@ -95,7 +95,7 @@ export const create = new Command('create')
     }
     else {
         try {
-            data = await oraPromise(call, {
+            data = await spin(call, {
                 text: `Creating a scrap from ${url}…`,
                 // No verdict symbol here (#106-F3) — ora's success only means "the
                 // HTTP call didn't throw", not "the first run succeeded". The real

package/dist/commands/doctor.js

@@ -1,5 +1,6 @@
 import { api } from '../lib/api.js';
 import chalk from 'chalk';
+import { formatDate } from '../lib/format.js';
 /**
  * Known anti-bot vendors (+ auth) that the worker's `blockType` field may name.
  * Ordered by first-match; `blockType` is a freeform worker string, not an enum
@@ -142,7 +143,7 @@ export function formatDoctor(scrapTitle, run, fix = null, scrapId) {
     }
     // Timestamp
     if (run.createdAt) {
-        lines.push(chalk.dim('  Run at:  ') + new Date(run.createdAt).toLocaleString());
+        lines.push(chalk.dim('  Run at:  ') + formatDate(run.createdAt));
     }
     // Snapshot hint
     if (run.errorSnapshot?.html || run.statusDetail === 'empty' || run.statusDetail === 'error') {

package/dist/commands/ping.js

@@ -17,7 +17,9 @@ export const ping = new Command('ping')
         json(data);
         return;
     }
-    const versionSuffix = data.version ? ` (v${data.version})` : '';
+    // #119 — label it as the API's version, not a bare `v0.4.0` that reads as
+    // "the platform is v0.4" (it's the server package version field).
+    const versionSuffix = data.version ? ` (api v${data.version})` : '';
     if (data.status === 'ok') {
         console.log(chalk.green('✓ OK') + versionSuffix);
     }

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

@@ -1,8 +1,8 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
-import { oraPromise } from 'ora';
+import { spin } from '../lib/spinner.js';
 import { api, LONG_RUN_TIMEOUT_MS } from '../lib/api.js';
-import { table, json } from '../lib/format.js';
+import { table, json, formatDate } from '../lib/format.js';
 import { promptPassword } from '../lib/prompt.js';
 import { validateObjectId } from '../lib/validate.js';
 import { classifyError, reportError, UsageError, RefusalError } from '../lib/errors.js';
@@ -42,16 +42,7 @@ function lastStatus(scrap) {
     return last.status === true ? 'success' : 'failure';
 }
 function lastRun(scrap) {
-    const last = scrap.history?.[0];
-    if (!last?.createdAt)
-        return '—';
-    const d = new Date(last.createdAt);
-    const dd = String(d.getDate()).padStart(2, '0');
-    const mm = String(d.getMonth() + 1).padStart(2, '0');
-    const yy = String(d.getFullYear()).slice(2);
-    const hh = String(d.getHours()).padStart(2, '0');
-    const min = String(d.getMinutes()).padStart(2, '0');
-    return `${dd}/${mm}/${yy} ${hh}:${min}`;
+    return formatDate(scrap.history?.[0]?.createdAt); // #119 — unified DD/MM/YY HH:mm
 }
 function statusIcon(status) {
     if (status === 'success')
@@ -389,7 +380,7 @@ export function attachListCommand(parent, attachOpts = {}) {
         }
         let data;
         try {
-            data = await oraPromise(async () => {
+            data = await spin(async () => {
                 if (page !== undefined) {
                     // Single-page mode: explicit page requested, no loop
                     return api.get(`/api/scraps?perPage=50&page=${page}`);
@@ -445,7 +436,7 @@ export function attachListCommand(parent, attachOpts = {}) {
             cron: s.cron || '—',
             status: statusIcon(lastStatus(s)),
             'last run': lastRun(s),
-            updated: new Date(s.updatedAt).toLocaleDateString(),
+            updated: formatDate(s.updatedAt),
         }));
         table(tableRows, ['id', 'title', 'cron', 'status', 'last run', 'updated']);
         // Print footer when --limit truncates
@@ -471,7 +462,7 @@ export function attachGetCommand(parent, attachOpts = {}) {
         console.log(chalk.dim(`  Cron:     `) + (data.cron || '—'));
         console.log(chalk.dim(`  Status:   `) + statusIcon(lastStatus(data)));
         console.log(chalk.dim(`  Last run: `) + lastRun(data));
-        console.log(chalk.dim(`  Updated:  `) + new Date(data.updatedAt).toLocaleString());
+        console.log(chalk.dim(`  Updated:  `) + formatDate(data.updatedAt));
     });
 }
 attachGetCommand(scraps, { hidden: true });
@@ -566,7 +557,7 @@ scraps
         usageError(`Invalid --tier "${opts.tier}" (allowed: ${VALID_TIERS.join(', ')})`, { json: opts.json });
         return;
     }
-    const data = await oraPromise(() => api.post('/api/scraps', {
+    const data = await spin(() => api.post('/api/scraps', {
         title: opts.title,
         ...(opts.url && { url: opts.url }),
         request: opts.request || '',
@@ -592,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 oraPromise(() => 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
@@ -735,7 +729,7 @@ export function attachRunCommand(parent, attachOpts = {}) {
         // all, mirroring `trawl create`'s own --json handling.
         const data = opts.json
             ? await call()
-            : await oraPromise(call, { text: 'Launching scrap…', successText: 'Scrap launched' });
+            : await spin(call, { text: 'Launching scrap…', successText: 'Scrap launched' });
         if (opts.json)
             json(data);
         if (opts.watch) {
@@ -830,7 +824,7 @@ export function attachDataCommand(parent, attachOpts = {}) {
         if (opts.fresh) {
             // #91 P0 — same long-run endpoint as `run` (30-250s server-side);
             // the 30s default was aborting it mid-flight.
-            const loaded = await oraPromise(() => api.get(`/api/scraps/load/${id}`, { timeoutMs: LONG_RUN_TIMEOUT_MS }), {
+            const loaded = await spin(() => api.get(`/api/scraps/load/${id}`, { timeoutMs: LONG_RUN_TIMEOUT_MS }), {
                 text: 'Launching a fresh scrap run (consumes execute quota)…',
                 successText: 'Fresh run complete',
             });
@@ -1050,7 +1044,7 @@ scraps
         json({ deleted: true, id });
         return;
     }
-    await oraPromise(call, { text: 'Deleting…', successText: 'Scrap deleted' });
+    await spin(call, { text: 'Deleting…', successText: 'Scrap deleted' });
 });
 // banner
 scraps
@@ -1092,7 +1086,7 @@ scraps
         json(data);
         return;
     }
-    await oraPromise(call, {
+    await spin(call, {
         text: 'Uploading banner…',
         successText: `Banner uploaded for scrap ${chalk.bold(id)}`,
     });
@@ -1135,7 +1129,7 @@ export function attachTriggerCommand(parent, attachOpts = {}) {
         // #107 — under --json the stdout path stays pure: no spinner channel.
         const data = opts.json
             ? await call()
-            : await oraPromise(call, {
+            : await spin(call, {
                 text: opts.wait ? 'Running worker…' : 'Triggering worker…',
                 successText: opts.wait ? 'Worker run complete' : 'Worker triggered',
             });
@@ -1214,7 +1208,7 @@ account
         json(data);
         return;
     }
-    const data = await oraPromise(call, { text: 'Saving credentials…', successText: 'Credentials saved' });
+    const data = await spin(call, { text: 'Saving credentials…', successText: 'Credentials saved' });
     const acc = data.account;
     console.log(chalk.dim('  Credentials: ') + (acc.hasCredentials ? chalk.green('✓ configured') : chalk.dim('not set')));
     console.log(chalk.dim('  Session:     ') + (acc.hasSession ? chalk.green('active') : chalk.dim('none')));
@@ -1244,7 +1238,7 @@ account
         json({ deleted: true, id });
         return;
     }
-    await oraPromise(call, {
+    await spin(call, {
         text: 'Deleting credentials…',
         successText: 'Account credentials deleted',
     });
@@ -1262,7 +1256,7 @@ account
         json({ cleared: true, id });
         return;
     }
-    await oraPromise(call, {
+    await spin(call, {
         text: 'Clearing session…',
         successText: 'Session cleared',
     });
@@ -1311,7 +1305,7 @@ accountSession
         json(data);
         return;
     }
-    const data = await oraPromise(call, {
+    const data = await spin(call, {
         text: 'Uploading session cookies…',
         successText: `Session cookies saved for scrap ${chalk.bold(id)}`,
     });
@@ -1325,7 +1319,7 @@ account
     .option('--json', 'Output as JSON')
     .action(async (id, opts) => {
     validateObjectId(id);
-    const data = await oraPromise(() => api.get(`/api/scraps/${id}`), 'Fetching scrap…');
+    const data = await spin(() => api.get(`/api/scraps/${id}`), 'Fetching scrap…');
     const acc = data.account;
     if (opts.json) {
         // #86 finding 12 — `json` is already statically imported at the top of

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/dist/lib/format.d.ts

@@ -1,2 +1,9 @@
 export declare function table(rows: Record<string, unknown>[], columns: string[]): void;
 export declare function json(data: unknown): void;
+/**
+ * One date format across the whole CLI: `DD/MM/YY HH:mm` (local time).
+ * #119 — `list` mixed `DD/MM/YY` (last-run col) with `M/D/YYYY,
+ * h:mm:ss AM/PM` (toLocaleString), ambiguous day/month side by side.
+ * Returns `—` for a missing/invalid date.
+ */
+export declare function formatDate(value: string | number | Date | null | undefined): string;

package/dist/lib/format.js

@@ -23,3 +23,22 @@ export function table(rows, columns) {
 export function json(data) {
     console.log(JSON.stringify(data, null, 2));
 }
+/**
+ * One date format across the whole CLI: `DD/MM/YY HH:mm` (local time).
+ * #119 — `list` mixed `DD/MM/YY` (last-run col) with `M/D/YYYY,
+ * h:mm:ss AM/PM` (toLocaleString), ambiguous day/month side by side.
+ * Returns `—` for a missing/invalid date.
+ */
+export function formatDate(value) {
+    if (value === null || value === undefined)
+        return '—';
+    const d = new Date(value);
+    if (Number.isNaN(d.getTime()))
+        return '—';
+    const dd = String(d.getDate()).padStart(2, '0');
+    const mm = String(d.getMonth() + 1).padStart(2, '0');
+    const yy = String(d.getFullYear()).slice(2);
+    const hh = String(d.getHours()).padStart(2, '0');
+    const min = String(d.getMinutes()).padStart(2, '0');
+    return `${dd}/${mm}/${yy} ${hh}:${min}`;
+}

package/dist/lib/spinner.d.ts

@@ -0,0 +1,18 @@
+type Action<T> = PromiseLike<T> | (() => PromiseLike<T>);
+type SpinOptions<T> = string | {
+    text?: string;
+    successText?: string | ((result: T) => string);
+    failText?: string | ((error: Error) => string);
+    [key: string]: unknown;
+};
+/**
+ * Drop-in for `oraPromise` that emits NOTHING when stderr is not a TTY.
+ *
+ * #119 — under a pipe / non-TTY, `oraPromise` still printed the start text AND
+ * a persisted `✔ …` line, so `trawl list | cat` showed the spinner caption
+ * twice. An agent/CI never wants spinner chrome; here we just run the action.
+ * When stderr IS a TTY, behaviour is identical to `oraPromise` (spinner writes
+ * to stderr, stdout stays clean either way).
+ */
+export declare function spin<T>(action: Action<T>, options?: SpinOptions<T>): Promise<T>;
+export {};

package/dist/lib/spinner.js

@@ -0,0 +1,17 @@
+import { oraPromise } from 'ora';
+/**
+ * Drop-in for `oraPromise` that emits NOTHING when stderr is not a TTY.
+ *
+ * #119 — under a pipe / non-TTY, `oraPromise` still printed the start text AND
+ * a persisted `✔ …` line, so `trawl list | cat` showed the spinner caption
+ * twice. An agent/CI never wants spinner chrome; here we just run the action.
+ * When stderr IS a TTY, behaviour is identical to `oraPromise` (spinner writes
+ * to stderr, stdout stays clean either way).
+ */
+export function spin(action, options) {
+    if (!process.stderr.isTTY) {
+        return Promise.resolve(typeof action === 'function' ? action() : action);
+    }
+    // oraPromise's own overloads accept (action, string) and (action, options).
+    return oraPromise(action, options);
+}

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