@trawlme/cli 1.20.0 → 1.22.0

package/README.md

@@ -8,6 +8,8 @@ Command-line client for [Trawl](https://trawl.me) — manage your scraps from th
 
 > ⚠️ **Early stage.** APIs may change before `1.0`. Pin a version if you depend on this in CI.
 
+> 🤖 **Driving this CLI from an AI agent?** See [docs/agent-quickstart.md](docs/agent-quickstart.md) for the minimal surface (`fetch`, `--json`, `TRAWL_TOKEN`, exit codes) — this README is the full human/CI guide.
+
 ## Install
 
 Requires Node.js >= 20.
@@ -21,99 +23,111 @@ npm install -g @trawlme/cli
 Three methods:
 
 1. **Interactive** — `trawl login` (prompts for email and password)
-2. **Env var** — `TRAWL_TOKEN=<jwt> trawl scraps list` (CI/CD, bypasses prompt)
+2. **Env var** — `TRAWL_TOKEN=<jwt> trawl list` (CI/CD, bypasses prompt)
 3. **Token flag** — `trawl login --token <jwt>` (CI/CD, direct JWT)
 
 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.
+`trawl --help` groups commands into two labeled tiers, in this exact wording: **Core commands (agent + human)** (listed first — `--json` first-class, never interactive) and **Management commands (human/CI)** (grouped below — the full scrap-admin/account/auth/skills/telemetry surface). Commander also prints a small ungrouped `help [command]` entry at the bottom, so "two tiers" describes the labeled sections, not literally every line of `--help` output. This section documents both tiers, in that order; [docs/agent-quickstart.md](docs/agent-quickstart.md) covers just the Core tier for an agent integration.
 
-### Auth
+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).
+
+### Core commands (agent + human)
 
 ```
-trawl login [--url <url>] [--token <jwt>] [--email <email>] [--password <pass>]
-trawl logout
-trawl token                                  Print the stored session JWT (for MCP Bearer auth)
+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 <success|failure|never|running|regression>] [--limit <n>] [--page <n>]
+trawl get <id> [--json]                        Get scrap details
+trawl data <id> [--json] [--fresh] [--errors]  Get scrap data (last persisted run — read-only, no quota; --fresh to launch one)
+trawl history <id> [--json] [-n <limit>]       List past runs for a scrap (newest first)
+trawl run-info <hid> [--json]                  Show details of a single run
+trawl trigger <id> [--watch] [--wait] [--json] Launch a scrap as a background worker (returns immediately)
+trawl whoami [--json]                          Show the authenticated user's identity
+trawl ping [--json]                            Health/version handshake against the Trawl API
 ```
 
-### Agent core verbs
+> **No breaking change:** every verb above is also still reachable under its pre-reorg path, `trawl scraps <verb>` (e.g. `trawl scraps list`, `trawl scraps run <id>`) — kept as a hidden alias so scripts written before the surface reorg keep working. `trawl --help` only shows the top-level form above; `trawl scraps --help` only shows the remaining scrap-management commands below.
 
-```
-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
-```
+`fetch`/`whoami`/`ping` are 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.
 
-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.
+- `list` has a short alias, `ls` (matches `trawl --help`'s `list|ls`).
+- `history` lists past runs (newest first); `run-info <hid>` shows details of a single run from that history.
+- `data` returns the last persisted run payload (no execute quota); `--fresh` runs the scrap live instead (consumes execute quota); `--errors` shows the last run's error detail (`--json` on a never-run scrap returns `{"status":"no_runs"}`, exit 0, matching `scraps doctor --json`). `[]` on stdout means a genuine zero-item successful run — a scrap that has never run, whose last run failed, or whose payload aged out of retention returns a `--json` error envelope (exit 4/1/4 respectively) instead. Two more honest states: a run still **in flight** (`status: null` server-side) returns a `kind:"in_progress"` error envelope (exit 1, "retry shortly" — never suggests `--fresh`, which would just 429 against the run already holding the lock); a run whose item count **regressed** vs baseline (`statusDetail: "regression"`) still returns the real, non-empty items on stdout (exit 0) plus a stderr warning pointing at `scraps doctor <id>` — the data itself is genuine even though the run is flagged.
+- `get` (and anything reading through it, like `data`'s default path) embeds only the newest 100 history rows on the returned scrap object — `run-info` and `scraps doctor` fetch a single run directly and are unaffected by that cap. `list`/`get` show a distinct amber `▼` "regression" badge, never the red `✗` a genuine failure gets (matches `scraps doctor`'s own badge).
+- **Long-running scrap execute (`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. `run --watch` and `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.
+- `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
+### Scrap management
 
 ```
-trawl scraps list [--json] [--status <success|failure|never|running|regression>] [--limit <n>] [--page <n>]
-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 data <id> [--json] [--fresh] [--errors]
-trawl scraps history <id> [--json] [-n <limit>]
-trawl scraps run-info <hid> [--json]
+trawl scraps watch <id> [--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.
-- `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).
+- `--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 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.
-- `scraps history` lists past runs (newest first); `scraps run-info <hid>` shows details of a single run from that history.
-- `scraps data` returns the last persisted run payload (no execute quota); `--fresh` runs the scrap live instead (consumes execute quota); `--errors` shows the last run's error detail (`--json` on a never-run scrap returns `{"status":"no_runs"}`, exit 0, matching `doctor --json`). `[]` on stdout means a genuine zero-item successful run — a scrap that has never run, whose last run failed, or whose payload aged out of retention returns a `--json` error envelope (exit 4/1/4 respectively) instead. Two more honest states: a run still **in flight** (`status: null` server-side) returns a `kind:"in_progress"` error envelope (exit 1, "retry shortly" — never suggests `--fresh`, which would just 429 against the run already holding the lock); a run whose item count **regressed** vs baseline (`statusDetail: "regression"`) still returns the real, non-empty items on stdout (exit 0) plus a stderr warning pointing at `scraps doctor <id>` — the data itself is genuine even though the run is flagged.
-- `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.
+- `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).
 
 You can also install skills standalone (without the CLI): `npx @trawlme/skills install`.
 
+### 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.
+
 ### 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
@@ -121,7 +135,7 @@ trawl telemetry status   Show current state, telemetry ID, and opt-out instructi
 `@trawlme/cli` collects anonymous usage data to help us improve the CLI based on real usage patterns. Telemetry is enabled by default.
 
 **What we collect:**
-- Command name (e.g. `scraps list`)
+- Command name (e.g. `list` — the #108 surface reorg renamed a promoted verb's telemetry event from `scraps <verb>` to `<verb>`; invoking the legacy `trawl scraps <verb>` path still emits the pre-reorg `scraps <verb>` name)
 - CLI version
 - Node.js version
 - Platform (e.g. `darwin`, `linux`, `win32`)
@@ -144,11 +158,20 @@ trawl telemetry status   Show current state, telemetry ID, and opt-out instructi
 trawl telemetry off
 
 # Session-level opt-out (env var, takes precedence)
-TRAWL_TELEMETRY=0 trawl scraps list
+TRAWL_TELEMETRY=0 trawl 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:
@@ -156,13 +179,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 `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) |
+| `4`  | Not found (no such resource, or — for `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
 
@@ -173,13 +196,13 @@ Under `--json`, a failing command emits a single error envelope on stdout — `{
 | `TRAWL_TELEMETRY`     | Set to `0` to disable telemetry for the current session           |
 | `DO_NOT_TRACK`        | Set to `1` to disable telemetry (cross-vendor convention, https://consoledonottrack.com) — same effect as `TRAWL_TELEMETRY=0` |
 | `TRAWL_CONFIG_DIR`    | Override where the config file (token, API URL, telemetry state) is stored — useful for hermetic CI runs or concurrent `trawl login`s that must not share one on-disk file |
-| `TRAWL_TIMEOUT`       | Override the per-request fetch timeout in milliseconds (default `30000`; `300000` for `scraps run`/`data --fresh`/`trigger --wait` — this env var always wins over that longer default too) |
+| `TRAWL_TIMEOUT`       | Override the per-request fetch timeout in milliseconds (default `30000`; `300000` for `run`/`data --fresh`/`trigger --wait` — this env var always wins over that longer default too) |
 | `TRAWL_SKILLS_SYNC`   | Set to `0` to disable the startup skills auto-sync entirely       |
 
 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
+TRAWL_API_URL=https://dev.trawl.me TRAWL_TOKEN=<jwt> trawl list --json
 ```
 
 ## API documentation

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/scraps.d.ts

@@ -1,4 +1,26 @@
 import { Command } from 'commander';
+/**
+ * #108 — surface reorg. `run`/`list`/`get`/`data`/`history`/`run-info`/
+ * `trigger` are promoted to top-level verbs (see index.ts's `createProgram`)
+ * alongside `fetch`/`whoami`/`ping`. Each is built by an exported
+ * `attachXCommand(parent, attachOpts)` factory instead of a fixed
+ * `scraps.command(...)` chain, so it can be attached TWICE with a single
+ * source-of-truth definition: once to `program` (the new canonical
+ * top-level path) and once more, hidden, right back onto `scraps` — so every
+ * pre-#108 `trawl scraps <verb>` invocation keeps resolving unchanged
+ * (`{ hidden: true }` only affects help visibility, never resolution).
+ *
+ * Future-drift guard: ALL `.option()`/`.argument()`/`.action()` wiring for a
+ * promoted verb MUST live INSIDE its `attachXCommand` factory body, never
+ * bolted onto one of its two call sites (index.ts's `createProgram` for the
+ * top-level attach, this file's own `attachXCommand(scraps, { hidden: true
+ * })` call for the legacy one). That's the only thing keeping `trawl run
+ * <id>` and `trawl scraps run <id>` identical — a call-site-only tweak to
+ * one attachment would silently diverge the two.
+ */
+type AttachOptions = {
+    hidden?: boolean;
+};
 export declare const scraps: Command;
 /** The top-of-history snapshot pollRunProgress needs to identify which run
  * it's watching — see captureBeforeRunState.
@@ -17,6 +39,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 +111,37 @@ 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 declare function attachListCommand(parent: Command, attachOpts?: AttachOptions): Command;
+export declare function attachGetCommand(parent: Command, attachOpts?: AttachOptions): Command;
+export declare function attachRunCommand(parent: Command, attachOpts?: AttachOptions): Command;
+export declare function attachDataCommand(parent: Command, attachOpts?: AttachOptions): Command;
+export declare function attachHistoryCommand(parent: Command, attachOpts?: AttachOptions): Command;
+export declare function attachRunInfoCommand(parent: Command, attachOpts?: AttachOptions): Command;
+export declare function attachTriggerCommand(parent: Command, attachOpts?: AttachOptions): Command;
 export {};