@trawlme/cli 1.16.0 → 1.17.0

package/README.md

@@ -26,27 +26,43 @@ Custom API URL: `trawl login --url https://self-hosted.example.com`
 
 ## Commands
 
+All commands accept a global `--debug` flag to show full error stack traces on failure.
+
 ### Auth
 
 ```
 trawl login [--url <url>] [--token <jwt>] [--email <email>] [--password <pass>]
 trawl logout
+trawl token                                  Print the stored session JWT (for MCP Bearer auth)
 ```
 
 ### Scraps
 
 ```
-trawl scraps list [--json] [--status <success|failure|never>]
+trawl scraps list [--json] [--status <success|failure|never>] [--limit <n>] [--page <n>]
 trawl scraps get <id> [--json]
-trawl scraps create -t <title> [-u <url>] [-r <request>] [-s <scrapper>]
-trawl scraps update <id> [-t title] [-u <url>] [-r request] [-s scrapper] [--cron <expr>|--no-cron] [--alert <email>|--no-alert] [-p <json>|--params-file <path>]
+trawl scraps create -t <title> [-u <url>] [-r <request>] [-d <description>] [--tier <tier0|tier1|tier2|tier3|tier4>]
+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>]
 trawl scraps run <id> [--watch]
-trawl scraps trigger <id> [--watch]
+trawl scraps trigger <id> [--watch] [--wait]
 trawl scraps watch <id>
-trawl scraps data <id> [--json]
+trawl scraps data <id> [--json] [--fresh] [--errors]
+trawl scraps history <id> [--json] [-n <limit>]
+trawl scraps run-info <hid> [--json]
+trawl scraps doctor <id> [--json] [--autofix]
+trawl scraps autofix <id> [--json]
+trawl scraps snapshot <id> [--error] [-o <file>]
+trawl scraps banner <id> -f <file>
 trawl scraps rm <id> [--force]
 ```
 
+- `--tier` forces a proxy tier; `--force-tier` raises the proxy-tier ceiling past the auto-cap (history-gated: may be refused or cost more).
+- `scraps doctor` diagnoses the last run (error, failed selector, block status, page state, autofix outcome); `--autofix` includes the full autofix diff/dry-run/knowledge.
+- `scraps autofix` shows the last auto-fix attempt on its own (decision, diff, dry-run, knowledge).
+- `scraps snapshot --error` fetches the error-path snapshot instead of the normal one; `-o <file>` writes to a file instead of stdout.
+- `scraps history` lists past runs (newest first); `scraps run-info <hid>` shows details of a single run from that history.
+- `scraps data` returns the last persisted run payload (no execute quota); `--fresh` runs the scrap live instead (consumes execute quota); `--errors` shows the last run's error detail.
+
 ### Scrap accounts
 
 ```
@@ -54,8 +70,11 @@ trawl scraps account set <id> [-u <username>] [-p <password>]
 trawl scraps account delete <id> [--force]
 trawl scraps account clear-session <id>
 trawl scraps account status <id> [--json]
+trawl scraps account session set <id> -c <file>
 ```
 
+`account session set` uploads a Puppeteer cookie JSON array to bootstrap a logged-in session without storing credentials (BYO-cookies).
+
 ### Claude Code skills
 
 The CLI bundles a Claude Code skill that teaches Claude how to use `trawl`. Once installed, Claude can manage scraps for you via prompts.

package/dist/commands/doctor.d.ts

@@ -25,6 +25,7 @@ export interface Run {
         selectors?: Record<string, number>;
     } | null;
     blocked?: boolean;
+    blockType?: string | null;
     proxyTier?: string | null;
     regressionDetected?: boolean;
     baselineLength?: number | null;
@@ -33,6 +34,14 @@ export interface Run {
     time?: number | null;
     triggeredBy?: string | null;
 }
+/**
+ * Resolve a known anti-bot vendor (or auth) name from a worker `blockType`
+ * string. Returns null when the run isn't blocked, or when it's blocked by
+ * something other than a known vendor (e.g. `proxy-domain-gate`,
+ * `rate_limited_per_host`) — those stay on the genuine-error path since we
+ * can't honestly attribute them to a specific "no reliable bypass" wall.
+ */
+export declare function detectWallVendor(run: Pick<Run, 'blocked' | 'blockType'>): string | null;
 /**
  * Autofix activity metadata — from the persisted ai_fix_end activity.
  * aiUsage (cost) is stripped server-side; all diagnostics are kept.

package/dist/commands/doctor.js

@@ -1,5 +1,48 @@
 import { api } from '../lib/api.js';
 import chalk from 'chalk';
+/**
+ * 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
+ * (see the `Run.blockType` doc comment), so this is a best-effort substring
+ * match against the real field — never an invented/mocked value.
+ *
+ * `datadome`/`perimeterx`/`akamai`/`cloudflare` are literal substrings the
+ * current worker emits (detect.js). `kasada` and `auth` are forward-compatible:
+ * the issue (#62 / wall-registry WS-7) names them as genuine walls, but the
+ * current worker vocabulary does not yet emit them — these branches light up
+ * automatically if/when a future worker classifier does, without a CLI change.
+ *
+ * The `auth` pattern is delimiter-anchored (`^`/`$`/`-_:`) rather than a bare
+ * substring so it matches worker-style tokens (`auth`, `auth-wall`, `auth_wall`,
+ * `login:auth`) without false-matching `oauth`/`authorization`/`author`. It uses
+ * `[-_:]` (not `\b`) because `_` is a JS `\w` char, so `\bauth\b` would miss the
+ * underscore-delimited `auth_wall` form the worker's `rate_limited_per_host`-style
+ * naming favors.
+ */
+const WALL_VENDOR_PATTERNS = [
+    [/datadome/i, 'DataDome'],
+    [/kasada/i, 'Kasada'],
+    [/perimeterx/i, 'PerimeterX'],
+    [/akamai/i, 'Akamai'],
+    [/cloudflare/i, 'Cloudflare'],
+    [/(?:^|[-_:])auth(?:$|[-_:])/i, 'auth'],
+];
+/**
+ * Resolve a known anti-bot vendor (or auth) name from a worker `blockType`
+ * string. Returns null when the run isn't blocked, or when it's blocked by
+ * something other than a known vendor (e.g. `proxy-domain-gate`,
+ * `rate_limited_per_host`) — those stay on the genuine-error path since we
+ * can't honestly attribute them to a specific "no reliable bypass" wall.
+ */
+export function detectWallVendor(run) {
+    if (run.blocked !== true || !run.blockType)
+        return null;
+    for (const [pattern, label] of WALL_VENDOR_PATTERNS) {
+        if (pattern.test(run.blockType))
+            return label;
+    }
+    return null;
+}
 const TIER_LABELS = {
     tier0: 'Tier 0',
     tier1: 'Tier 1',
@@ -9,7 +52,7 @@ const TIER_LABELS = {
 };
 const RUN_ALLOWLIST = [
     '_id', 'status', 'statusDetail', 'length', 'errorMessage', 'errorSnapshot',
-    'emptyContext', 'blocked', 'proxyTier', 'regressionDetected', 'baselineLength',
+    'emptyContext', 'blocked', 'blockType', 'proxyTier', 'regressionDetected', 'baselineLength',
     'fixVersionId', 'createdAt', 'time', 'triggeredBy',
 ];
 const FIX_ALLOWLIST = [
@@ -49,9 +92,15 @@ export function formatDoctor(scrapTitle, run, fix = null, scrapId) {
             : chalk.red('● failed');
     lines.push(`${chalk.bold(scrapTitle)}  ${badge}${run.statusDetail ? ` (${run.statusDetail})` : ''}`);
     lines.push(chalk.dim(`  Run ID:  ${run._id}`));
-    // Error message
+    // Error message — an honest accept-wall string for known-walled scraps
+    // (DataDome/Kasada/PerimeterX/Akamai/auth terminal verdict from the worker),
+    // otherwise the real error (genuine transient failure).
+    const wallVendor = detectWallVendor(run);
     const errMsg = run.errorMessage ?? run.errorSnapshot?.errorMessage;
-    if (errMsg) {
+    if (wallVendor) {
+        lines.push(chalk.dim('  Error:   ') + chalk.red(`walled: ${wallVendor} — no reliable bypass`));
+    }
+    else if (errMsg) {
         lines.push(chalk.dim('  Error:   ') + chalk.red(errMsg));
     }
     // Failed selector

package/dist/commands/login.js

@@ -2,14 +2,23 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 import config, { getApiUrl } from '../lib/config.js';
 import { api } from '../lib/api.js';
-import { requireJwt, requireUrl } from '../lib/validate.js';
+import { requireFreshJwt, requireUrl } from '../lib/validate.js';
 import { promptPassword } from '../lib/prompt.js';
 async function promptEmail() {
     const { createInterface } = await import('readline');
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     try {
-        return await new Promise((resolve) => {
-            rl.question('Email: ', (answer) => resolve(answer.trim()));
+        return await new Promise((resolve, reject) => {
+            let answered = false;
+            rl.question('Email: ', (answer) => {
+                answered = true;
+                resolve(answer.trim());
+            });
+            rl.on('close', () => {
+                if (!answered) {
+                    reject(new Error('No input received — pass -e/-p or set TRAWL_TOKEN for non-interactive use'));
+                }
+            });
         });
     }
     finally {
@@ -23,12 +32,21 @@ export const login = new Command('login')
     .option('-e, --email <email>', 'Email address')
     .option('-p, --password <password>', 'Password (CI only — visible in process list and shell history)')
     .action(async (opts) => {
-    if (opts.url)
-        config.set('apiUrl', requireUrl(opts.url, '--url'));
+    // Validate --url but do NOT persist it yet. A failed signin must not
+    // brick the config by pointing it at an unreachable/wrong host while the
+    // OLD token stays stored (and would then be sent to that new host on the
+    // next command). Target this run via `pendingUrl` and persist only once
+    // a token has actually been obtained. (#68)
+    const pendingUrl = opts.url ? requireUrl(opts.url, '--url') : undefined;
+    const persistUrlIfPending = () => {
+        if (pendingUrl)
+            config.set('apiUrl', pendingUrl);
+    };
     // Check environment variable override first
     const envToken = process.env['TRAWL_TOKEN'];
     if (envToken) {
-        config.set('token', requireJwt(envToken, 'TRAWL_TOKEN'));
+        config.set('token', requireFreshJwt(envToken, 'TRAWL_TOKEN'));
+        persistUrlIfPending();
         console.log(chalk.green('✓ Logged in'));
         console.log(chalk.dim(`  API: ${getApiUrl()}`));
         console.log(chalk.dim(`  Config: ${config.path}`));
@@ -36,7 +54,8 @@ export const login = new Command('login')
     }
     // --token flag: direct JWT (CI / retrocompat)
     if (opts.token) {
-        config.set('token', requireJwt(opts.token, '--token'));
+        config.set('token', requireFreshJwt(opts.token, '--token'));
+        persistUrlIfPending();
         console.log(chalk.green('✓ Logged in'));
         console.log(chalk.dim(`  API: ${getApiUrl()}`));
         console.log(chalk.dim(`  Config: ${config.path}`));
@@ -48,7 +67,7 @@ export const login = new Command('login')
     }
     const email = opts.email ?? (await promptEmail());
     const password = opts.password ?? (await promptPassword('Password: '));
-    const { data, headers } = await api.publicPost('/api/auth/signin', { email, password });
+    const { data, headers } = await api.publicPost('/api/auth/signin', { email, password }, pendingUrl);
     // Try token from response body first, then fall back to Set-Cookie header
     let raw = typeof data === 'string' ? data : data.token;
     if (!raw) {
@@ -60,8 +79,9 @@ export const login = new Command('login')
     if (!raw || typeof raw !== 'string') {
         throw new Error(`Invalid response from API: no token received. Got: ${JSON.stringify(data)}`);
     }
-    const token = requireJwt(raw, 'token');
+    const token = requireFreshJwt(raw, 'token');
     config.set('token', token);
+    persistUrlIfPending();
     console.log(chalk.green(`✓ Logged in as ${email}`));
     console.log(chalk.dim(`  API: ${getApiUrl()}`));
     console.log(chalk.dim(`  Config: ${config.path}`));

package/dist/commands/scraps.js

@@ -178,6 +178,7 @@ scraps
     .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`)
     .action(async (id, opts) => {
     validateObjectId(id);
     if (opts.tier !== undefined && !VALID_TIERS.includes(opts.tier)) {
@@ -185,6 +186,11 @@ scraps
         process.exitCode = 1;
         return;
     }
+    if (opts.forceTier !== undefined && !VALID_TIERS.includes(opts.forceTier)) {
+        console.log(chalk.red(`✗ Invalid --force-tier "${opts.forceTier}" (allowed: ${VALID_TIERS.join(', ')})`));
+        process.exitCode = 1;
+        return;
+    }
     const body = {};
     if (opts.title !== undefined)
         body.title = opts.title;
@@ -233,6 +239,12 @@ scraps
     }
     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) {
         console.log(chalk.yellow('Nothing to update. Provide at least one option.'));
         return;
@@ -240,8 +252,41 @@ scraps
     const spinner = ora('Updating scrap…').start();
     const data = await api.put(`/api/scraps/${id}`, body);
     spinner.succeed(`Scrap updated: ${chalk.bold(data._id)}`);
+    // #1559 — surface the effective tier + clamp/refuse reason (fixes the
+    // silent-clamp: the server may persist a lower tier than requested).
+    const ov = data._tierOverride;
+    const shown = data;
     for (const key of Object.keys(body)) {
-        console.log(chalk.dim(`  ${key}: `) + String(data[key] ?? '—'));
+        // Only suppress the raw proxyTier/proxyMaxTier echo when _tierOverride is
+        // present to report the truth. Against an older server (no _tierOverride)
+        // fall back to echoing the requested value from the body, so the tier is
+        // never silently dropped (worse than a misleading echo).
+        if ((key === 'proxyTier' || key === 'proxyMaxTier') && ov)
+            continue;
+        const src = key in shown ? shown[key] : body[key];
+        console.log(chalk.dim(`  ${key}: `) + String(src ?? '—'));
+    }
+    if (ov) {
+        if (ov.refused) {
+            console.log(chalk.red(`  ✗ tier ceiling override refused: ${ov.reason ?? 'unknown'}`)
+                + chalk.dim(` (requested ${ov.requestedMaxTier ?? '—'}; kept the registry cap)`));
+            process.exitCode = 1;
+        }
+        else if (ov.effectiveMaxTier) {
+            console.log(chalk.green(`  ✓ tier ceiling: ${ov.effectiveMaxTier}`)
+                + chalk.dim(` (${ov.reason ?? ''}${ov.provider ? `, ${ov.provider}` : ''})`));
+            if (ov.warning)
+                console.log(chalk.yellow(`    ⚠ ${ov.warning}`));
+        }
+        if (ov.proxyTier) {
+            if (ov.proxyTier.clamped) {
+                console.log(chalk.yellow(`  ⚠ proxyTier requested ${ov.proxyTier.requested} → applied ${ov.proxyTier.effective}`)
+                    + chalk.dim(` (${ov.proxyTier.reason ?? 'capped'})`));
+            }
+            else {
+                console.log(chalk.dim(`  proxyTier: `) + ov.proxyTier.effective);
+            }
+        }
     }
 });
 // run
@@ -258,15 +303,31 @@ scraps
         await watchActivities(id);
     }
 });
+// #70 — render an items array either as a table summary or --json. Shared by
+// both the default (persisted read) and --fresh (live execute) paths of `data`.
+function renderScrapItems(items, asJson) {
+    if (asJson) {
+        json(items);
+        return;
+    }
+    console.log(chalk.bold('Last run data:'));
+    console.log(chalk.dim(`  Items: ${items.length}`));
+    if (items.length > 0 && typeof items[0] === 'object' && items[0] !== null) {
+        console.log(chalk.dim(`  First item keys: ${Object.keys(items[0]).join(', ')}`));
+    }
+    console.log(chalk.dim('  Use --json for full output.'));
+}
 // data
 scraps
     .command('data <id>')
-    .description('Get scrap data (latest run payload)')
+    .description('Get scrap data (last persisted run — read-only, no quota). Use --fresh to launch a new run instead.')
     .option('--json', 'Output as JSON')
     .option('--errors', 'Show failure diagnostics when the last run failed')
+    .option('--fresh', 'Launch a fresh run instead of reading the last persisted payload (consumes execute quota, same as `scraps run`)')
     .action(async (id, opts) => {
     validateObjectId(id);
-    // --errors: fetch full run + fix detail via fetchRunAndFix (DRY with doctor)
+    // --errors: fetch full run + fix detail via fetchRunAndFix (DRY with doctor).
+    // Read-only: GET /api/scraps/:id + GET /api/historys/:hid, no quota, no run lock.
     if (opts.errors) {
         const result = await fetchRunAndFix(id);
         if (!result) {
@@ -282,20 +343,53 @@ scraps
         console.log(formatDoctor(result.scrap.title, result.run, result.fix, id));
         return;
     }
-    const loaded = await api.get(`/api/scraps/load/${id}`);
-    const items = loaded?.result?.data;
-    if (!Array.isArray(items)) {
-        console.log(chalk.dim('No data yet. Run the scrap first.'));
+    // #70 — --fresh is the explicit opt-in for a LIVE run. This is what the
+    // default path used to do silently: GET /api/scraps/load/:id executes a
+    // fresh scrap run server-side (requireQuota('scraps','execute') + a
+    // distributed run lock — trawl_node modules/scraps/routes/scraps.routes.js),
+    // burning execute quota and 429ing if a run is already in flight. A user
+    // or agent "just reading data" must never trigger that by accident.
+    if (opts.fresh) {
+        const spinner = ora('Launching a fresh scrap run (consumes execute quota)…').start();
+        const loaded = await api.get(`/api/scraps/load/${id}`);
+        spinner.succeed('Fresh run complete');
+        const items = loaded?.result?.data;
+        if (!Array.isArray(items)) {
+            console.log(chalk.dim('No data yet. Run the scrap first.'));
+            return;
+        }
+        renderScrapItems(items, opts.json);
         return;
     }
-    if (opts.json)
-        return json(items);
-    console.log(chalk.bold('Last run data:'));
-    console.log(chalk.dim(`  Items: ${items.length}`));
-    if (items.length > 0 && typeof items[0] === 'object' && items[0] !== null) {
-        console.log(chalk.dim(`  First item keys: ${Object.keys(items[0]).join(', ')}`));
+    // Default: read the last PERSISTED run payload — no quota, no run lock.
+    // History.data (trawl_node modules/historys/services/historys.service.js
+    // `update()`) is a JSON-stringified clone of the worker result, so it
+    // carries the same `.data` items array the live load endpoint returns —
+    // it's just pulled from the most recent history row instead of a fresh
+    // run. Retention keeps this only for the newest row per (scrap, status)
+    // bucket (config.trawl.keepData, default 1); older rows null it out.
+    const scrap = await api.get(`/api/scraps/${id}`);
+    const hid = scrap.history?.[0]?._id;
+    if (!hid) {
+        console.log(chalk.dim('No data yet. Run the scrap first, or pass --fresh to launch one now.'));
+        return;
     }
-    console.log(chalk.dim('  Use --json for full output.'));
+    const detail = await api.get(`/api/historys/${hid}`);
+    let items;
+    if (typeof detail?.data === 'string' && detail.data) {
+        try {
+            items = JSON.parse(detail.data)?.data;
+        }
+        catch {
+            items = undefined;
+        }
+    }
+    if (!Array.isArray(items)) {
+        console.log(chalk.dim('No persisted data for the last run (it may have failed, or aged out of retention). '
+            + 'Pass --fresh to launch a new run (consumes execute quota).'));
+        return;
+    }
+    renderScrapItems(items, opts.json);
 });
 // history — list past runs for a scrap
 scraps

package/dist/commands/telemetry.js

@@ -28,16 +28,20 @@ telemetry
     const enabled = config.get('telemetry') !== false;
     const userId = config.get('telemetryUserId') || '(not yet generated)';
     const envOverride = process.env['TRAWL_TELEMETRY'] === '0';
+    const doNotTrack = process.env['DO_NOT_TRACK'] === '1';
     console.log(chalk.bold('Telemetry status'));
     console.log(chalk.dim('  State:         ') +
-        (envOverride
-            ? chalk.yellow('disabled (TRAWL_TELEMETRY=0 env var)')
-            : enabled
-                ? chalk.green('enabled')
-                : chalk.yellow('disabled')));
+        (doNotTrack
+            ? chalk.yellow('disabled (DO_NOT_TRACK=1 env var)')
+            : envOverride
+                ? chalk.yellow('disabled (TRAWL_TELEMETRY=0 env var)')
+                : enabled
+                    ? chalk.green('enabled')
+                    : chalk.yellow('disabled')));
     console.log(chalk.dim('  Telemetry ID:  ') + userId);
     console.log('');
     console.log(chalk.dim('  To opt out:'));
     console.log(chalk.dim('    trawl telemetry off'));
     console.log(chalk.dim('    TRAWL_TELEMETRY=0  (env var, disables for this session)'));
+    console.log(chalk.dim('    DO_NOT_TRACK=1     (cross-tool env var, disables for this session)'));
 });

package/dist/commands/token.js

@@ -1,25 +1,7 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
 import config from '../lib/config.js';
-/**
- * Decode the exp claim from a JWT (middle segment, base64url encoded JSON).
- * Returns null if the payload cannot be decoded or has no exp field.
- */
-function decodeExp(jwt) {
-    try {
-        const parts = jwt.split('.');
-        if (parts.length !== 3)
-            return null;
-        const payload = Buffer.from(parts[1], 'base64url').toString('utf8');
-        const parsed = JSON.parse(payload);
-        if (typeof parsed.exp !== 'number')
-            return null;
-        return parsed.exp;
-    }
-    catch {
-        return null;
-    }
-}
+import { decodeExp } from '../lib/jwt.js';
 export const token = new Command('token')
     .description('Print the stored session JWT (for MCP Bearer auth)')
     .action(() => {
@@ -47,11 +29,15 @@ export const token = new Command('token')
         const daysLeft = secsLeft / 86400;
         if (daysLeft < 1) {
             const hoursLeft = Math.floor(secsLeft / 3600);
-            console.log(chalk.yellow(`⚠ Token expiring in ${hoursLeft}h. Run: trawl login to refresh.`));
+            // stderr, not stdout — this is an advisory, not the payload. `trawl
+            // token` exists so callers can capture the raw JWT via
+            // `$(trawl token)` for `Authorization: Bearer …`; anything printed
+            // to stdout after the token corrupts that capture. (#68)
+            console.error(chalk.yellow(`⚠ Token expiring in ${hoursLeft}h. Run: trawl login to refresh.`));
         }
         else {
             const daysRounded = Math.floor(daysLeft);
-            console.log(chalk.dim(`  Expires in ${daysRounded}d. Renew with: trawl login`));
+            console.error(chalk.dim(`  Expires in ${daysRounded}d. Renew with: trawl login`));
         }
     }
 });

package/dist/index.d.ts

@@ -1,2 +1,20 @@
 #!/usr/bin/env node
-export {};
+import { Command } from 'commander';
+/**
+ * Derive a safe telemetry event name from a *resolved* commander Command —
+ * NEVER from raw argv. Flag values (e.g. the string after --password/--email/
+ * --url) don't start with '-' and would otherwise survive an argv filter and
+ * leak to PostHog (#67). Falls back to 'unknown' when no command resolved
+ * (e.g. an error thrown before any action ran).
+ */
+export declare function resolveCommandName(actionCommand: Command | undefined): string;
+/**
+ * Walk the full command tree and produce every valid resolveCommandName()
+ * token — the allowlist registered with posthog.ts so captureCommand can
+ * never be handed a free-form string.
+ */
+export declare function collectCommandNames(root: Command): string[];
+export declare function createProgram(): Command;
+/** True when this module is the process entrypoint (not merely imported by a test). */
+export declare function isEntryPoint(argv1: string | undefined, moduleUrl: string): boolean;
+export declare function runCli(argv?: string[]): Promise<void>;

package/dist/index.js

@@ -2,7 +2,7 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
 import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { dirname, join } from 'node:path';
 import { login, logout } from './commands/login.js';
 import { scraps } from './commands/scraps.js';
@@ -10,49 +10,107 @@ import { skills } from './commands/skills.js';
 import { telemetry } from './commands/telemetry.js';
 import { token } from './commands/token.js';
 import { autoUpdateInstalledSkills } from './lib/skills.js';
-import { initPostHog, captureCommand, shutdown } from './lib/posthog.js';
-autoUpdateInstalledSkills();
-initPostHog();
+import { initPostHog, captureCommand, shutdown, registerAllowedCommands } from './lib/posthog.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
-const program = new Command()
-    .name('trawl')
-    .description('Trawl CLI — manage scraps from the terminal')
-    .version(pkg.version)
-    .option('--debug', 'Show full error stack traces');
-// Track start times per command instance for duration measurement
-const startTimes = new WeakMap();
-program.hook('preAction', (thisCommand, actionCommand) => {
-    startTimes.set(actionCommand, Date.now());
-});
-program.hook('postAction', (thisCommand, actionCommand) => {
-    const start = startTimes.get(actionCommand);
-    if (start !== undefined) {
-        const name = actionCommand.parent
-            ? `${actionCommand.parent.name()} ${actionCommand.name()}`
-            : actionCommand.name();
-        void captureCommand(name, { duration_ms: Date.now() - start, exit_code: 0 });
+/**
+ * Derive a safe telemetry event name from a *resolved* commander Command —
+ * NEVER from raw argv. Flag values (e.g. the string after --password/--email/
+ * --url) don't start with '-' and would otherwise survive an argv filter and
+ * leak to PostHog (#67). Falls back to 'unknown' when no command resolved
+ * (e.g. an error thrown before any action ran).
+ */
+export function resolveCommandName(actionCommand) {
+    if (!actionCommand)
+        return 'unknown';
+    return actionCommand.parent
+        ? `${actionCommand.parent.name()} ${actionCommand.name()}`
+        : actionCommand.name();
+}
+/**
+ * Walk the full command tree and produce every valid resolveCommandName()
+ * token — the allowlist registered with posthog.ts so captureCommand can
+ * never be handed a free-form string.
+ */
+export function collectCommandNames(root) {
+    const names = [];
+    const walk = (cmd) => {
+        for (const sub of cmd.commands) {
+            names.push(resolveCommandName(sub));
+            walk(sub);
+        }
+    };
+    walk(root);
+    return names;
+}
+export function createProgram() {
+    const program = new Command()
+        .name('trawl')
+        .description('Trawl CLI — manage scraps from the terminal')
+        .version(pkg.version)
+        .option('--debug', 'Show full error stack traces');
+    program.addCommand(login);
+    program.addCommand(logout);
+    program.addCommand(scraps);
+    program.addCommand(skills);
+    program.addCommand(telemetry);
+    program.addCommand(token);
+    return program;
+}
+/** True when this module is the process entrypoint (not merely imported by a test). */
+export function isEntryPoint(argv1, moduleUrl) {
+    return argv1 !== undefined && moduleUrl === pathToFileURL(argv1).href;
+}
+export async function runCli(argv = process.argv) {
+    autoUpdateInstalledSkills();
+    initPostHog();
+    const program = createProgram();
+    registerAllowedCommands(collectCommandNames(program));
+    // Track start times + the currently-resolved command per instance, so the
+    // catch handler below can derive the exact same safe name the success path
+    // uses — it must never re-derive anything from argv.
+    const startTimes = new WeakMap();
+    let currentCommand;
+    program.hook('preAction', (_thisCommand, actionCommand) => {
+        currentCommand = actionCommand;
+        startTimes.set(actionCommand, Date.now());
+    });
+    program.hook('postAction', (_thisCommand, actionCommand) => {
+        const start = startTimes.get(actionCommand);
+        if (start !== undefined) {
+            // Actions can fail without throwing (process.exitCode set directly) —
+            // report the real outcome instead of hardcoding success.
+            const exitCode = typeof process.exitCode === 'number' ? process.exitCode : 0;
+            void captureCommand(resolveCommandName(actionCommand), {
+                duration_ms: Date.now() - start,
+                exit_code: exitCode,
+            });
+        }
+    });
+    try {
+        await program.parseAsync(argv);
     }
-});
-program.addCommand(login);
-program.addCommand(logout);
-program.addCommand(scraps);
-program.addCommand(skills);
-program.addCommand(telemetry);
-program.addCommand(token);
-process.on('exit', () => {
-    void shutdown();
-});
-program.parseAsync().catch((err) => {
-    // Capture error telemetry (best-effort: command name from process.argv)
-    const name = process.argv.slice(2).filter((a) => !a.startsWith('-')).join(' ') || 'unknown';
-    void captureCommand(name, { exit_code: 1, error: err.name });
-    const { debug } = program.opts();
-    if (debug || process.env['DEBUG']) {
-        console.error(err);
+    catch (err) {
+        // Capture error telemetry from the resolved command only — never argv.
+        void captureCommand(resolveCommandName(currentCommand), {
+            exit_code: 1,
+            error: err.name,
+        });
+        const { debug } = program.opts();
+        if (debug || process.env['DEBUG']) {
+            console.error(err);
+        }
+        else {
+            console.error(chalk.red('✗ ' + err.message));
+        }
+        process.exitCode = 1;
     }
-    else {
-        console.error(chalk.red('✗ ' + err.message));
+    finally {
+        // Flush + close telemetry before the process exits. A `process.on('exit')`
+        // handler cannot reliably run async work, so this must happen here.
+        await shutdown();
     }
-    process.exitCode = 1;
-});
+}
+if (isEntryPoint(process.argv[1], import.meta.url)) {
+    void runCli();
+}

package/dist/lib/api.d.ts

@@ -5,7 +5,7 @@ export declare const api: {
     put: <T>(path: string, body?: unknown) => Promise<T>;
     delete: <T>(path: string) => Promise<T>;
     upload: <T>(path: string, formData: FormData) => Promise<T>;
-    publicPost: <T>(path: string, body?: unknown) => Promise<{
+    publicPost: <T>(path: string, body?: unknown, baseUrlOverride?: string) => Promise<{
         data: T;
         headers: Headers;
     }>;

package/dist/lib/api.js

@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
-import config, { getApiUrl } from './config.js';
+import { getApiUrl, getToken } from './config.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(resolve(__dirname, '../../package.json'), 'utf8'));
 const USER_AGENT = `@trawlme/cli/${pkg.version}`;
@@ -57,7 +57,7 @@ async function throwIfError(res, isPublic = false) {
     }
 }
 async function request(path, options = {}) {
-    const token = config.get('token');
+    const token = getToken();
     if (!token)
         throw new Error('Not logged in. Run: trawl login');
     const url = `${getApiUrl()}${path}`;
@@ -87,7 +87,7 @@ async function request(path, options = {}) {
     }
 }
 async function upload(path, formData) {
-    const token = config.get('token');
+    const token = getToken();
     if (!token)
         throw new Error('Not logged in. Run: trawl login');
     const url = `${getApiUrl()}${path}`;
@@ -116,8 +116,8 @@ async function upload(path, formData) {
         throw new Error('Invalid JSON in server response');
     }
 }
-async function publicPost(path, body) {
-    const url = `${getApiUrl()}${path}`;
+async function publicPost(path, body, baseUrlOverride) {
+    const url = `${baseUrlOverride ?? getApiUrl()}${path}`;
     const res = await fetch(url, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json', 'User-Agent': USER_AGENT },
@@ -134,7 +134,7 @@ async function publicPost(path, body) {
     }
 }
 async function getText(path) {
-    const token = config.get('token');
+    const token = getToken();
     if (!token)
         throw new Error('Not logged in. Run: trawl login');
     const url = `${getApiUrl()}${path}`;
@@ -160,9 +160,9 @@ export const api = {
     }),
     delete: (path) => request(path, { method: 'DELETE' }),
     upload: (path, formData) => upload(path, formData),
-    publicPost: (path, body) => publicPost(path, body),
+    publicPost: (path, body, baseUrlOverride) => publicPost(path, body, baseUrlOverride),
     stream: async function* (path) {
-        const token = config.get('token');
+        const token = getToken();
         if (!token)
             throw new Error('Not logged in. Run: trawl login');
         const url = `${getApiUrl()}${path}`;

package/dist/lib/config.d.ts

@@ -14,4 +14,15 @@ declare const config: Conf<TrawlConfig>;
  * without mutating the operator's persisted config. (#56)
  */
 export declare function getApiUrl(): string;
+/**
+ * Resolve the effective session token.
+ * Precedence: TRAWL_TOKEN env > stored `trawl login` token.
+ * Lets CI/agents authenticate headlessly (`TRAWL_TOKEN=<jwt> trawl scraps list`)
+ * without ever touching the on-disk config — and without a stored token being
+ * silently sent to whatever TRAWL_API_URL points at instead (cross-env
+ * credential misuse). Every request/upload/getText/stream call site in
+ * api.ts must read the token through this, never through `config.get('token')`
+ * directly. Mirrors getApiUrl(). (#68)
+ */
+export declare function getToken(): string;
 export default config;

package/dist/lib/config.js

@@ -1,6 +1,16 @@
 import Conf from 'conf';
+/**
+ * TRAWL_CONFIG_DIR overrides where Conf stores the config file (its `cwd`
+ * option). Without this, the CLI has zero config isolation on macOS — Conf's
+ * env-paths dependency hardcodes `~/Library/Preferences/...` and ignores
+ * XDG_CONFIG_HOME — so CI/agent runs and concurrent `trawl login`s race on
+ * one shared on-disk file. Point at an ephemeral dir for hermetic runs, e.g.
+ * `TRAWL_CONFIG_DIR=$(mktemp -d) trawl login --token …`. Rescope of #59. (#68)
+ */
+const configDir = process.env['TRAWL_CONFIG_DIR']?.trim();
 const config = new Conf({
     projectName: 'trawl-cli',
+    ...(configDir ? { cwd: configDir } : {}),
     defaults: {
         apiUrl: 'https://api.trawl.me',
         token: '',
@@ -19,4 +29,18 @@ export function getApiUrl() {
     const override = process.env['TRAWL_API_URL']?.trim();
     return override ? override : config.get('apiUrl');
 }
+/**
+ * Resolve the effective session token.
+ * Precedence: TRAWL_TOKEN env > stored `trawl login` token.
+ * Lets CI/agents authenticate headlessly (`TRAWL_TOKEN=<jwt> trawl scraps list`)
+ * without ever touching the on-disk config — and without a stored token being
+ * silently sent to whatever TRAWL_API_URL points at instead (cross-env
+ * credential misuse). Every request/upload/getText/stream call site in
+ * api.ts must read the token through this, never through `config.get('token')`
+ * directly. Mirrors getApiUrl(). (#68)
+ */
+export function getToken() {
+    const override = process.env['TRAWL_TOKEN']?.trim();
+    return override ? override : config.get('token');
+}
 export default config;

package/dist/lib/jwt.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Decode the `exp` claim from a JWT (middle segment, base64url-encoded JSON).
+ * Returns null if the payload cannot be decoded or has no `exp` field.
+ *
+ * Shared between `trawl token` (expiry advisory) and `trawl login` (reject
+ * already-expired tokens instead of silently storing them). (#68)
+ */
+export declare function decodeExp(jwt: string): number | null;

package/dist/lib/jwt.js

@@ -0,0 +1,22 @@
+/**
+ * Decode the `exp` claim from a JWT (middle segment, base64url-encoded JSON).
+ * Returns null if the payload cannot be decoded or has no `exp` field.
+ *
+ * Shared between `trawl token` (expiry advisory) and `trawl login` (reject
+ * already-expired tokens instead of silently storing them). (#68)
+ */
+export function decodeExp(jwt) {
+    try {
+        const parts = jwt.split('.');
+        if (parts.length !== 3)
+            return null;
+        const payload = Buffer.from(parts[1], 'base64url').toString('utf8');
+        const parsed = JSON.parse(payload);
+        if (typeof parsed.exp !== 'number')
+            return null;
+        return parsed.exp;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/lib/posthog.d.ts

@@ -1,4 +1,13 @@
 export declare const initPostHog: () => void;
+/**
+ * Register the complete set of valid "<parent> <name>" telemetry tokens,
+ * derived from the actual commander command tree (see resolveCommandName /
+ * collectCommandNames in src/index.ts). captureCommand refuses any command
+ * string outside this set — defense in depth so free-form user input (argv
+ * operands, flag values) can never reach PostHog as the event name, even if a
+ * future change accidentally reintroduces argv-derived naming.
+ */
+export declare const registerAllowedCommands: (names: readonly string[]) => void;
 export declare const captureCommand: (command: string, props?: Record<string, unknown>) => void;
 export declare const shutdown: () => Promise<void>;
 /** Reset singleton state — for testing only */

package/dist/lib/posthog.js

@@ -1,4 +1,5 @@
 import { PostHog } from 'posthog-node';
+import chalk from 'chalk';
 import os from 'node:os';
 import crypto from 'node:crypto';
 import { readFileSync } from 'node:fs';
@@ -8,26 +9,66 @@ import config from './config.js';
 // public-by-design — cf memory feedback_public_keys_in_config.md
 const POSTHOG_KEY = 'phc_pGgSLivbq8rDZzXC9trWWJG7sBjNghXeTJjETzBcnEDv';
 const POSTHOG_HOST = 'https://eu.i.posthog.com';
+// Fail fast: a firewalled/offline endpoint must never add tens of seconds of
+// trailing latency to a CLI command. Library defaults are requestTimeout 10s x
+// 3 retries at a 3s delay (~40s+ worst case per call), and a 30s shutdown
+// ceiling on top of that — cap all three low.
+const REQUEST_TIMEOUT_MS = 3000;
+const FETCH_RETRY_COUNT = 1;
+const FETCH_RETRY_DELAY_MS = 250;
+// A touch above one request + one retry, so the shutdown-time flush has room
+// to complete normally without inheriting the library's 30s default ceiling.
+const SHUTDOWN_TIMEOUT_MS = 8000;
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(resolve(__dirname, '../../package.json'), 'utf8'));
 let client = null;
 let distinctId = null;
+let allowedCommands = new Set();
+/**
+ * Cross-vendor opt-out (https://consoledonottrack.com) on top of the existing
+ * config/env gates. Any one of these disables telemetry entirely.
+ */
+function isTelemetryDisabled() {
+    return (config.get('telemetry') === false ||
+        process.env['TRAWL_TELEMETRY'] === '0' ||
+        process.env['DO_NOT_TRACK'] === '1');
+}
 export const initPostHog = () => {
-    if (config.get('telemetry') === false || process.env['TRAWL_TELEMETRY'] === '0')
+    if (isTelemetryDisabled())
         return;
-    if (!config.get('telemetryUserId')) {
+    const isFirstRun = !config.get('telemetryUserId');
+    if (isFirstRun) {
         config.set('telemetryUserId', `cli_${crypto.randomUUID()}`);
+        // One-time disclosure — telemetry is on by default and otherwise silent.
+        console.error(chalk.dim('ℹ Trawl CLI collects anonymous usage telemetry (no credentials or command arguments). ' +
+            'Opt out: trawl telemetry off, TRAWL_TELEMETRY=0, or DO_NOT_TRACK=1.'));
     }
     distinctId = config.get('telemetryUserId');
     client = new PostHog(POSTHOG_KEY, {
         host: POSTHOG_HOST,
         flushAt: 1,
         flushInterval: 0,
+        requestTimeout: REQUEST_TIMEOUT_MS,
+        fetchRetryCount: FETCH_RETRY_COUNT,
+        fetchRetryDelay: FETCH_RETRY_DELAY_MS,
     });
 };
+/**
+ * Register the complete set of valid "<parent> <name>" telemetry tokens,
+ * derived from the actual commander command tree (see resolveCommandName /
+ * collectCommandNames in src/index.ts). captureCommand refuses any command
+ * string outside this set — defense in depth so free-form user input (argv
+ * operands, flag values) can never reach PostHog as the event name, even if a
+ * future change accidentally reintroduces argv-derived naming.
+ */
+export const registerAllowedCommands = (names) => {
+    allowedCommands = new Set(names);
+};
 export const captureCommand = (command, props = {}) => {
     if (!client || !distinctId)
         return;
+    if (!allowedCommands.has(command))
+        return;
     client.capture({
         distinctId,
         event: 'cli.command.run',
@@ -42,11 +83,14 @@ export const captureCommand = (command, props = {}) => {
     });
 };
 export const shutdown = async () => {
+    // Explicit ceiling — client.shutdown() otherwise defaults to a 30s internal
+    // race, which would undercut the whole point of capping request/retry time.
     if (client)
-        await client.shutdown();
+        await client.shutdown(SHUTDOWN_TIMEOUT_MS);
 };
 /** Reset singleton state — for testing only */
 export const _resetForTesting = () => {
     client = null;
     distinctId = null;
+    allowedCommands = new Set();
 };

package/dist/lib/prompt.js

@@ -1,6 +1,6 @@
 export async function promptPassword(prompt) {
     process.stderr.write(prompt);
-    return new Promise((resolve) => {
+    return new Promise((resolve, reject) => {
         let password = '';
         if (process.stdin.isTTY) {
             process.stdin.setRawMode(true);
@@ -31,13 +31,24 @@ export async function promptPassword(prompt) {
             process.stdin.on('data', onData);
         }
         else {
-            // Non-TTY fallback (e.g. piped input in CI)
+            // Non-TTY fallback (e.g. piped input in CI). If stdin closes (EOF)
+            // before an answer arrives — e.g. `trawl login < /dev/null` — the
+            // `question` callback never fires; without a `close` handler the
+            // promise hangs forever and the process exits 0 without logging in.
+            // Reject loudly instead. (#68)
             import('readline').then(({ createInterface }) => {
                 const rl = createInterface({ input: process.stdin, output: process.stdout });
+                let answered = false;
                 rl.question('', (answer) => {
+                    answered = true;
                     rl.close();
                     resolve(answer.trim());
                 });
+                rl.on('close', () => {
+                    if (!answered) {
+                        reject(new Error('No input received — pass -e/-p or set TRAWL_TOKEN for non-interactive use'));
+                    }
+                });
             });
         }
     });

package/dist/lib/validate.d.ts

@@ -2,3 +2,12 @@ export declare function validateObjectId(id: string): void;
 export declare function requireString(value: unknown, name: string): string;
 export declare function requireUrl(value: unknown, name: string): string;
 export declare function requireJwt(value: unknown, name: string): string;
+/**
+ * Like requireJwt, but also rejects a JWT whose `exp` claim has already
+ * passed — `trawl login --token <expired>` / `TRAWL_TOKEN=<expired>` must
+ * not print "✓ Logged in" for a token that can't actually authenticate.
+ * A JWT with an undecodable/opaque payload is let through (we can't prove
+ * it's expired), mirroring `trawl token`'s advisory-only handling of the
+ * same case. (#68)
+ */
+export declare function requireFreshJwt(value: unknown, name: string): string;

package/dist/lib/validate.js

@@ -1,3 +1,4 @@
+import { decodeExp } from './jwt.js';
 export function validateObjectId(id) {
     if (!/^[0-9a-fA-F]{24}$/.test(id)) {
         throw new Error(`Invalid scrap ID: "${id}" — expected a 24-char hex ObjectId`);
@@ -31,3 +32,20 @@ export function requireJwt(value, name) {
     }
     return str;
 }
+/**
+ * Like requireJwt, but also rejects a JWT whose `exp` claim has already
+ * passed — `trawl login --token <expired>` / `TRAWL_TOKEN=<expired>` must
+ * not print "✓ Logged in" for a token that can't actually authenticate.
+ * A JWT with an undecodable/opaque payload is let through (we can't prove
+ * it's expired), mirroring `trawl token`'s advisory-only handling of the
+ * same case. (#68)
+ */
+export function requireFreshJwt(value, name) {
+    const jwt = requireJwt(value, name);
+    const exp = decodeExp(jwt);
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    if (exp !== null && exp < nowSeconds) {
+        throw new Error(`${name} is an expired JWT (exp has already passed) — obtain a fresh token and retry`);
+    }
+    return jwt;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trawlme/cli",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "description": "Trawl CLI — manage scraps from the terminal",
   "type": "module",
   "bin": {
@@ -12,7 +12,7 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "scripts": {
     "build": "tsc",