@trawlme/cli 1.14.0 → 1.16.0

package/README.md

@@ -117,9 +117,15 @@ TRAWL_TELEMETRY=0 trawl scraps list
 | Variable           | Description                                                       |
 |--------------------|-------------------------------------------------------------------|
 | `TRAWL_TOKEN`      | JWT token — bypasses login prompt, useful for CI/CD               |
-| `TRAWL_API_URL`    | Override the default API URL (`https://api.trawl.me`)             |
+| `TRAWL_API_URL`    | Override the API base URL for the session (takes precedence over `trawl login --url`) |
 | `TRAWL_TELEMETRY`  | Set to `0` to disable telemetry for the current session           |
 
+Session override (no `trawl login` mutation, ideal for CI/QA against another env):
+
+```bash
+TRAWL_API_URL=https://dev.trawl.me TRAWL_TOKEN=<jwt> trawl scraps list --json
+```
+
 ## API documentation
 
 The Trawl API is documented at [trawl.me/api/spec.json](https://trawl.me/api/spec.json) (OpenAPI 3).

package/dist/commands/doctor.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Run diagnostics shape — mirrors the owner-safe REST shape returned by
+ * GET /api/historys/:id (Phase 1 projection, 2026-05-27).
+ * Cost and proxy-nature fields are intentionally absent by design.
+ * Abstract proxyTier (Tier 0–4) is kept.
+ */
+export interface Run {
+    _id: string;
+    status: boolean | null;
+    statusDetail: 'success' | 'error' | 'empty' | 'regression' | null;
+    length?: number | null;
+    errorMessage?: string | null;
+    errorSnapshot?: {
+        selector?: string | null;
+        errorMessage?: string | null;
+        html?: string | null;
+        capturedAt?: string | null;
+    } | null;
+    emptyContext?: {
+        page?: {
+            url?: string;
+            title?: string;
+            totalAnchors?: number;
+        };
+        selectors?: Record<string, number>;
+    } | null;
+    blocked?: boolean;
+    proxyTier?: string | null;
+    regressionDetected?: boolean;
+    baselineLength?: number | null;
+    fixVersionId?: string | null;
+    createdAt?: string;
+    time?: number | null;
+    triggeredBy?: string | null;
+}
+/**
+ * Autofix activity metadata — from the persisted ai_fix_end activity.
+ * aiUsage (cost) is stripped server-side; all diagnostics are kept.
+ */
+export interface FixActivity {
+    outcome: 'applied' | 'failed' | 'skipped' | 'breaker_tripped' | 'timeout' | null;
+    classification?: string | null;
+    reason?: string | null;
+    fixDiff?: string | null;
+    dryRunResults?: Array<{
+        status: 'success' | 'error';
+        error?: string;
+    }> | null;
+    knowledgeUsed?: Array<{
+        fingerprint: string;
+        confidence?: number | null;
+    }> | null;
+    attempt?: number;
+    maxAttempts?: number;
+    versionId?: string | null;
+    createdAt?: string;
+}
+interface ScrapHead {
+    _id: string;
+    title: string;
+    history?: Array<{
+        _id?: string;
+        status?: boolean | null;
+        createdAt?: string;
+    }>;
+}
+export declare function pickRun(run: Run): Partial<Run>;
+export declare function pickFix(fix: FixActivity | null): Partial<FixActivity> | null;
+/**
+ * Pure formatter — returns a human-readable diagnosis string for a run.
+ * Used by `doctor`, `doctor --autofix`, and `data --errors`.
+ *
+ * @param scrapTitle - Display name of the scrap
+ * @param run        - Owner-safe history run object
+ * @param fix        - Optional autofix activity (null = no fix attempted)
+ * @param scrapId    - Scrap document id (used in hint lines — autofix/snapshot take scrap id, not run id)
+ * @returns Multi-line string ready for console.log
+ */
+export declare function formatDoctor(scrapTitle: string, run: Run, fix?: FixActivity | null, scrapId?: string): string;
+/**
+ * Pure formatter — returns a human-readable autofix detail block.
+ * Shows diff, dry-run results, knowledge consulted.
+ */
+export declare function formatAutofix(fix: FixActivity): string;
+/**
+ * Fetch the latest run + its ai_fix_end activity for a scrap.
+ * Returns null if the scrap has no runs yet.
+ */
+export declare function fetchRunAndFix(scrapId: string): Promise<{
+    scrap: ScrapHead;
+    run: Run;
+    fix: FixActivity | null;
+} | null>;
+export {};

package/dist/commands/doctor.js

@@ -0,0 +1,140 @@
+import { api } from '../lib/api.js';
+import chalk from 'chalk';
+const TIER_LABELS = {
+    tier0: 'Tier 0',
+    tier1: 'Tier 1',
+    tier2: 'Tier 2',
+    tier3: 'Tier 3',
+    tier4: 'Tier 4',
+};
+const RUN_ALLOWLIST = [
+    '_id', 'status', 'statusDetail', 'length', 'errorMessage', 'errorSnapshot',
+    'emptyContext', 'blocked', 'proxyTier', 'regressionDetected', 'baselineLength',
+    'fixVersionId', 'createdAt', 'time', 'triggeredBy',
+];
+const FIX_ALLOWLIST = [
+    'outcome', 'classification', 'reason', 'fixDiff', 'dryRunResults',
+    'knowledgeUsed', 'attempt', 'maxAttempts', 'versionId', 'createdAt',
+];
+export function pickRun(run) {
+    return Object.fromEntries(RUN_ALLOWLIST
+        .filter((k) => k in run)
+        .map((k) => [k, run[k]]));
+}
+export function pickFix(fix) {
+    if (!fix)
+        return null;
+    return Object.fromEntries(FIX_ALLOWLIST
+        .filter((k) => k in fix)
+        .map((k) => [k, fix[k]]));
+}
+/**
+ * Pure formatter — returns a human-readable diagnosis string for a run.
+ * Used by `doctor`, `doctor --autofix`, and `data --errors`.
+ *
+ * @param scrapTitle - Display name of the scrap
+ * @param run        - Owner-safe history run object
+ * @param fix        - Optional autofix activity (null = no fix attempted)
+ * @param scrapId    - Scrap document id (used in hint lines — autofix/snapshot take scrap id, not run id)
+ * @returns Multi-line string ready for console.log
+ */
+export function formatDoctor(scrapTitle, run, fix = null, scrapId) {
+    const lines = [];
+    // Header + status badge
+    const ok = run.status === true;
+    const badge = ok
+        ? chalk.green('● success')
+        : run.statusDetail === 'empty'
+            ? chalk.yellow('● empty')
+            : chalk.red('● failed');
+    lines.push(`${chalk.bold(scrapTitle)}  ${badge}${run.statusDetail ? ` (${run.statusDetail})` : ''}`);
+    lines.push(chalk.dim(`  Run ID:  ${run._id}`));
+    // Error message
+    const errMsg = run.errorMessage ?? run.errorSnapshot?.errorMessage;
+    if (errMsg) {
+        lines.push(chalk.dim('  Error:   ') + chalk.red(errMsg));
+    }
+    // Failed selector
+    if (run.errorSnapshot?.selector) {
+        lines.push(chalk.dim('  Failed selector: ') + chalk.cyan(run.errorSnapshot.selector));
+    }
+    // Blocked
+    lines.push(chalk.dim('  Blocked: ') + (run.blocked ? chalk.red('yes') : 'no'));
+    // Proxy tier (abstract, kept for owner)
+    if (run.proxyTier && TIER_LABELS[run.proxyTier]) {
+        lines.push(chalk.dim('  Proxy:   ') + TIER_LABELS[run.proxyTier]);
+    }
+    // Empty context detail
+    if (run.statusDetail === 'empty' && run.emptyContext?.page) {
+        const page = run.emptyContext.page;
+        lines.push(chalk.dim('  Empty context:   ') + `url=${page.url ?? '?'}  anchors=${page.totalAnchors ?? '?'}`);
+    }
+    // Regression detail
+    if (run.regressionDetected) {
+        lines.push(chalk.dim('  Regression:      ') + `length ${run.length ?? '?'} vs baseline ${run.baselineLength ?? '?'}`);
+    }
+    // Autofix summary (when fix exists)
+    if (fix) {
+        lines.push(`  ${chalk.magenta('Autofix:')}        ${fix.outcome ?? '?'}${fix.classification ? ` — ${fix.classification}` : ''}${fix.reason ? ` (${fix.reason})` : ''}`);
+        lines.push(chalk.dim(`  → full diff/dry-run/knowledge: trawl scraps autofix ${scrapId ?? run._id}  (or doctor --autofix)`));
+    }
+    // Timestamp
+    if (run.createdAt) {
+        lines.push(chalk.dim('  Run at:  ') + new Date(run.createdAt).toLocaleString());
+    }
+    // Snapshot hint
+    if (run.errorSnapshot?.html || run.statusDetail === 'empty' || run.statusDetail === 'error') {
+        lines.push('');
+        lines.push(chalk.dim(`  → trawl scraps snapshot ${scrapId ?? run._id} --error   (download error-path HTML)`));
+    }
+    return lines.join('\n');
+}
+/**
+ * Pure formatter — returns a human-readable autofix detail block.
+ * Shows diff, dry-run results, knowledge consulted.
+ */
+export function formatAutofix(fix) {
+    const lines = [];
+    lines.push(chalk.magenta.bold('Autofix attempt'));
+    lines.push(`  Decision:  ${fix.outcome ?? '?'}${fix.classification ? ` — ${fix.classification}` : ''}${fix.reason ? ` (${fix.reason})` : ''}`);
+    if (fix.versionId)
+        lines.push(`  Version:   ${fix.versionId}`);
+    lines.push('  Fix diff:');
+    if (fix.fixDiff && fix.fixDiff.trim()) {
+        for (const l of fix.fixDiff.split('\n')) {
+            const c = l.startsWith('+') ? chalk.green(l) : l.startsWith('-') ? chalk.red(l) : chalk.dim(l);
+            lines.push(`    ${c}`);
+        }
+    }
+    else {
+        lines.push(chalk.dim('    No code change — no-op recovery (site recovered between fail and dry-run).'));
+    }
+    if (fix.dryRunResults?.length) {
+        const ok = fix.dryRunResults.filter((d) => d.status === 'success').length;
+        lines.push(`  Dry-run:   ${ok}/${fix.dryRunResults.length} succeeded`);
+        fix.dryRunResults
+            .filter((d) => d.status === 'error' && d.error)
+            .forEach((d) => lines.push(chalk.red(`    ✗ ${d.error}`)));
+    }
+    if (fix.knowledgeUsed?.length) {
+        lines.push('  Knowledge consulted:');
+        fix.knowledgeUsed.forEach((k) => lines.push(`    • ${k.fingerprint}${k.confidence != null ? ` (${Math.round(k.confidence * 100)}%)` : ''}`));
+    }
+    return lines.join('\n');
+}
+/**
+ * Fetch the latest run + its ai_fix_end activity for a scrap.
+ * Returns null if the scrap has no runs yet.
+ */
+export async function fetchRunAndFix(scrapId) {
+    const scrap = await api.get(`/api/scraps/${scrapId}`);
+    const hid = scrap.history?.[0]?._id;
+    if (!hid)
+        return null;
+    const run = await api.get(`/api/historys/${hid}`);
+    // api.get unwraps the { data: T } envelope — the response is the array directly
+    const acts = await api.get(`/api/scraps/${scrapId}/activities?history=${hid}&limit=5`);
+    const fixAct = Array.isArray(acts) ? acts.find((a) => a.type === 'ai_fix_end') : undefined;
+    const fix = fixAct ? { ...fixAct.metadata, createdAt: fixAct.createdAt } : null;
+    return { scrap, run, fix };
+}

package/dist/commands/login.js

@@ -1,6 +1,6 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
-import config from '../lib/config.js';
+import config, { getApiUrl } from '../lib/config.js';
 import { api } from '../lib/api.js';
 import { requireJwt, requireUrl } from '../lib/validate.js';
 import { promptPassword } from '../lib/prompt.js';
@@ -30,7 +30,7 @@ export const login = new Command('login')
     if (envToken) {
         config.set('token', requireJwt(envToken, 'TRAWL_TOKEN'));
         console.log(chalk.green('✓ Logged in'));
-        console.log(chalk.dim(`  API: ${config.get('apiUrl')}`));
+        console.log(chalk.dim(`  API: ${getApiUrl()}`));
         console.log(chalk.dim(`  Config: ${config.path}`));
         return;
     }
@@ -38,7 +38,7 @@ export const login = new Command('login')
     if (opts.token) {
         config.set('token', requireJwt(opts.token, '--token'));
         console.log(chalk.green('✓ Logged in'));
-        console.log(chalk.dim(`  API: ${config.get('apiUrl')}`));
+        console.log(chalk.dim(`  API: ${getApiUrl()}`));
         console.log(chalk.dim(`  Config: ${config.path}`));
         return;
     }
@@ -63,7 +63,7 @@ export const login = new Command('login')
     const token = requireJwt(raw, 'token');
     config.set('token', token);
     console.log(chalk.green(`✓ Logged in as ${email}`));
-    console.log(chalk.dim(`  API: ${config.get('apiUrl')}`));
+    console.log(chalk.dim(`  API: ${getApiUrl()}`));
     console.log(chalk.dim(`  Config: ${config.path}`));
 });
 export const logout = new Command('logout')

package/dist/commands/scraps.js

@@ -5,6 +5,7 @@ import { api } from '../lib/api.js';
 import { table, json } from '../lib/format.js';
 import { promptPassword } from '../lib/prompt.js';
 import { validateObjectId } from '../lib/validate.js';
+import { formatDoctor, formatAutofix, fetchRunAndFix, pickRun, pickFix } from './doctor.js';
 function lastStatus(scrap) {
     const last = scrap.history?.[0];
     if (!last || last.status === null || last.status === undefined)
@@ -55,13 +56,51 @@ scraps
     .description('List all scraps')
     .option('--json', 'Output as JSON')
     .option('--status <status>', 'Filter by last run status (success|failure|never)')
+    .option('--limit <n>', 'Show only the first N results', (v) => parseInt(v, 10))
+    .option('--page <n>', 'Fetch a specific page only (50 per page, no auto-pagination)', (v) => parseInt(v, 10))
     .action(async (opts) => {
+    // Guard: --limit and --page are mutually exclusive
+    if (opts.limit !== undefined && opts.page !== undefined) {
+        console.log(chalk.red('✗ --limit and --page are mutually exclusive. Use one or the other.'));
+        process.exitCode = 1;
+        return;
+    }
     const spinner = ora('Fetching scraps…').start();
-    const data = await api.get('/api/scraps');
-    spinner.stop();
-    let rows = data;
+    let data;
+    try {
+        if (opts.page !== undefined) {
+            // Single-page mode: explicit page requested, no loop
+            const pageNum = opts.page;
+            data = await api.get(`/api/scraps?perPage=50&page=${pageNum}`);
+        }
+        else {
+            // Fetch-all mode: paginate until a page returns < 200 items
+            const perPage = 200;
+            data = [];
+            let page = 1;
+            while (true) {
+                const batch = await api.get(`/api/scraps?perPage=${perPage}&page=${page}`);
+                data = data.concat(batch);
+                if (batch.length < perPage)
+                    break;
+                page++;
+            }
+        }
+    }
+    catch (err) {
+        spinner.stop();
+        console.log(chalk.red(`✗ Failed to fetch scraps: ${err.message}`));
+        process.exitCode = 1;
+        return;
+    }
+    finally {
+        spinner.stop();
+    }
     if (opts.status)
-        rows = rows.filter((s) => lastStatus(s) === opts.status);
+        data = data.filter((s) => lastStatus(s) === opts.status);
+    const totalMatched = data.length;
+    const limit = opts.limit;
+    const rows = limit !== undefined ? data.slice(0, limit) : data;
     if (opts.json)
         return json(rows);
     const tableRows = rows.map((s) => ({
@@ -73,6 +112,10 @@ scraps
         updated: new Date(s.updatedAt).toLocaleDateString(),
     }));
     table(tableRows, ['id', 'title', 'cron', 'status', 'last run', 'updated']);
+    // Print footer when --limit truncates
+    if (limit !== undefined && rows.length < totalMatched) {
+        console.log(chalk.dim(`Showing ${rows.length} of ${totalMatched} — omit --limit to see all`));
+    }
 });
 // get
 scraps
@@ -220,8 +263,25 @@ scraps
     .command('data <id>')
     .description('Get scrap data (latest run payload)')
     .option('--json', 'Output as JSON')
+    .option('--errors', 'Show failure diagnostics when the last run failed')
     .action(async (id, opts) => {
     validateObjectId(id);
+    // --errors: fetch full run + fix detail via fetchRunAndFix (DRY with doctor)
+    if (opts.errors) {
+        const result = await fetchRunAndFix(id);
+        if (!result) {
+            console.log(chalk.dim('No runs yet.'));
+            return;
+        }
+        if (result.run.status === true) {
+            console.log(chalk.green('✓ Last run succeeded. No errors to show.'));
+            return;
+        }
+        if (opts.json)
+            return json(pickRun(result.run));
+        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)) {
@@ -232,14 +292,67 @@ scraps
         return json(items);
     console.log(chalk.bold('Last run data:'));
     console.log(chalk.dim(`  Items: ${items.length}`));
-    if (loaded?.result?._proxyTier) {
-        console.log(chalk.dim(`  Proxy tier: ${loaded.result._proxyTier}`));
-    }
     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.'));
 });
+// history — list past runs for a scrap
+scraps
+    .command('history <id>')
+    .description('List past runs for a scrap (newest first)')
+    .option('--json', 'Output as JSON')
+    .option('-n, --limit <n>', 'Max runs to show', '20')
+    .action(async (id, opts) => {
+    validateObjectId(id);
+    const limit = Number(opts.limit);
+    if (!Number.isInteger(limit) || limit < 1) {
+        console.log(chalk.red(`✗ Invalid --limit "${opts.limit}" (expected a positive integer)`));
+        process.exitCode = 1;
+        return;
+    }
+    const scrap = await api.get(`/api/scraps/${id}`);
+    const runs = (scrap.history ?? []).slice(0, limit).map((h) => ({
+        hid: h._id,
+        status: h.statusDetail ?? null,
+        time: h.time ?? null,
+        tier: h.proxyTier ?? null,
+        failureKind: h.failureKind ?? null,
+        blockType: h.blockType ?? null,
+        createdAt: h.createdAt ?? null,
+    }));
+    if (opts.json) {
+        json(runs);
+        return;
+    }
+    table(runs, ['hid', 'status', 'time', 'tier', 'failureKind', 'blockType', 'createdAt']);
+});
+// run-info — single-run detail by history id
+scraps
+    .command('run-info <hid>')
+    .description('Show details of a single run (status, tier, failureKind, error)')
+    .option('--json', 'Output as JSON')
+    .action(async (hid, opts) => {
+    validateObjectId(hid);
+    const h = await api.get(`/api/historys/${hid}`);
+    const info = {
+        hid,
+        status: h.statusDetail ?? null,
+        time: h.time ?? null,
+        tier: h.proxyTier ?? null,
+        failureKind: h.failureKind ?? null,
+        blockType: h.blockType ?? null,
+        errorMessage: h.errorSnapshot?.errorMessage ?? null,
+        selector: h.errorSnapshot?.selector ?? null,
+        emptyContext: h.errorSnapshot?.emptyContext ?? null,
+        createdAt: h.createdAt ?? null,
+    };
+    if (opts.json) {
+        json(info);
+        return;
+    }
+    table([info], ['hid', 'status', 'time', 'tier', 'failureKind', 'blockType', 'errorMessage', 'selector', 'emptyContext', 'createdAt']);
+});
 // delete
 scraps
     .command('delete <id>')
@@ -311,13 +424,18 @@ scraps
 // trigger
 scraps
     .command('trigger <id>')
-    .description('Launch a scrap as a background worker')
+    .description('Launch a scrap as a background worker (returns immediately)')
     .option('-w, --watch', 'Stream activities after triggering')
+    .option('--wait', 'Run synchronously and wait for the result (legacy behaviour)')
     .action(async (id, opts) => {
     validateObjectId(id);
-    const spinner = ora('Triggering worker…').start();
-    await api.post(`/api/scraps/worker/${id}`);
-    spinner.succeed('Worker triggered');
+    const spinner = ora(opts.wait ? 'Running worker…' : 'Triggering worker…').start();
+    // #50 — default async: the backend (#1313) kicks off the run and returns a
+    // 'queued' envelope immediately instead of holding the connection for the
+    // whole run. --wait restores the old synchronous round-trip.
+    const path = opts.wait ? `/api/scraps/worker/${id}` : `/api/scraps/worker/${id}?wait=false`;
+    await api.post(path);
+    spinner.succeed(opts.wait ? 'Worker run complete' : 'Worker triggered');
     if (opts.watch)
         await watchActivities(id);
 });
@@ -501,3 +619,68 @@ account
     }
     console.log(`${credLine} | ${sessionLine}`);
 });
+// doctor — diagnose last run of a scrap (error, failed selector, block status, page state, autofix)
+scraps
+    .command('doctor <id>')
+    .description('Diagnose the last run (error, failed selector, block status, page state, autofix outcome)')
+    .option('--json', 'Output raw run + autofix JSON')
+    .option('--autofix', 'Include the full autofix diff / dry-run / knowledge')
+    .action(async (id, opts) => {
+    validateObjectId(id);
+    const result = await fetchRunAndFix(id);
+    if (!result) {
+        console.log(chalk.dim('No runs yet.'));
+        return;
+    }
+    if (opts.json)
+        return json({ run: pickRun(result.run), fix: pickFix(result.fix) });
+    console.log(formatDoctor(result.scrap.title, result.run, result.fix, id));
+    if (opts.autofix && result.fix) {
+        console.log('\n' + formatAutofix(result.fix));
+    }
+});
+// autofix — show full auto-fix attempt detail (diff, dry-run, knowledge)
+scraps
+    .command('autofix <id>')
+    .description('Show the last auto-fix attempt for a scrap (decision, diff, dry-run, knowledge)')
+    .option('--json', 'Output raw autofix JSON')
+    .action(async (id, opts) => {
+    validateObjectId(id);
+    const result = await fetchRunAndFix(id);
+    if (!result) {
+        console.log(chalk.dim('No runs yet.'));
+        return;
+    }
+    if (!result.fix) {
+        console.log(chalk.dim('No auto-fix attempt on the last run.'));
+        return;
+    }
+    if (opts.json)
+        return json(result.fix);
+    console.log(formatAutofix(result.fix));
+});
+// snapshot — download the captured page HTML (or error-path HTML) for the last run
+scraps
+    .command('snapshot <id>')
+    .description('Download captured page HTML for the last run of a scrap')
+    .option('--error', 'Fetch the error-path snapshot (errorSnapshot.html)')
+    .option('-o, --out <file>', 'Write HTML to a file instead of stdout')
+    .action(async (id, opts) => {
+    validateObjectId(id);
+    const scrap = await api.get(`/api/scraps/${id}`);
+    const hid = scrap.history?.[0]?._id;
+    if (!hid) {
+        console.log(chalk.dim('No runs yet.'));
+        return;
+    }
+    const kindParam = opts.error ? '?kind=error' : '';
+    const html = await api.getText(`/api/historys/${hid}/html-snapshot${kindParam}`);
+    if (opts.out) {
+        const { writeFile } = await import('fs/promises');
+        await writeFile(opts.out, html, 'utf8');
+        console.log(chalk.green(`✓ Snapshot written to ${opts.out}`));
+    }
+    else {
+        process.stdout.write(html);
+    }
+});

package/dist/commands/token.d.ts

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

package/dist/commands/token.js

@@ -0,0 +1,57 @@
+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;
+    }
+}
+export const token = new Command('token')
+    .description('Print the stored session JWT (for MCP Bearer auth)')
+    .action(() => {
+    const stored = config.get('token');
+    if (!stored) {
+        console.error(chalk.red('✗ Not logged in. Run: trawl login'));
+        process.exitCode = 1;
+        return;
+    }
+    const exp = decodeExp(stored);
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    if (exp !== null && exp < nowSeconds) {
+        console.error(chalk.red('✗ Session token expired. Run: trawl login to refresh.'));
+        process.exitCode = 1;
+        return;
+    }
+    // Print the raw token first (so it can be piped / copied)
+    console.log(stored);
+    if (exp === null) {
+        // Could not decode expiry (malformed/opaque JWT) — advisory only, do not block piping
+        console.error(chalk.dim('  (could not decode expiry — verify the token manually)'));
+    }
+    else {
+        const secsLeft = exp - nowSeconds;
+        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.`));
+        }
+        else {
+            const daysRounded = Math.floor(daysLeft);
+            console.log(chalk.dim(`  Expires in ${daysRounded}d. Renew with: trawl login`));
+        }
+    }
+});

package/dist/index.js

@@ -8,6 +8,7 @@ import { login, logout } from './commands/login.js';
 import { scraps } from './commands/scraps.js';
 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();
@@ -38,6 +39,7 @@ program.addCommand(logout);
 program.addCommand(scraps);
 program.addCommand(skills);
 program.addCommand(telemetry);
+program.addCommand(token);
 process.on('exit', () => {
     void shutdown();
 });

package/dist/lib/api.d.ts

@@ -1,5 +1,6 @@
 export declare const api: {
     get: <T>(path: string) => Promise<T>;
+    getText: (path: string) => Promise<string>;
     post: <T>(path: string, body?: unknown) => Promise<T>;
     put: <T>(path: string, body?: unknown) => Promise<T>;
     delete: <T>(path: string) => Promise<T>;

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 from './config.js';
+import config, { getApiUrl } 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}`;
@@ -60,7 +60,7 @@ async function request(path, options = {}) {
     const token = config.get('token');
     if (!token)
         throw new Error('Not logged in. Run: trawl login');
-    const url = `${config.get('apiUrl')}${path}`;
+    const url = `${getApiUrl()}${path}`;
     const res = await fetch(url, {
         ...options,
         headers: {
@@ -90,7 +90,7 @@ async function upload(path, formData) {
     const token = config.get('token');
     if (!token)
         throw new Error('Not logged in. Run: trawl login');
-    const url = `${config.get('apiUrl')}${path}`;
+    const url = `${getApiUrl()}${path}`;
     // Do NOT set Content-Type — fetch sets it automatically with the correct multipart boundary
     const res = await fetch(url, {
         method: 'POST',
@@ -117,7 +117,7 @@ async function upload(path, formData) {
     }
 }
 async function publicPost(path, body) {
-    const url = `${config.get('apiUrl')}${path}`;
+    const url = `${getApiUrl()}${path}`;
     const res = await fetch(url, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json', 'User-Agent': USER_AGENT },
@@ -133,8 +133,23 @@ async function publicPost(path, body) {
         throw new Error('Invalid JSON in server response');
     }
 }
+async function getText(path) {
+    const token = config.get('token');
+    if (!token)
+        throw new Error('Not logged in. Run: trawl login');
+    const url = `${getApiUrl()}${path}`;
+    const res = await fetch(url, {
+        headers: {
+            'User-Agent': USER_AGENT,
+            Cookie: `TOKEN=${token}`,
+        },
+    });
+    await throwIfError(res);
+    return res.text();
+}
 export const api = {
     get: (path) => request(path),
+    getText: (path) => getText(path),
     post: (path, body) => request(path, {
         method: 'POST',
         body: body ? JSON.stringify(body) : undefined,
@@ -150,7 +165,7 @@ export const api = {
         const token = config.get('token');
         if (!token)
             throw new Error('Not logged in. Run: trawl login');
-        const url = `${config.get('apiUrl')}${path}`;
+        const url = `${getApiUrl()}${path}`;
         const res = await fetch(url, {
             headers: {
                 Accept: 'text/event-stream',

package/dist/lib/config.d.ts

@@ -6,4 +6,12 @@ interface TrawlConfig {
     telemetryUserId: string;
 }
 declare const config: Conf<TrawlConfig>;
+/**
+ * Resolve the effective API base URL.
+ * Precedence: TRAWL_API_URL env > stored `trawl login --url` > default.
+ * Mirrors the TRAWL_TOKEN / TRAWL_TELEMETRY session-override pattern so scripts
+ * (e.g. infra /trawl-prod-qa against https://dev.trawl.me) can retarget the CLI
+ * without mutating the operator's persisted config. (#56)
+ */
+export declare function getApiUrl(): string;
 export default config;

package/dist/lib/config.js

@@ -8,4 +8,15 @@ const config = new Conf({
         telemetryUserId: '',
     },
 });
+/**
+ * Resolve the effective API base URL.
+ * Precedence: TRAWL_API_URL env > stored `trawl login --url` > default.
+ * Mirrors the TRAWL_TOKEN / TRAWL_TELEMETRY session-override pattern so scripts
+ * (e.g. infra /trawl-prod-qa against https://dev.trawl.me) can retarget the CLI
+ * without mutating the operator's persisted config. (#56)
+ */
+export function getApiUrl() {
+    const override = process.env['TRAWL_API_URL']?.trim();
+    return override ? override : config.get('apiUrl');
+}
 export default config;

package/package.json

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