@trawlme/cli 1.19.1 → 1.21.0

package/README.md

@@ -28,16 +28,28 @@ 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.
+All commands accept a global `--debug` flag to show full error stack traces on failure. Every command below supports `--json` (a raw payload / structured result on stdout, nothing else) and never blocks on an interactive prompt when `--json` is set or stdin/stdout isn't a real TTY — see [Non-interactive rule](#non-interactive-rule) and [Exit codes](#exit-codes). Two documented exceptions to "single payload": `scraps watch --json` is a live stream, so it emits NDJSON (one JSON object per line) instead; `scraps snapshot --json` only changes behavior on a never-run scrap (`{"status":"no_runs"}`) — when a run exists it still writes the raw HTML snapshot regardless of `--json` (there's no JSON-encoded form of an HTML page to emit).
 
 ### Auth
 
 ```
-trawl login [--url <url>] [--token <jwt>] [--email <email>] [--password <pass>]
-trawl logout
-trawl token                                  Print the stored session JWT (for MCP Bearer auth)
+trawl login [--url <url>] [--token <jwt>] [--email <email>] [--password <pass>] [--json]
+trawl logout [--json]
+trawl token [--json]                         Print the stored session JWT (for MCP Bearer auth)
 ```
 
+`login --json` prints `{"ok":true,"apiUrl","config",email?}` on success — never the raw token (that's `token`'s job). `token --json` prints `{"token","exp","expiresAt"}` instead of the bare JWT + stderr advisories. See [Non-interactive rule](#non-interactive-rule) below: a missing `--email`/`--password` refuses immediately (usage error, exit 2) instead of prompting when `--json` is set or stdin/stdout isn't a real TTY.
+
+### Agent core verbs
+
+```
+trawl fetch <url> [--json] [--reason <text>]  One-shot fetch + extract readable content from a public URL (no scrap needed)
+trawl whoami [--json]                         Show the authenticated user's identity
+trawl ping [--json]                           Health/version handshake against the Trawl API
+```
+
+Fully non-interactive — all three read auth only from `TRAWL_TOKEN`/the stored login token, never prompt. `trawl fetch` is the REST counterpart of the MCP `trawl_fetch_url` tool (same shared engine, `POST /api/scraps/fetch-url`): `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 (both human and `--json` modes) even though `--json` always prints the raw payload verbatim. `truncated:true` means the 100KB response cap tripped; `result` is dropped and `url` repoints at the full history row instead. `trawl whoami`/`trawl ping` mirror the MCP `trawl_whoami`/`trawl_health_ping` tools as closely as the REST surface allows (`GET /api/users/me` / `GET /api/health`) — `ping`'s `--json` payload is admin-enriched (version/uptime/db) and just `{"status":"ok"}` for anyone else.
+
 ### Scraps
 
 ```
@@ -45,20 +57,20 @@ trawl scraps list [--json] [--status <success|failure|never|running|regression>]
 trawl scraps get <id> [--json]
 trawl scraps create -t <title> [-u <url>] [-r <request>] [-d <description>] [--tier <tier0|tier1|tier2|tier3|tier4>] [--json]
 trawl scraps update <id> [-t <title>] [-u <url>] [-r <request>] [-d <description>] [--cron <expr>|--no-cron] [--alert <email>|--no-alert] [--autofix|--no-autofix] [-p <json>|--params-file <path>] [--tier <tier0|tier1|tier2|tier3|tier4>] [--force-tier <tier0|tier1|tier2|tier3|tier4>] [--json]
-trawl scraps run <id> [--watch]
-trawl scraps trigger <id> [--watch] [--wait]
-trawl scraps watch <id>
+trawl scraps run <id> [--watch] [--json]
+trawl scraps trigger <id> [--watch] [--wait] [--json]
+trawl scraps watch <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>] [--json]
-trawl scraps banner <id> -f <file>
-trawl scraps delete <id> [--force]         Alias: rm
+trawl scraps banner <id> -f <file> [--json]
+trawl scraps delete <id> [--force] [--json]         Alias: rm
 ```
 
-- `--tier` forces a proxy tier; `--force-tier` raises the proxy-tier ceiling past the auto-cap (history-gated: may be refused or cost more). `create --json`/`update --json` print the full scrap object (including the `_tierOverride` outcome) on stdout; a refused tier override exits 1 with a standard `--json` error envelope. When a tier was requested but the server's response carries no `_tierOverride` at all (an older server that can't confirm what actually got applied), a stderr warning is printed either way, and under `--json` the emitted object also carries `"_tierUnconfirmed": true` — the machine-readable counterpart to that warning, since a `--json` caller has no reliable reason to read stderr.
+- `--tier` forces a proxy tier; `--force-tier` raises the proxy-tier ceiling past the auto-cap (history-gated: may be refused or cost more). `create --json`/`update --json` print the full scrap object (including the `_tierOverride` outcome) on stdout; a refused tier override exits 1 with a standard `--json` error envelope (`kind:"refused"` — distinct from `"unknown"`, so a script can branch on "the server said no"). When a tier was requested but the server's response carries no `_tierOverride` at all (an older server that can't confirm what actually got applied), a stderr warning is printed either way, and under `--json` the emitted object also carries `"_tierUnconfirmed": true` — the machine-readable counterpart to that warning, since a `--json` caller has no reliable reason to read stderr.
 - `scraps doctor` diagnoses the last run (error, failed selector, block status, page state, autofix outcome); `--autofix` includes the full autofix diff/dry-run/knowledge. A run that is still in flight (`status: null`, server-side) shows a `running` badge, never `failed`; a run whose item count regressed vs baseline (`statusDetail: "regression"`) shows its own amber `regression` badge, never `failed` either (`scraps list`/`get` show the same distinction — a `▼` icon, not the red `✗` a genuine failure gets).
 - `scraps autofix` shows the last auto-fix attempt on its own (decision, diff, dry-run, knowledge). `--json` on a scrap that has **never run** returns `{"status":"no_runs"}` (exit 0) — distinct from `null`, which means a run exists but had no auto-fix attempt.
 - `scraps snapshot --error` fetches the error-path snapshot instead of the normal one; `-o <file>` writes to a file instead of stdout. On a scrap that has **never run**: `--json` returns `{"status":"no_runs"}` (exit 0), matching `doctor`/`autofix`; `-o <file>` (without `--json`) exits 4 (`not_found`) instead of silently exiting 0 with nothing written — a script checking the exit code alone must be able to tell "no file was produced" from success. `--json` takes priority when both are passed.
@@ -67,31 +79,34 @@ trawl scraps delete <id> [--force]         Alias: rm
 - `scraps get` (and anything reading through it, like `scraps data`'s default path) embeds only the newest 100 history rows on the returned scrap object — `scraps run-info` and `scraps doctor` fetch a single run directly and are unaffected by that cap.
 - `scraps banner -f <file>` only accepts `png`/`jpg`/`jpeg`/`webp`; any other extension is a usage error (exit 2) instead of silently uploading the file under a fabricated `image/png` Content-Type.
 - **Long-running scrap execute (`scraps run`, `data --fresh`, `trigger --wait`):** these hit the same server-side scrap-execute path, which can legitimately take 30–250s (proxy tier escalation, AI-fix retries) — the CLI arms a 300s timeout for exactly these three call sites instead of the generic 30s default. `TRAWL_TIMEOUT` (see below) still overrides ALL requests, including these — set it if you need a tighter or looser ceiling than 300s for a long-running scrap.
-- **`--watch` is poll-based, not a live stream:** the activities SSE endpoint has no backlog and, for the default async `trigger` (no `--wait`), runs in a separate cron-consumer pod whose events never reach the API pod holding the SSE connection — a naive "await the run, then open SSE" shows nothing. `scraps run --watch` and `scraps trigger --watch` instead poll `GET /api/scraps/:id` (terminal status) and the activities REST list until the run finishes, printing each new activity line as it appears; a run that never reaches a terminal status within 300s prints an honest timeout notice pointing at `scraps doctor <id>`. `scraps watch <id>` (the standalone command, no trigger) is unchanged — it still opens the live SSE stream directly.
+- **`--watch` is poll-based, not a live stream:** the activities SSE endpoint has no backlog and, for the default async `trigger` (no `--wait`), runs in a separate cron-consumer pod whose events never reach the API pod holding the SSE connection — a naive "await the run, then open SSE" shows nothing. `scraps run --watch` and `scraps trigger --watch` instead poll `GET /api/scraps/:id` (terminal status) and the activities REST list until the run finishes, printing each new activity line as it appears. The watched run's outcome drives the exit code too, in BOTH human and `--json` mode: a genuinely failed terminal run, a poll timeout, or a persistently unreachable API all exit non-zero — a clean successful run is the only exit `0`. A run that never reaches a terminal status within 300s prints an honest timeout notice pointing at `scraps doctor <id>` (human mode) — see the `--json` shape below. `scraps watch <id>` (the standalone command, no trigger) is unchanged — it still opens the live SSE stream directly.
+- `scraps run --json`/`trigger --json` bypass the spinner and print the raw launch/trigger payload on stdout; combined with `--watch`, every intermediate progress line stays suppressed (stdout stays pure JSON) and, once the watch reaches its outcome, exactly ONE final NDJSON line is emitted: `{"runId","status"}` (the honest terminal status — `success`/`error`/`empty`/`regression`/…), `{"runId","status":"timeout"}` on a poll timeout, or `{"runId","status":"poll_error","error"}` if the API stays unreachable for several consecutive polls — `process.exitCode` is non-zero for all three except a genuine success. `scraps watch --json` emits one raw JSON object per activity line (NDJSON) instead of the formatted `[time] message` text — there's no single final payload to wait for on a live stream. `scraps delete`/`banner --json` print `{"deleted":true,"id"}` / the raw upload response.
 
 ### Scrap accounts
 
 ```
-trawl scraps account set <id> [-u <username>] [-p <password>]
-trawl scraps account delete <id> [--force]
-trawl scraps account clear-session <id>
+trawl scraps account set <id> [-u <username>] [-p <password>] [--json]
+trawl scraps account delete <id> [--force] [--json]
+trawl scraps account clear-session <id> [--json]
 trawl scraps account status <id> [--json]
-trawl scraps account session set <id> -c <file>
+trawl scraps account session set <id> -c <file> [--json]
 ```
 
-`account session set` uploads a Puppeteer cookie JSON array to bootstrap a logged-in session without storing credentials (BYO-cookies).
+`account session set` uploads a Puppeteer cookie JSON array to bootstrap a logged-in session without storing credentials (BYO-cookies). A missing `-u/--username`/`-p/--password` on `account set` follows the same [non-interactive rule](#non-interactive-rule) as `login`.
 
 ### Claude Code skills
 
 The CLI bundles 5 Claude Code skills that teach Claude how to use `trawl`. Once installed, Claude can manage scraps for you via prompts.
 
 ```
-trawl skills list                                     List bundled skills and install status
-trawl skills install [<skill>] [--local] [--force]    Install all (or one). Default: ~/.claude/skills/
-trawl skills uninstall [<skill>] [--local]            Remove
-trawl skills update [<skill>] [--local] [--force]     Reinstall (force sync with CLI version)
+trawl skills list [--json]                                     List bundled skills and install status
+trawl skills install [<skill>] [--local] [--force] [--json]    Install all (or one). Default: ~/.claude/skills/
+trawl skills uninstall [<skill>] [--local] [--json]            Remove
+trawl skills update [<skill>] [--local] [--force] [--json]     Reinstall (force sync with CLI version)
 ```
 
+`--json` prints a structured result (`{"version","skills":[...]}` for `list`; `{"installed"/"uninstalled"/"updated":[{"name","scope","dest"}]}` for the others) instead of the `✓`-prefixed lines — the orphan-sweep/re-sync stderr lines are unaffected either way (stdout stays pure).
+
 Skills auto-update when you upgrade the CLI — no need to re-install manually — but it is not silent: it prints an honest `trawl: re-synced skill "<name>" (<scope>) <old> → <new>` line to stderr whenever it rewrites a skill dir, so a rewrite is never invisible. If a bundled skill is renamed or dropped between CLI versions, the old install is swept too — a `trawl: removed orphaned skill "<name>" (<scope>) — no longer bundled with this CLI version` line to stderr, so a stale skill teaching outdated CLI usage never lingers silently. Only marker-owned dirs (installed by trawl itself) are ever touched by either line. Opt out with `TRAWL_SKILLS_SYNC=0`.
 
 A pre-existing skill directory that trawl did not install itself (no `.version` marker) is never touched — `install`/`update` refuse to overwrite it and require `--force` to proceed. This applies to the CLI-upgrade auto-sync too (it silently skips marker-less dirs rather than refusing, since there is no interactive user to show a refusal to).
@@ -101,9 +116,9 @@ You can also install skills standalone (without the CLI): `npx @trawlme/skills i
 ### Telemetry
 
 ```
-trawl telemetry on       Enable usage telemetry (default)
-trawl telemetry off      Disable usage telemetry
-trawl telemetry status   Show current state, telemetry ID, and opt-out instructions
+trawl telemetry on [--json]       Enable usage telemetry (default)
+trawl telemetry off [--json]      Disable usage telemetry
+trawl telemetry status [--json]   Show current state, telemetry ID, and opt-out instructions
 ```
 
 ## Telemetry
@@ -139,6 +154,15 @@ TRAWL_TELEMETRY=0 trawl scraps list
 
 **Why:** usage data helps us prioritise CLI features and catch silent errors before users report them.
 
+## Non-interactive rule
+
+Every command that would otherwise block on a `readline` prompt (a destructive-action `[y/N]` confirmation, or a required value like `login`'s email/password) follows the same rule: when `--json` is set, **or** stdin/stdout isn't a real TTY (a pipe, a CI runner, an agent driving this CLI as a subprocess), it **never prompts** — it reports a structured usage error (exit `2`) instead of hanging forever waiting for an answer that can't arrive.
+
+- **Confirmations** (`scraps delete`/`rm`, `scraps account delete`): pass `-f`/`--force` to pre-confirm and skip the prompt entirely, interactive or not.
+- **Required values with no flag equivalent for "skip"** (`login`'s email/password, `scraps account set`'s username/password): pass the flag (`-e`/`-p`, `-u`/`-p`) or set `TRAWL_TOKEN`, instead of relying on the prompt.
+- The guard is a hard gate, not a timeout — an agent-spawned subprocess with an open-but-idle stdin (common when a harness doesn't explicitly close it) would otherwise hang indefinitely; this refuses immediately instead.
+- **Behavior change:** a piped `y` (e.g. `echo y | trawl scraps delete <id>`) no longer confirms the deletion. Piped stdin isn't a real TTY, so this now hits the same non-interactive refusal as any other scripted invocation (exit `2`, fail-closed) instead of silently proceeding on whatever text happened to be piped in. Existing scripts that relied on `echo y | …` must pass `-f`/`--force` instead.
+
 ## Exit codes
 
 Every command exits with one of these codes — scripts and agents driving the CLI unattended can branch on the exact failure kind instead of a uniform pass/fail:
@@ -146,13 +170,13 @@ Every command exits with one of these codes — scripts and agents driving the C
 | Code | Meaning                                                                 |
 |------|--------------------------------------------------------------------------|
 | `0`  | Success                                                                 |
-| `1`  | Unknown/generic error (an unmapped failure — API errors other than 401/404, an unhandled bug — or a business-logic refusal like `scraps data`'s `run_failed`/`in_progress` states) |
-| `2`  | Usage error (bad flag/value, invalid ID, missing required argument, unknown option/command) |
+| `1`  | Unknown/generic error (an unmapped failure — API errors other than 401/404, an unhandled bug — or a business-logic refusal like `scraps data`'s `run_failed`/`in_progress` states, or `trawl fetch`'s honest `status:'failed'`/`'blocked'` outcome). **Known overload:** `fetch`'s domain-level failure and an arbitrary unmapped bug both land on `1` — a script needs to read the `--json` payload's own `status`/`error` field (for `fetch`) to tell them apart; this is intentional (the REST contract's outcome states are a separate axis from the CLI's transport-error taxonomy) and documented here rather than "resolved" by inventing a new code that would only apply to one command. |
+| `2`  | Usage error (bad flag/value, invalid ID, missing required argument, unknown option/command — including the [non-interactive rule](#non-interactive-rule) refusing to prompt) |
 | `3`  | Auth error (not logged in, or the session token is expired/invalid — run `trawl login`) |
 | `4`  | Not found (no such resource, or — for `scraps data` — no persisted payload to read) |
 | `5`  | Network error (the API host is unreachable, DNS/connection/TLS failure, or the request timed out) |
 
-Under `--json`, a failing command emits a single error envelope on stdout — `{"error":{"message","status?","kind"}}` — instead of prose; the human-readable line always goes to stderr, never stdout.
+Under `--json`, a failing command emits a single error envelope on stdout — `{"error":{"message","status?","kind"}}` — instead of prose; the human-readable line always goes to stderr, never stdout. `kind` is the machine-readable discriminant (`"usage"`/`"auth"`/`"not_found"`/`"network"`/`"api"`/`"refused"`/`"unknown"`/…) — the short string a script should switch on (`"refused"` is a business-logic refusal the server explicitly reported back, e.g. `scraps create|update`'s tier-ceiling override rejection — distinct from `"unknown"`, which stays reserved for an unmapped bug); `status` is present only when a real HTTP response carried one (never fabricated for a local failure like an expired-locally JWT or a refused confirmation prompt).
 
 ## Environment variables
 

package/dist/commands/fetch.d.ts

@@ -0,0 +1,31 @@
+import { Command } from 'commander';
+/**
+ * `POST /api/scraps/fetch-url` response contract (#1697, trawl_node —
+ * shipped, contract LOCKED). REST counterpart of the MCP `trawl_fetch_url`
+ * tool: both run through the same shared engine
+ * (scraps.fetchUrl.service.js#runEphemeralUrlFetch), so the outcome shape is
+ * identical regardless of transport.
+ *
+ *  - `status`: 'completed' | 'failed' | 'empty' | 'blocked' — an HONEST
+ *    outcome, not a bare "it ran". A failed/blocked/empty run is still a
+ *    200 response (this is not an HTTP error), so callers must branch on
+ *    `status`, never assume 2xx means "got data".
+ *  - `error` is present ONLY when `status === 'failed'`.
+ *  - `truncated: true` when the 100KB response-payload cap tripped — the
+ *    server drops `result` in that case and repoints `url` at the full
+ *    history row (`/api/historys/:runId`) instead of echoing the fetched
+ *    target.
+ */
+export interface FetchUrlResponse {
+    url: string;
+    status: 'completed' | 'failed' | 'empty' | 'blocked';
+    runId?: string | null;
+    statusDetail?: string | null;
+    blocked?: boolean;
+    length?: number | null;
+    result?: unknown;
+    truncated?: boolean;
+    reason?: string;
+    error?: string;
+}
+export declare const fetchUrl: Command;

package/dist/commands/fetch.js

@@ -0,0 +1,95 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { oraPromise } from 'ora';
+import { api, LONG_RUN_TIMEOUT_MS } from '../lib/api.js';
+import { json } from '../lib/format.js';
+import { requireUrl } from '../lib/validate.js';
+function statusIcon(status) {
+    if (status === 'completed')
+        return chalk.green('✓');
+    if (status === 'failed')
+        return chalk.red('✗');
+    if (status === 'blocked')
+        return chalk.yellow('⚠');
+    return chalk.dim('•'); // empty
+}
+/** Best-effort human summary of `result` — same "count + first-item keys"
+ * shape scraps.ts's renderScrapItems uses, never a full dump (that's what
+ * --json is for). */
+function renderResultSummary(result) {
+    if (!Array.isArray(result))
+        return;
+    console.log(chalk.dim(`  Items:      `) + result.length);
+    const first = result[0];
+    if (result.length > 0 && first && typeof first === 'object') {
+        console.log(chalk.dim(`  First keys: `) + Object.keys(first).join(', '));
+    }
+}
+export const fetchUrl = new Command('fetch')
+    .description('One-shot fetch + extract readable content from a public URL (no scrap needed)')
+    .argument('<url>', 'Target public HTTPS URL')
+    .option('--json', 'Output the raw API payload')
+    .option('--reason <reason>', 'Audit-trail reason for this fetch (logged server-side, max 500 chars)')
+    .action(async (rawUrl, opts) => {
+    // Fast, local usage-error (exit 2) on an obviously malformed URL — never
+    // a round-trip to the server for something we can already tell is bad.
+    // The server still re-validates (SSRF guard) — this is a UX fast-path,
+    // not a security boundary.
+    const url = requireUrl(rawUrl, 'url');
+    const body = {
+        url,
+        ...(opts.reason !== undefined && { reason: opts.reason }),
+    };
+    // #106 review F1 — this endpoint runs the FULL worker pipeline (browser
+    // `goto` networkidle2 + extraction + persistence), legitimately 30-250s
+    // server-side — same #91 P0 pattern as `scraps run` / `data --fresh` /
+    // `trigger --wait` (src/commands/scraps.ts). The 30s DEFAULT_TIMEOUT_MS
+    // was aborting it mid-flight and would have surfaced a fabricated
+    // NetworkError timeout for a request that was always going to succeed.
+    const call = () => api.post('/api/scraps/fetch-url', body, { timeoutMs: LONG_RUN_TIMEOUT_MS });
+    // #106 review F2 — under --json the stdout path must be provably pure:
+    // no spinner channel at all. Only the human path gets the ora progress
+    // indicator; --json calls the API directly.
+    const data = opts.json
+        ? await call()
+        : await oraPromise(call, {
+            text: `Fetching ${url}…`,
+            // #106 review F3 — no successText verdict here. ora's success
+            // symbol only means "the HTTP call didn't throw", not "the fetch
+            // succeeded" — a failed/blocked domain `status` is still a 200
+            // response. The real outcome is rendered below via statusIcon +
+            // the Status: line; a green check here would contradict a
+            // red/yellow icon printed right after it.
+            successText: 'Request complete',
+        });
+    if (opts.json) {
+        json(data);
+    }
+    else {
+        console.log(`${statusIcon(data.status)} ${chalk.bold(data.url)}`);
+        console.log(chalk.dim(`  Status:     `) + data.status);
+        if (data.runId)
+            console.log(chalk.dim(`  Run ID:     `) + data.runId);
+        if (data.statusDetail)
+            console.log(chalk.dim(`  Detail:     `) + data.statusDetail);
+        if (data.length != null)
+            console.log(chalk.dim(`  Length:     `) + data.length);
+        if (data.truncated) {
+            console.log(chalk.yellow(`  ⚠ Truncated (payload too large) — full result: ${data.url}`));
+        }
+        if (data.status === 'failed' && data.error) {
+            console.log(chalk.red(`  Error:      `) + data.error);
+        }
+        renderResultSummary(data.result);
+    }
+    // Honest exit code alongside the honest payload — a --json caller gets
+    // the raw body regardless (never wrapped/altered), but a script checking
+    // the exit code alone must be able to tell "no usable data" from "ran
+    // fine" without parsing. `blocked` (#106 review F4 — an antibot wall) is
+    // a failure to get data exactly like `failed`: an agent scripting
+    // `trawl fetch ... || handle` must see non-zero for either. `empty`
+    // stays 0 on purpose — the fetch genuinely ran to completion, there was
+    // just nothing extractable at that URL; that's not an error.
+    if (data.status === 'failed' || data.status === 'blocked')
+        process.exitCode = 1;
+});

package/dist/commands/login.js

@@ -4,6 +4,8 @@ import config, { getApiUrl } from '../lib/config.js';
 import { api } from '../lib/api.js';
 import { requireFreshJwt, requireUrl } from '../lib/validate.js';
 import { promptPassword } from '../lib/prompt.js';
+import { requireInteractive } from '../lib/confirm.js';
+import { json } from '../lib/format.js';
 async function promptEmail() {
     const { createInterface } = await import('readline');
     const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -25,12 +27,26 @@ async function promptEmail() {
         rl.close();
     }
 }
+/** #107 — the shared success-reporting tail for all three login paths (env
+ * token, --token flag, email/password). Under --json, prints a single
+ * structured result on stdout instead of the chalk lines — never the raw
+ * token itself (that's what `trawl token` is for). */
+function reportLoginSuccess(opts, email) {
+    if (opts.json) {
+        json({ ok: true, apiUrl: getApiUrl(), config: config.path, ...(email && { email }) });
+        return;
+    }
+    console.log(chalk.green(email ? `✓ Logged in as ${email}` : '✓ Logged in'));
+    console.log(chalk.dim(`  API: ${getApiUrl()}`));
+    console.log(chalk.dim(`  Config: ${config.path}`));
+}
 export const login = new Command('login')
     .description('Authenticate with the Trawl API')
     .option('-u, --url <url>', 'API base URL')
     .option('-t, --token <token>', 'JWT token (for CI use only)')
     .option('-e, --email <email>', 'Email address')
     .option('-p, --password <password>', 'Password (CI only — visible in process list and shell history)')
+    .option('--json', 'Output as JSON')
     .action(async (opts) => {
     // 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
@@ -47,23 +63,28 @@ export const login = new Command('login')
     if (envToken) {
         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}`));
+        reportLoginSuccess(opts);
         return;
     }
     // --token flag: direct JWT (CI / retrocompat)
     if (opts.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}`));
+        reportLoginSuccess(opts);
         return;
     }
     // Email/password flow
     if (opts.password) {
-        console.warn(chalk.yellow('Warning: passing --password on the command line is insecure.'));
+        console.error(chalk.yellow('Warning: passing --password on the command line is insecure.'));
+    }
+    // #107 — never blocks on a readline prompt under --json or a non-TTY
+    // invocation (agent/CI subprocess); refuses with a clear, structured
+    // usage error instead, naming the flag (or TRAWL_TOKEN) to pass.
+    if (!opts.email) {
+        requireInteractive('Email is required — pass -e/--email, --token, or set TRAWL_TOKEN (refusing to block on a prompt, non-interactive).', { json: opts.json });
+    }
+    if (!opts.password) {
+        requireInteractive('Password is required — pass -p/--password, --token, or set TRAWL_TOKEN (refusing to block on a prompt, non-interactive).', { json: opts.json });
     }
     const email = opts.email ?? (await promptEmail());
     const password = opts.password ?? (await promptPassword('Password: '));
@@ -82,13 +103,16 @@ export const login = new Command('login')
     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}`));
+    reportLoginSuccess(opts, email);
 });
 export const logout = new Command('logout')
     .description('Clear stored credentials')
-    .action(() => {
+    .option('--json', 'Output as JSON')
+    .action((opts) => {
     config.set('token', '');
+    if (opts.json) {
+        json({ ok: true });
+        return;
+    }
     console.log(chalk.green('✓ Logged out'));
 });

package/dist/commands/ping.d.ts

@@ -0,0 +1,24 @@
+import { Command } from 'commander';
+/**
+ * `GET /api/health` response shape (home.controller.js#health,
+ * home.service.js#getHealthStatus) — MCP `trawl_health_ping` parity
+ * (`{ok, version, uptime}`). The REST route enriches the payload with
+ * `version`/`uptime`/`db`/`memory` ONLY for an admin caller
+ * (home.controller.js's `isAdmin` gate); a non-admin JWT gets `{status:'ok'}`
+ * alone on a healthy server. A non-2xx response (degraded, `status:503`)
+ * throws an ApiError like any other failed request — but a 2xx response is
+ * NOT a guarantee that `status === 'ok'` (#106 review F5): a soft-degraded
+ * signal (e.g. a partial dependency outage) could still come back as a 200
+ * with a non-"ok" `status`. The HTTP call not throwing only means the
+ * transport succeeded, never that the reported health is good — so the
+ * human-mode `✓ OK` line is gated on the actual field, not assumed from a
+ * successful round-trip.
+ */
+export interface PingResponse {
+    status: string;
+    db?: string;
+    uptime?: number;
+    version?: string;
+    memory?: unknown;
+}
+export declare const ping: Command;

package/dist/commands/ping.js

@@ -0,0 +1,29 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { api } from '../lib/api.js';
+import { json } from '../lib/format.js';
+export const ping = new Command('ping')
+    .description('Health/version handshake against the Trawl API')
+    .option('--json', 'Output as JSON')
+    .action(async (opts) => {
+    const data = await api.get('/api/health');
+    // #106 review (kimi) — honest exit code: a soft-degraded 200 (status !== 'ok')
+    // must exit non-zero so `trawl ping || handle_degraded` doesn't treat a
+    // degraded API as healthy. Applies in BOTH --json and human modes, alongside
+    // the raw/decorated output below.
+    if (data.status !== 'ok')
+        process.exitCode = 1;
+    if (opts.json) {
+        json(data);
+        return;
+    }
+    const versionSuffix = data.version ? ` (v${data.version})` : '';
+    if (data.status === 'ok') {
+        console.log(chalk.green('✓ OK') + versionSuffix);
+    }
+    else {
+        // #106 review F5 — never green-light a degraded API just because the
+        // HTTP call didn't throw; show the real reported status instead.
+        console.log(chalk.yellow(`⚠ ${data.status}`) + versionSuffix);
+    }
+});

package/dist/commands/scraps.d.ts

@@ -17,6 +17,17 @@ interface BeforeRunState {
     alreadyInFlight: boolean;
     captured: boolean;
 }
+/** The machine-readable outcome `pollRunProgress` prints as the single final
+ * NDJSON line under `--json` (#107 review F1). `status` is the same honest
+ * terminal string the human-mode "Run finished: <status>" line already
+ * shows (`success`/`error`/`empty`/`regression`/…), or `'timeout'` /
+ * `'poll_error'` for the two non-terminal exits. */
+export interface PollOutcome {
+    runId?: string;
+    status: string;
+    /** Present only for `status:'poll_error'` — the last poll failure's message. */
+    error?: string;
+}
 /**
  * #91 P1 — replaces "await the run to completion, THEN open the activities
  * SSE stream" (which showed NOTHING: the activities SSE
@@ -78,9 +89,30 @@ interface BeforeRunState {
  * this function has, so it resolves to the same honest timeout rather than
  * risk reporting a possibly-wrong outcome (never a lie, at worst a timeout
  * telling the caller to check `doctor`).
+ *
+ * #107 review F1 — before this fix, `run|trigger --json --watch` was
+ * outcome-blind: `quiet` suppressed ALL output (including "Run finished:
+ * failure" and the timeout notice), a transient poll error was caught and
+ * silently retried FOREVER within the deadline, and the process always
+ * exited 0 after the poll loop regardless of what the watched run actually
+ * did — dead air, then a clean exit code, even for a failed or timed-out
+ * run. An agent scripting this CLI had no way to tell success from failure
+ * from "we gave up". Fixed by:
+ *  - emitting exactly ONE final NDJSON line on stdout under `--json` once
+ *    the watch reaches ANY of its three exits (terminal status, timeout, or
+ *    a persistent poll error) — `{runId,status}` (+`error` for a poll
+ *    error) — while every intermediate progress line stays suppressed
+ *    (unchanged from before);
+ *  - setting `process.exitCode` non-zero on a genuine run failure, a
+ *    timeout, or a persistent poll error, and `0` on a real success — in
+ *    BOTH `--json` and human `--watch` modes (human mode used to exit 0
+ *    unconditionally, the same bug, just silent instead of dishonest);
+ *  - giving up after `MAX_CONSECUTIVE_POLL_ERRORS` consecutive failed reads
+ *    instead of retrying the same dead endpoint for the full 300s.
  */
 export declare function pollRunProgress(id: string, before: BeforeRunState | undefined, opts?: {
     intervalMs?: number;
     timeoutMs?: number;
+    json?: boolean;
 }): Promise<void>;
 export {};