@trawlme/cli 1.20.0 → 1.22.0

package/dist/commands/skills.js

@@ -2,6 +2,7 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 import { listBundledSkills, installSkill, uninstallSkill, getBundledSkillsVersion, getInstalledVersion, isSkillInstalled, removeOrphanedSkills, } from '../lib/skills.js';
 import { UsageError } from '../lib/errors.js';
+import { json } from '../lib/format.js';
 function pickScope(opts) {
     return opts.local ? 'local' : 'user';
 }
@@ -20,14 +21,21 @@ export const skills = new Command('skills').description('Manage Claude Code skil
 skills
     .command('list')
     .description('List bundled skills and their installed status')
-    .action(() => {
+    .option('--json', 'Output as JSON')
+    .action((opts) => {
     const bundled = listBundledSkills();
+    const version = getBundledSkillsVersion();
     if (!bundled.length) {
+        if (opts.json) {
+            json({ version, skills: [] });
+            return;
+        }
         console.log(chalk.dim('No bundled skills.'));
         return;
     }
-    const version = getBundledSkillsVersion();
-    console.log(chalk.dim(`@trawlme/skills@${version}\n`));
+    if (!opts.json)
+        console.log(chalk.dim(`@trawlme/skills@${version}\n`));
+    const rows = [];
     for (const name of bundled) {
         const userInstalled = isSkillInstalled(name, 'user');
         const localInstalled = isSkillInstalled(name, 'local');
@@ -59,7 +67,16 @@ skills
                 installedVersion = null;
             }
         }
-        const stale = installedVersion && installedVersion !== version;
+        const stale = Boolean(installedVersion && installedVersion !== version);
+        if (opts.json) {
+            rows.push({
+                name,
+                installed: { user: userInstalled, local: localInstalled },
+                installedVersion,
+                outdated: stale,
+            });
+            continue;
+        }
         const tag = userInstalled
             ? localInstalled
                 ? '(user + local)'
@@ -70,46 +87,72 @@ skills
         const staleNote = stale ? chalk.yellow(` outdated: ${installedVersion} → ${version}`) : '';
         console.log(`  ${name} ${chalk.dim(tag)}${staleNote}`);
     }
+    if (opts.json)
+        json({ version, skills: rows });
 });
 skills
     .command('install [skill]')
     .description('Install one or all bundled skills')
     .option('--local', 'Install at project level (./.claude/skills) instead of user level (~/.claude/skills)')
     .option('--force', 'Overwrite a pre-existing dir even if trawl did not install it (no .version marker)')
+    .option('--json', 'Output as JSON')
     .action((skill, opts) => {
     const scope = pickScope(opts);
     const targets = pickSkills(skill);
+    const results = [];
     for (const name of targets) {
         const dest = installSkill(name, scope, { force: opts.force });
+        if (opts.json) {
+            results.push({ name, scope, dest });
+            continue;
+        }
         console.log(chalk.green(`✓ Installed "${name}"`) + chalk.dim(` at ${dest}`));
     }
+    if (opts.json) {
+        json({ installed: results });
+        return;
+    }
     console.log(chalk.dim('  Restart Claude Code if it was already running.'));
 });
 skills
     .command('uninstall [skill]')
     .description('Remove one or all bundled skills')
     .option('--local', 'Remove from project level (./.claude/skills)')
+    .option('--json', 'Output as JSON')
     .action((skill, opts) => {
     const scope = pickScope(opts);
     const targets = pickSkills(skill);
+    const results = [];
     for (const name of targets) {
         const dest = uninstallSkill(name, scope);
+        if (opts.json) {
+            results.push({ name, scope, dest, removed: dest !== null });
+            continue;
+        }
         if (dest)
             console.log(chalk.green(`✓ Removed "${name}"`) + chalk.dim(` from ${dest}`));
         else
             console.log(chalk.dim(`  No "${name}" found`));
     }
+    if (opts.json)
+        json({ uninstalled: results });
 });
 skills
     .command('update [skill]')
     .description('Reinstall over the existing skill (force sync with CLI version)')
     .option('--local', 'Update at project level')
     .option('--force', 'Overwrite a pre-existing dir even if trawl did not install it (no .version marker)')
+    .option('--json', 'Output as JSON')
     .action((skill, opts) => {
     const scope = pickScope(opts);
     const targets = pickSkills(skill);
+    const results = [];
     for (const name of targets) {
         const dest = installSkill(name, scope, { force: opts.force });
+        if (opts.json) {
+            results.push({ name, scope, dest });
+            continue;
+        }
         console.log(chalk.green(`✓ Updated "${name}"`) + chalk.dim(` at ${dest}`));
     }
     // #86 review — same orphan sweep as the startup auto-sync: an explicit
@@ -117,6 +160,9 @@ skills
     // or removed upstream (e.g. 1.0.0's `trawl` → 1.3.1's `trawl-cli`),
     // instead of leaving a stale ghost teaching outdated usage. Only the
     // scope being updated is swept; marker-less dirs are never touched.
-    // removeOrphanedSkills prints its own honest stderr line per removal.
-    removeOrphanedSkills(scope);
+    // removeOrphanedSkills prints its own honest stderr line per removal
+    // (stderr, so it's safe under --json too).
+    const orphansRemoved = removeOrphanedSkills(scope);
+    if (opts.json)
+        json({ updated: results, orphansRemoved });
 });

package/dist/commands/telemetry.js

@@ -2,33 +2,53 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 import config from '../lib/config.js';
 import { initPostHog } from '../lib/posthog.js';
+import { json } from '../lib/format.js';
 export const telemetry = new Command('telemetry').description('Manage CLI telemetry (usage data collection)');
 telemetry
     .command('on')
     .description('Enable telemetry (default)')
-    .action(() => {
+    .option('--json', 'Output as JSON')
+    .action((opts) => {
     config.set('telemetry', true);
     // Ensure a telemetryUserId is created on opt-in
     initPostHog();
+    if (opts.json) {
+        json({ telemetry: true });
+        return;
+    }
     console.log(chalk.green('✓ Telemetry enabled'));
     console.log(chalk.dim('  Anonymous usage data will be collected. Run `trawl telemetry status` to view.'));
 });
 telemetry
     .command('off')
     .description('Disable telemetry')
-    .action(() => {
+    .option('--json', 'Output as JSON')
+    .action((opts) => {
     config.set('telemetry', false);
+    if (opts.json) {
+        json({ telemetry: false });
+        return;
+    }
     console.log(chalk.green('✓ Telemetry disabled'));
     console.log(chalk.dim('  No data will be sent. Your telemetry ID is kept for if you re-enable later.'));
 });
 telemetry
     .command('status')
     .description('Show current telemetry state')
-    .action(() => {
+    .option('--json', 'Output as JSON')
+    .action((opts) => {
     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';
+    // The effective on/off state factoring in both env overrides — matches
+    // the human-mode "State:" line's own precedence (DO_NOT_TRACK >
+    // TRAWL_TELEMETRY > config).
+    const effectiveEnabled = enabled && !envOverride && !doNotTrack;
+    if (opts.json) {
+        json({ enabled: effectiveEnabled, configEnabled: enabled, telemetryUserId: config.get('telemetryUserId') || null, envOverride, doNotTrack });
+        return;
+    }
     console.log(chalk.bold('Telemetry status'));
     console.log(chalk.dim('  State:         ') +
         (doNotTrack

package/dist/commands/token.js

@@ -4,9 +4,11 @@ import { getToken } from '../lib/config.js';
 import { AuthError, notLoggedInError } from '../lib/api.js';
 import { reportError } from '../lib/errors.js';
 import { decodeExp } from '../lib/jwt.js';
+import { json } from '../lib/format.js';
 export const token = new Command('token')
     .description('Print the stored session JWT (for MCP Bearer auth)')
-    .action(() => {
+    .option('--json', 'Output as JSON ({token, exp, expiresAt}) instead of the raw JWT')
+    .action((opts) => {
     // getToken() resolves TRAWL_TOKEN env first, then the stored config
     // token (see config.ts:47-51) — matching every other token consumer in
     // the CLI instead of reading the config store directly. (#86 finding 1)
@@ -15,7 +17,7 @@ export const token = new Command('token')
         // Auth-classified (ApiError 401 → exit 3, kind:"auth"), not a generic
         // exit 1 — an agent scripting `trawl token` needs to tell "not logged
         // in" apart from an arbitrary bug. (#86 finding 1)
-        process.exitCode = reportError(notLoggedInError());
+        process.exitCode = reportError(notLoggedInError(), { json: opts.json });
         return;
     }
     const exp = decodeExp(stored);
@@ -24,7 +26,11 @@ export const token = new Command('token')
         // Decoded entirely client-side (no HTTP call made) — AuthError, not a
         // fabricated ApiError(401): the server never actually said this. (#88
         // item 4)
-        process.exitCode = reportError(new AuthError('Session token expired. Run: trawl login to refresh.'));
+        process.exitCode = reportError(new AuthError('Session token expired. Run: trawl login to refresh.'), { json: opts.json });
+        return;
+    }
+    if (opts.json) {
+        json({ token: stored, exp, expiresAt: exp !== null ? new Date(exp * 1000).toISOString() : null });
         return;
     }
     // Print the raw token first (so it can be piped / copied)

package/dist/index.d.ts

@@ -15,6 +15,14 @@ import { Command } from 'commander';
  * chain — matching the pre-existing convention that a direct child of the
  * root (e.g. `scraps list`, `telemetry on`) is named relative to its
  * immediate group, never prefixed with the program name.
+ *
+ * #108 note: promoting a verb to a top-level command (see `createProgram`
+ * below) renamed ITS resolved telemetry name from `scraps <verb>` to
+ * `<verb>` — the canonical top-level attach and the legacy hidden
+ * `scraps <verb>` attach are two separate Command instances (scraps.ts's
+ * double-attach factories), each with its own parent chain, so they
+ * resolve to two different names here even though they run the same
+ * handler. Intentional (the canonical command IS now `<verb>`), not a bug.
  */
 export declare function resolveCommandName(actionCommand: Command | undefined): string;
 /**

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 } from './commands/scraps.js';
+import { scraps, attachListCommand, attachGetCommand, attachRunCommand, attachDataCommand, attachHistoryCommand, attachRunInfoCommand, attachTriggerCommand, } from './commands/scraps.js';
 import { skills } from './commands/skills.js';
 import { telemetry } from './commands/telemetry.js';
 import { token } from './commands/token.js';
@@ -32,6 +32,14 @@ const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8
  * chain — matching the pre-existing convention that a direct child of the
  * root (e.g. `scraps list`, `telemetry on`) is named relative to its
  * immediate group, never prefixed with the program name.
+ *
+ * #108 note: promoting a verb to a top-level command (see `createProgram`
+ * below) renamed ITS resolved telemetry name from `scraps <verb>` to
+ * `<verb>` — the canonical top-level attach and the legacy hidden
+ * `scraps <verb>` attach are two separate Command instances (scraps.ts's
+ * double-attach factories), each with its own parent chain, so they
+ * resolve to two different names here even though they run the same
+ * handler. Intentional (the canonical command IS now `<verb>`), not a bug.
  */
 export function resolveCommandName(actionCommand) {
     if (!actionCommand)
@@ -63,21 +71,51 @@ export function collectCommandNames(root) {
     walk(root);
     return names;
 }
+/**
+ * #108 — surface reorg into two `trawl --help` tiers. Core verbs are
+ * agent+human, `--json` first-class, non-interactive; Management is the
+ * existing human/CI surface, kept but grouped so top-level help reads
+ * simple. Commander v14's native per-command help group (`.commandsGroup()`
+ * sets the default a subsequently-registered command inherits via
+ * `.helpGroup()`) drives the section headings — group ORDER in the printed
+ * help follows first-seen insertion order into `program.commands`, so every
+ * Core command is registered below before any Management one.
+ */
+const CORE_GROUP = 'Core commands (agent + human):';
+const MANAGEMENT_GROUP = 'Management commands (human/CI):';
 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);
+    // Core verbs (#108) — promoted/listed first: fetch, run, list, get, data,
+    // history, run-info, trigger, whoami, ping. `list`/`get`/`run`/`data`/
+    // `history`/`run-info`/`trigger` are built via scraps.ts's exported
+    // attachXCommand() factories — the SAME definition also stays wired
+    // (hidden) under `scraps` there, so every pre-#108 `trawl scraps <verb>`
+    // invocation keeps resolving (no breaking change).
+    program.commandsGroup(CORE_GROUP);
     program.addCommand(fetchUrl);
+    attachRunCommand(program);
+    attachListCommand(program);
+    attachGetCommand(program);
+    attachDataCommand(program);
+    attachHistoryCommand(program);
+    attachRunInfoCommand(program);
+    attachTriggerCommand(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.
+    program.commandsGroup(MANAGEMENT_GROUP);
+    program.addCommand(scraps);
+    program.addCommand(skills);
+    program.addCommand(login);
+    program.addCommand(logout);
+    program.addCommand(token);
+    program.addCommand(telemetry);
     return program;
 }
 /**

package/dist/lib/confirm.d.ts

@@ -0,0 +1,70 @@
+/**
+ * #107 — the machine contract's non-interactive rule, in one place. True only
+ * when a blocking interactive prompt is safe to show: NOT `--json` (a machine
+ * consumer needs pure stdout, and there's no human reading a prompt anyway)
+ * AND both stdin/stdout are real TTYs. A pipe/redirect/CI runner — including
+ * an agent driving this CLI as a subprocess — has nowhere for a human to type
+ * an answer; a blocking `readline` prompt in that situation hangs forever
+ * instead of ever returning.
+ */
+export declare function isInteractive(opts?: {
+    json?: boolean;
+}): boolean;
+export interface ConfirmOutcome {
+    /** True when the caller should proceed with the guarded action. */
+    proceed: boolean;
+    /**
+     * True when refused because the invocation is non-interactive (`--json`,
+     * or stdin/stdout isn't a real TTY) — a structured usage error has ALREADY
+     * been reported (the stderr line and/or the `--json` envelope) and
+     * `process.exitCode` set to 2. The caller must return immediately without
+     * printing anything else (mirrors every other `usageError()` call site).
+     */
+    blocked: boolean;
+}
+/**
+ * Shared guard for every destructive y/N confirmation in the CLI (`scraps
+ * delete`, `scraps account delete`, …). #107 — before this, each call site
+ * hand-rolled its own `readline` question with no non-interactive escape
+ * hatch, so a scripted/agent invocation with no `-f`/`--force` would hang
+ * forever waiting for a y/N answer that could never arrive.
+ *
+ * `-f`/`--force` (`opts.force`) always pre-confirms, interactive or not — the
+ * caller already gave explicit consent up front. Otherwise:
+ *  - Non-interactive (`--json`, or stdin/stdout isn't a real TTY): NEVER
+ *    prompts. Reports a structured usage error (exit 2) instead, via the same
+ *    central `reportError` formatting path every other error in this CLI
+ *    uses (stderr human line, or the `--json` envelope on stdout).
+ *  - Interactive: prompts via `readline` exactly like the pre-#107 call
+ *    sites did.
+ *
+ * `message` MUST be plain, unstyled text — it feeds both the refusal
+ * UsageError's message (human stderr line AND the `--json` error envelope on
+ * stdout) and the fallback prompt text. Before this, call sites passed a
+ * `chalk.bold(id)`-styled string as `message`, which leaked raw ANSI escape
+ * bytes into the `--json` envelope (e.g. `scraps delete X --json` on the
+ * refusal path emitted a message with the raw bold-on/off escape sequence
+ * wrapped around the id) — unusable for a script/agent parsing that string.
+ * `promptMessage` is the OPTIONAL styled variant shown only for the
+ * interactive TTY `[y/N]` prompt (chalk is safe there — no machine ever
+ * reads it); it defaults to `message` when omitted. (#107 review F2)
+ */
+export declare function confirmDestructive(message: string, opts?: {
+    force?: boolean;
+    json?: boolean;
+    promptMessage?: string;
+}): Promise<ConfirmOutcome>;
+/**
+ * Guard for a required interactive value that has no flag-supplied value yet
+ * (login's email prompt, …) — for call sites that propagate errors by
+ * `throw`ing and let the top-level handler in index.ts classify + report
+ * (login.ts's existing convention), as opposed to `scraps.ts`'s local
+ * exitCode-setting `usageError()` style (which should check `isInteractive`
+ * directly instead of using this). Same non-interactive contract as
+ * `confirmDestructive`: never invokes a blocking prompt when `--json` is set
+ * or stdin/stdout isn't a real TTY — throws a `UsageError` naming the flag to
+ * pass instead. (#107)
+ */
+export declare function requireInteractive(message: string, opts?: {
+    json?: boolean;
+}): void;

package/dist/lib/confirm.js

@@ -0,0 +1,79 @@
+import chalk from 'chalk';
+import { UsageError } from './errors.js';
+import { reportError } from './errors.js';
+/**
+ * #107 — the machine contract's non-interactive rule, in one place. True only
+ * when a blocking interactive prompt is safe to show: NOT `--json` (a machine
+ * consumer needs pure stdout, and there's no human reading a prompt anyway)
+ * AND both stdin/stdout are real TTYs. A pipe/redirect/CI runner — including
+ * an agent driving this CLI as a subprocess — has nowhere for a human to type
+ * an answer; a blocking `readline` prompt in that situation hangs forever
+ * instead of ever returning.
+ */
+export function isInteractive(opts = {}) {
+    if (opts.json)
+        return false;
+    return Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
+}
+/**
+ * Shared guard for every destructive y/N confirmation in the CLI (`scraps
+ * delete`, `scraps account delete`, …). #107 — before this, each call site
+ * hand-rolled its own `readline` question with no non-interactive escape
+ * hatch, so a scripted/agent invocation with no `-f`/`--force` would hang
+ * forever waiting for a y/N answer that could never arrive.
+ *
+ * `-f`/`--force` (`opts.force`) always pre-confirms, interactive or not — the
+ * caller already gave explicit consent up front. Otherwise:
+ *  - Non-interactive (`--json`, or stdin/stdout isn't a real TTY): NEVER
+ *    prompts. Reports a structured usage error (exit 2) instead, via the same
+ *    central `reportError` formatting path every other error in this CLI
+ *    uses (stderr human line, or the `--json` envelope on stdout).
+ *  - Interactive: prompts via `readline` exactly like the pre-#107 call
+ *    sites did.
+ *
+ * `message` MUST be plain, unstyled text — it feeds both the refusal
+ * UsageError's message (human stderr line AND the `--json` error envelope on
+ * stdout) and the fallback prompt text. Before this, call sites passed a
+ * `chalk.bold(id)`-styled string as `message`, which leaked raw ANSI escape
+ * bytes into the `--json` envelope (e.g. `scraps delete X --json` on the
+ * refusal path emitted a message with the raw bold-on/off escape sequence
+ * wrapped around the id) — unusable for a script/agent parsing that string.
+ * `promptMessage` is the OPTIONAL styled variant shown only for the
+ * interactive TTY `[y/N]` prompt (chalk is safe there — no machine ever
+ * reads it); it defaults to `message` when omitted. (#107 review F2)
+ */
+export async function confirmDestructive(message, opts = {}) {
+    if (opts.force)
+        return { proceed: true, blocked: false };
+    if (!isInteractive(opts)) {
+        process.exitCode = reportError(new UsageError(`${message} requires confirmation — refusing to block on a prompt (non-interactive). Pass -f/--force to confirm.`), { json: opts.json });
+        return { proceed: false, blocked: true };
+    }
+    const { createInterface } = await import('readline');
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await new Promise((resolve) => {
+            rl.question(`${opts.promptMessage ?? message} ${chalk.dim('[y/N]')} `, (a) => resolve(a.trim().toLowerCase()));
+        });
+        return { proceed: answer === 'y' || answer === 'yes', blocked: false };
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * Guard for a required interactive value that has no flag-supplied value yet
+ * (login's email prompt, …) — for call sites that propagate errors by
+ * `throw`ing and let the top-level handler in index.ts classify + report
+ * (login.ts's existing convention), as opposed to `scraps.ts`'s local
+ * exitCode-setting `usageError()` style (which should check `isInteractive`
+ * directly instead of using this). Same non-interactive contract as
+ * `confirmDestructive`: never invokes a blocking prompt when `--json` is set
+ * or stdin/stdout isn't a real TTY — throws a `UsageError` naming the flag to
+ * pass instead. (#107)
+ */
+export function requireInteractive(message, opts = {}) {
+    if (!isInteractive(opts)) {
+        throw new UsageError(message);
+    }
+}

package/dist/lib/errors.d.ts

@@ -8,6 +8,19 @@
 export declare class UsageError extends Error {
     constructor(message: string);
 }
+/**
+ * Thrown for a business-logic REFUSAL the server explicitly reported back
+ * (e.g. a tier-ceiling override the registry cap rejected) — distinct from
+ * an arbitrary unmapped bug. Before this, `reportTierRefusal` routed a bare
+ * `new Error(message)` through here, which fell through to the generic
+ * `kind:"unknown"` bucket — indistinguishable from a genuine crash, even
+ * though the README sells `kind` as the machine discriminant an agent
+ * branches on. Same exit code (1: a business-logic refusal, not a usage
+ * error) as before — only the `kind` differs. (#107 review F3)
+ */
+export declare class RefusalError extends Error {
+    constructor(message: string);
+}
 export interface ErrorEnvelope {
     message: string;
     status?: number;

package/dist/lib/errors.js

@@ -13,6 +13,22 @@ export class UsageError extends Error {
         this.name = 'UsageError';
     }
 }
+/**
+ * Thrown for a business-logic REFUSAL the server explicitly reported back
+ * (e.g. a tier-ceiling override the registry cap rejected) — distinct from
+ * an arbitrary unmapped bug. Before this, `reportTierRefusal` routed a bare
+ * `new Error(message)` through here, which fell through to the generic
+ * `kind:"unknown"` bucket — indistinguishable from a genuine crash, even
+ * though the README sells `kind` as the machine discriminant an agent
+ * branches on. Same exit code (1: a business-logic refusal, not a usage
+ * error) as before — only the `kind` differs. (#107 review F3)
+ */
+export class RefusalError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RefusalError';
+    }
+}
 /**
  * Central status → exit-code map (#71 findings 13/14/60). Agents driving this
  * CLI unattended need to tell "you're not logged in" (3) from "that id
@@ -43,6 +59,9 @@ export function classifyError(err) {
     if (err instanceof UsageError) {
         return { exitCode: 2, envelope: { message, kind: 'usage' } };
     }
+    if (err instanceof RefusalError) {
+        return { exitCode: 1, envelope: { message, kind: 'refused' } };
+    }
     return { exitCode: 1, envelope: { message, kind: 'unknown' } };
 }
 /**

package/docs/agent-quickstart.md

@@ -0,0 +1,103 @@
+# Trawl CLI — Agent Quickstart
+
+The minimal surface an AI agent needs to drive `@trawlme/cli` non-interactively.
+For the full command reference (management surface, Claude Code skills,
+telemetry, etc.) see the [main README](../README.md) — the human/CI guide.
+
+## Auth — zero prompts
+
+Set `TRAWL_TOKEN` and every command authenticates without ever touching a
+prompt:
+
+```bash
+export TRAWL_TOKEN=<jwt>
+trawl whoami --json
+```
+
+(Interactive `trawl login` and the `--url`/config-file flow are documented in
+the README's [Authentication](../README.md#authentication) section — an
+agent should never need them.)
+
+## Core commands (agent + human)
+
+These ten commands are the CLI's agent+human surface — `--json` is
+first-class on every one, and none of them ever blocks on a prompt (see
+[Non-interactive contract](#non-interactive-contract) below):
+
+```
+trawl fetch <url> [--json] [--reason <text>]   One-shot fetch + extract readable content from a public URL (no scrap needed)
+trawl run <id> [--watch] [--json]              Run a scrap
+trawl list|ls [--json] [--status <s>] [--limit <n>] [--page <n>]   List all scraps
+trawl get <id> [--json]                        Get scrap details
+trawl data <id> [--json] [--fresh] [--errors]  Get scrap data (last persisted run, or --fresh to launch one)
+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 whoami [--json]                          Show the authenticated user's identity
+trawl ping [--json]                            Health/version handshake against the Trawl API
+```
+
+`trawl fetch` is the one command with no persisted scrap behind it — a
+one-shot fetch + extract for any public URL, the closest primitive to
+"just get me this page's content." It's the REST counterpart of the MCP
+`trawl_fetch_url` tool (same shared engine): `status` is an honest outcome
+(`completed`/`failed`/`empty`/`blocked`), not "did the HTTP call succeed" — a
+failed fetch is still a 200 response with `status:'failed'` + `error`, and
+the CLI exits `1` in that case even though `--json` always prints the raw
+payload verbatim.
+
+> **No breaking change:** every verb above is also still reachable under its
+> pre-reorg path, `trawl scraps <verb>` (e.g. `trawl scraps list`) — kept as
+> 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 `create`/`update`, 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.
+
+## `--json` contract
+
+Every command above supports `--json`: a single structured payload on
+stdout, nothing else. Two narrow exceptions carried over from the human
+surface: a `--watch` poll emits exactly one final NDJSON line once the run
+reaches a terminal state (not the whole progress stream), and there is no
+JSON form of an HTML page (irrelevant to the core verbs above — that only
+applies to the management-only `scraps snapshot`).
+
+On failure, `--json` emits a single error envelope on stdout instead of
+prose — `{"error":{"message","status?","kind"}}` — and the human-readable
+line goes to stderr, never stdout. `kind` is the machine-readable
+discriminant (`"usage"`/`"auth"`/`"not_found"`/`"network"`/`"api"`/
+`"refused"`/`"unknown"`) a script should switch on.
+
+## Non-interactive contract
+
+No core verb ever blocks waiting for a prompt. When stdin/stdout isn't a
+real TTY (any subprocess-driven invocation) — or `--json` is set — any
+command that would otherwise ask a `[y/N]` confirmation or a missing value
+instead fails fast with a structured usage error (exit `2`) rather than
+hanging. Full rule + rationale: README's
+[Non-interactive rule](../README.md#non-interactive-rule).
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0`  | Success |
+| `1`  | Unknown/generic error, or a business-logic outcome (e.g. `fetch`'s honest `status:'failed'`/`'blocked'`, `data`'s `run_failed`/`in_progress`) |
+| `2`  | Usage error (bad flag/value, invalid ID, missing required argument, or the non-interactive guard refusing to prompt) |
+| `3`  | Auth error (not logged in, or the session token is expired/invalid) |
+| `4`  | Not found (no such resource, or no persisted payload to read) |
+| `5`  | Network error (API host unreachable, DNS/connection/TLS failure, or timeout) |
+
+This table is the stable contract; per-command nuance and overloads (e.g.
+`fetch`'s domain-level failure sharing exit `1` with an unmapped bug) are
+documented once, in the README's [Exit codes](../README.md#exit-codes)
+section — treat that as canonical if the two ever seem to disagree.
+
+## Minimal example
+
+```bash
+TRAWL_TOKEN=<jwt> trawl fetch https://example.com --json
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trawlme/cli",
-  "version": "1.20.0",
+  "version": "1.22.0",
   "description": "Trawl CLI — manage scraps from the terminal",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "dist",
+    "docs",
     "README.md",
     "LICENSE"
   ],