@trawlme/cli 3.7.4 → 3.8.0

package/dist/index.d.ts

@@ -64,6 +64,58 @@ export declare function isHelpOrVersion(argv: string[]): boolean;
  * case so it never shows up ahead of e.g. `trawl scraps --help`.
  */
 export declare function isBareInvocation(argv: string[]): boolean;
+/**
+ * True for `trawl spec` (with or without `--json`) — deliberately NOT folded
+ * into `isHelpOrVersion` above: that predicate's name and doc comment are
+ * about help/version queries specifically, and `spec` is a real, data-
+ * bearing command (see `isHelpOrVersion`'s own #170 test case), not a help
+ * query. This is its own narrow predicate for a DIFFERENT reason: `spec
+ * --json` is documented (docs/agent-quickstart.md) as the first call an AI
+ * agent makes against this CLI, so it must not mutate anything the caller
+ * did not ask it to — same requirement `--help`/`--version` already got
+ * from `isHelpOrVersion` (#73), extended here to cover `spec` too.
+ *
+ * Scope, stated honestly rather than aspirationally: this guard suppresses
+ * the skills auto-sync (an `rmSync(recursive)` + `cpSync` over the user's
+ * `~/.claude/skills`) and the update notifier (a config write plus a
+ * DETACHED CHILD that queries the npm registry — fatal in an
+ * egress-restricted sandbox). It does NOT suppress `initPostHog()`, which
+ * still creates the `conf` config file and mints a persistent
+ * `telemetryUserId` on first run, exactly as it does for every other
+ * command. That one is deliberate: `spec` is the signal that tells us
+ * whether agents are actually adopting the CLI, so it stays measured, and
+ * the caller's own controls (`TRAWL_TELEMETRY=0`, `DO_NOT_TRACK=1`) are the
+ * opt-out. That same first run also has `initPostHog()` write a one-time
+ * telemetry disclosure line (`ℹ Trawl CLI collects anonymous usage
+ * telemetry…`) to STDERR, ahead of the JSON payload — this guard does not
+ * suppress that either. `stdout` stays pure JSON either way, so this only
+ * bites a caller that merges the two streams (e.g. `2>&1`); whether a `spec`
+ * probe specifically should suppress the notice is a product call,
+ * deliberately not taken here. Do not upgrade this paragraph back to "no
+ * filesystem side effect" without also gating telemetry — a comment that
+ * overstates its own invariant is worse than no comment, because the next
+ * reader trusts it.
+ *
+ * Before this, `trawl spec --json` silently re-synced
+ * `~/.claude/skills` (and `./.claude/skills`) and printed `trawl: re-synced
+ * skill …` lines to stderr BEFORE the JSON payload — an agent's very first
+ * probe of the CLI mutated the user's filesystem and polluted the channel
+ * it was about to parse.
+ *
+ * Matches `spec` as the FIRST positional token, skipping any leading
+ * `-`-prefixed tokens first (a global flag ahead of the subcommand, e.g.
+ * `trawl --debug spec --json`) — the same argv-scan discipline `hasJsonFlag`
+ * below already applies. #170 review F4 — before this, a bare
+ * `argv.slice(2)[0] === 'spec'` check was defeated by ANY leading flag:
+ * `trawl --debug spec --json` read `--debug` as the first positional, missed
+ * the match entirely, and fell through to the normal startup path — running
+ * the filesystem-mutating skills auto-sync during what's documented
+ * (docs/agent-quickstart.md) as an agent's read-only first probe of the CLI.
+ * Still never a bare substring search: e.g. `trawl scraps create --title
+ * spec` (the literal string "spec" as a FLAG VALUE, not a leading flag) never
+ * matches, since `scraps` — the first non-`-`-prefixed token — isn't `spec`.
+ */
+export declare function isSpecQuery(argv: string[]): boolean;
 /** Best-effort scan for a `--json` flag in raw argv, used only when parsing
  * itself failed before any command's own `.opts()` could be resolved (a
  * commander usage error — unknown option/command, missing required arg). Same

package/dist/index.js

@@ -13,9 +13,10 @@ import { upgrade } from './commands/upgrade.js';
 import { create } from './commands/create.js';
 import { whoami } from './commands/whoami.js';
 import { ping } from './commands/ping.js';
+import { spec } from './commands/spec.js';
 import { autoUpdateInstalledSkills } from './lib/skills.js';
 import { initPostHog, captureCommand, shutdown, registerAllowedCommands } from './lib/posthog.js';
-import { classifyError, reportError, stripCommanderErrorPrefix } from './lib/errors.js';
+import { classifyError, reportError, stripCommanderErrorPrefix, retryFieldsFor } from './lib/errors.js';
 import { renderPinch, pinchEnabled } from './lib/pinch.js';
 import { maybeNotifyUpdate, scheduleUpdateCheck } from './lib/updateNotifier.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -126,6 +127,10 @@ export function createProgram() {
     program.addCommand(whoami);
     program.addCommand(token);
     program.addCommand(ping);
+    // #170 — `spec` last: it describes the whole tree above it, so it reads
+    // naturally as the final "and here's the full machine-readable map" entry
+    // rather than being wedged between identity/credential/health utilities.
+    program.addCommand(spec);
     // 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.
@@ -190,6 +195,64 @@ export function isHelpOrVersion(argv) {
 export function isBareInvocation(argv) {
     return argv.slice(2).length === 0;
 }
+/**
+ * True for `trawl spec` (with or without `--json`) — deliberately NOT folded
+ * into `isHelpOrVersion` above: that predicate's name and doc comment are
+ * about help/version queries specifically, and `spec` is a real, data-
+ * bearing command (see `isHelpOrVersion`'s own #170 test case), not a help
+ * query. This is its own narrow predicate for a DIFFERENT reason: `spec
+ * --json` is documented (docs/agent-quickstart.md) as the first call an AI
+ * agent makes against this CLI, so it must not mutate anything the caller
+ * did not ask it to — same requirement `--help`/`--version` already got
+ * from `isHelpOrVersion` (#73), extended here to cover `spec` too.
+ *
+ * Scope, stated honestly rather than aspirationally: this guard suppresses
+ * the skills auto-sync (an `rmSync(recursive)` + `cpSync` over the user's
+ * `~/.claude/skills`) and the update notifier (a config write plus a
+ * DETACHED CHILD that queries the npm registry — fatal in an
+ * egress-restricted sandbox). It does NOT suppress `initPostHog()`, which
+ * still creates the `conf` config file and mints a persistent
+ * `telemetryUserId` on first run, exactly as it does for every other
+ * command. That one is deliberate: `spec` is the signal that tells us
+ * whether agents are actually adopting the CLI, so it stays measured, and
+ * the caller's own controls (`TRAWL_TELEMETRY=0`, `DO_NOT_TRACK=1`) are the
+ * opt-out. That same first run also has `initPostHog()` write a one-time
+ * telemetry disclosure line (`ℹ Trawl CLI collects anonymous usage
+ * telemetry…`) to STDERR, ahead of the JSON payload — this guard does not
+ * suppress that either. `stdout` stays pure JSON either way, so this only
+ * bites a caller that merges the two streams (e.g. `2>&1`); whether a `spec`
+ * probe specifically should suppress the notice is a product call,
+ * deliberately not taken here. Do not upgrade this paragraph back to "no
+ * filesystem side effect" without also gating telemetry — a comment that
+ * overstates its own invariant is worse than no comment, because the next
+ * reader trusts it.
+ *
+ * Before this, `trawl spec --json` silently re-synced
+ * `~/.claude/skills` (and `./.claude/skills`) and printed `trawl: re-synced
+ * skill …` lines to stderr BEFORE the JSON payload — an agent's very first
+ * probe of the CLI mutated the user's filesystem and polluted the channel
+ * it was about to parse.
+ *
+ * Matches `spec` as the FIRST positional token, skipping any leading
+ * `-`-prefixed tokens first (a global flag ahead of the subcommand, e.g.
+ * `trawl --debug spec --json`) — the same argv-scan discipline `hasJsonFlag`
+ * below already applies. #170 review F4 — before this, a bare
+ * `argv.slice(2)[0] === 'spec'` check was defeated by ANY leading flag:
+ * `trawl --debug spec --json` read `--debug` as the first positional, missed
+ * the match entirely, and fell through to the normal startup path — running
+ * the filesystem-mutating skills auto-sync during what's documented
+ * (docs/agent-quickstart.md) as an agent's read-only first probe of the CLI.
+ * Still never a bare substring search: e.g. `trawl scraps create --title
+ * spec` (the literal string "spec" as a FLAG VALUE, not a leading flag) never
+ * matches, since `scraps` — the first non-`-`-prefixed token — isn't `spec`.
+ */
+export function isSpecQuery(argv) {
+    const args = argv.slice(2);
+    let i = 0;
+    while (i < args.length && args[i].startsWith('-'))
+        i++;
+    return args[i] === 'spec';
+}
 /** Best-effort scan for a `--json` flag in raw argv, used only when parsing
  * itself failed before any command's own `.opts()` could be resolved (a
  * commander usage error — unknown option/command, missing required arg). Same
@@ -290,7 +353,7 @@ export function bestEffortCommandName(argv, allowedNames) {
     return 'unknown';
 }
 export async function runCli(argv = process.argv) {
-    if (!isHelpOrVersion(argv))
+    if (!isHelpOrVersion(argv) && !isSpecQuery(argv))
         autoUpdateInstalledSkills();
     // Pinch wave banner (#94) — bare `trawl` only, guarded so it never shows
     // under NO_COLOR/non-TTY/piped output (pinchEnabled() covers all three).
@@ -392,7 +455,18 @@ export async function runCli(argv = process.argv) {
                     // of the outputError override above, which only reformats what
                     // gets WRITTEN to stderr) — strip it so the envelope's `message`
                     // stays clean for a machine parser.
-                    console.log(JSON.stringify({ error: { message: stripCommanderErrorPrefix(err.message), kind: 'usage' } }));
+                    //
+                    // #170 review F3 — typed as ErrorEnvelope (not a bare object
+                    // literal) so the compiler enforces `retryable` being non-optional
+                    // here too. Mutation-proven: `tsc --noEmit` stayed at exit 0 with
+                    // `...retryFieldsFor('usage')` removed entirely before this
+                    // annotation existed.
+                    const envelope = {
+                        message: stripCommanderErrorPrefix(err.message),
+                        kind: 'usage',
+                        ...retryFieldsFor('usage'),
+                    };
+                    console.log(JSON.stringify({ error: envelope }));
                 }
                 process.exitCode = 2;
                 // #88 item 6 — currentCommand is still undefined here whenever the
@@ -443,7 +517,14 @@ export async function runCli(argv = process.argv) {
         // Passive "update available" notifier (#129) — never on a help/version
         // query, and each half individually guarded so a notifier bug can never
         // turn a successful command into a failure or change its exit code.
-        if (!isHelpOrVersion(argv)) {
+        // #170 review F5 — never on a `spec` query either: `maybeNotifyUpdate`/
+        // `scheduleUpdateCheck` write to disk (`Library/Preferences/…/config.json`,
+        // `update-check.json`) and the latter spawns a DETACHED child that queries
+        // the npm registry — real filesystem + network side effects `isSpecQuery`'s
+        // own doc comment already promises `spec --json` never has. Before this,
+        // `spec`'s only protection was skipping the skills auto-sync above; this
+        // finally block ran unconditionally regardless.
+        if (!isHelpOrVersion(argv) && !isSpecQuery(argv)) {
             try {
                 maybeNotifyUpdate();
             }

package/dist/lib/api.d.ts

@@ -1,6 +1,16 @@
 export declare class ApiError extends Error {
     status: number;
-    constructor(status: number, message: string);
+    next?: string[] | undefined;
+    /**
+     * `next` is an OPTIONAL per-instance override of the envelope's default
+     * `next` steps (errors.ts's frozen `RETRY_POLICY`) — set only at the two
+     * apiKey-mode 401 call sites below (via authNextSteps()), where the
+     * generic "trawl login --token <jwt>" default is inert until a live
+     * TRAWL_API_KEY/TRAWL_TOKEN is unset first (#169 review). Absent for every
+     * other error, so classifyError falls back to the frozen default exactly
+     * as before.
+     */
+    constructor(status: number, message: string, next?: string[] | undefined);
 }
 /**
  * A fetch-level failure — the request never got a response at all (DNS,
@@ -23,7 +33,9 @@ export declare class NetworkError extends Error {
  * ApiError, absent here). (#88 item 4)
  */
 export declare class AuthError extends Error {
-    constructor(message: string);
+    next?: string[] | undefined;
+    /** See ApiError's `next` for what this overrides and why. */
+    constructor(message: string, next?: string[] | undefined);
 }
 /**
  * The single "no token available" error — every call site in this file that
@@ -37,6 +49,28 @@ export declare class AuthError extends Error {
  * the same thing everywhere it can be observed. (#86 findings 1/2, #88 item 4)
  */
 export declare function notLoggedInError(): AuthError;
+/**
+ * The "this route is JWT-only" error — thrown client-side, before any HTTP
+ * call, by a command that only works with a session JWT (today: `whoami`,
+ * see its own doc comment for why `GET /api/users/me` was descoped rather
+ * than relocated) when the resolved credential is a scoped API key instead.
+ * Distinct from notLoggedInError(): there IS a credential here, it's just
+ * the wrong shape for this one route. Left unhandled, that route would 401
+ * and surface the generic `notLoggedInError`-adjacent message ("Session
+ * expired or invalid. Run: trawl login") — wrong twice over under a key: the
+ * route never accepts keys at all (no session ever "expired"), and
+ * re-running `trawl login` genuinely IS the fix here, just not because
+ * anything expired. Classifies to the SAME exit 3 / kind:"auth" as every
+ * other auth failure (#169) — reusing the existing `auth` kind rather than
+ * minting a new one, since the taxonomy question is still "not
+ * authenticated the way this route needs," never a new category.
+ *
+ * Always called already knowing authMode is 'apiKey' (see whoami.ts) — the
+ * message and `next` both route through loginRemedyText()/authNextSteps()
+ * so this never emits the same inert "Run: trawl login" that finding 2
+ * corrects everywhere else. (#169 review round 2 — finding 2)
+ */
+export declare function apiKeyUnsupportedError(command: string): AuthError;
 /**
  * #91 P0 — some endpoints legitimately run 30–250s server-side: a scrap
  * execute (worker-puppeteer navigation + antibot tier escalation + AI-fix

package/dist/lib/api.js

@@ -1,16 +1,27 @@
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
-import { getApiUrl, getToken } from './config.js';
+import { getApiUrl, getToken, getAuthMode, getLiveAuthEnvVar } from './config.js';
 import { parseServerJson } from './json.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(resolve(__dirname, '../../package.json'), 'utf8'));
 const USER_AGENT = `@trawlme/cli/${pkg.version}`;
 export class ApiError extends Error {
     status;
-    constructor(status, message) {
+    next;
+    /**
+     * `next` is an OPTIONAL per-instance override of the envelope's default
+     * `next` steps (errors.ts's frozen `RETRY_POLICY`) — set only at the two
+     * apiKey-mode 401 call sites below (via authNextSteps()), where the
+     * generic "trawl login --token <jwt>" default is inert until a live
+     * TRAWL_API_KEY/TRAWL_TOKEN is unset first (#169 review). Absent for every
+     * other error, so classifyError falls back to the frozen default exactly
+     * as before.
+     */
+    constructor(status, message, next) {
         super(message);
         this.status = status;
+        this.next = next;
         this.name = 'ApiError';
     }
 }
@@ -38,8 +49,11 @@ export class NetworkError extends Error {
  * ApiError, absent here). (#88 item 4)
  */
 export class AuthError extends Error {
-    constructor(message) {
+    next;
+    /** See ApiError's `next` for what this overrides and why. */
+    constructor(message, next) {
         super(message);
+        this.next = next;
         this.name = 'AuthError';
     }
 }
@@ -57,6 +71,144 @@ export class AuthError extends Error {
 export function notLoggedInError() {
     return new AuthError('Not logged in. Run: trawl login');
 }
+/**
+ * The actionable "how to recover" tail for an apiKey-mode auth failure —
+ * shared by sessionAuthMessage's apiKey branch and apiKeyUnsupportedError so
+ * neither one contradicts the other. `Run: trawl login` alone is INERT
+ * whenever TRAWL_API_KEY/TRAWL_TOKEN is live: getToken()'s own precedence
+ * (config.ts) keeps resolving the env credential over whatever `trawl login`
+ * just stored, so the login it just told the operator to run changes
+ * nothing on the very next request — reproduced end to end (`login --token
+ * <jwt>` reports success; the next call 401s again with the same rejected
+ * key). Leads with the unset step whenever there's a live var to unset;
+ * falls back to the plain original wording when there isn't (the stored
+ * config token case — `trawl login` alone already fixes that one). (#169
+ * review round 2 — finding 2)
+ */
+function loginRemedyText() {
+    const liveVar = getLiveAuthEnvVar();
+    return liveVar ? `unset ${liveVar}, then run: trawl login` : 'Run: trawl login';
+}
+/**
+ * The machine-readable counterpart to loginRemedyText() — feeds `ApiError`/
+ * `AuthError`'s `next` override (see ApiError's doc comment) so an agent
+ * reading `--json` on stdout gets the SAME "unset first" step the prose
+ * message carries, never a `next` that quietly disagrees with the message
+ * next to it. Only ever called from a branch that already knows the auth
+ * mode is 'apiKey' — see both call sites. (#169 review round 2 — finding 2)
+ */
+function authNextSteps() {
+    const liveVar = getLiveAuthEnvVar();
+    const login = 'trawl login --token <jwt>';
+    return liveVar ? [`unset ${liveVar}`, login] : [login];
+}
+/**
+ * The "this route is JWT-only" error — thrown client-side, before any HTTP
+ * call, by a command that only works with a session JWT (today: `whoami`,
+ * see its own doc comment for why `GET /api/users/me` was descoped rather
+ * than relocated) when the resolved credential is a scoped API key instead.
+ * Distinct from notLoggedInError(): there IS a credential here, it's just
+ * the wrong shape for this one route. Left unhandled, that route would 401
+ * and surface the generic `notLoggedInError`-adjacent message ("Session
+ * expired or invalid. Run: trawl login") — wrong twice over under a key: the
+ * route never accepts keys at all (no session ever "expired"), and
+ * re-running `trawl login` genuinely IS the fix here, just not because
+ * anything expired. Classifies to the SAME exit 3 / kind:"auth" as every
+ * other auth failure (#169) — reusing the existing `auth` kind rather than
+ * minting a new one, since the taxonomy question is still "not
+ * authenticated the way this route needs," never a new category.
+ *
+ * Always called already knowing authMode is 'apiKey' (see whoami.ts) — the
+ * message and `next` both route through loginRemedyText()/authNextSteps()
+ * so this never emits the same inert "Run: trawl login" that finding 2
+ * corrects everywhere else. (#169 review round 2 — finding 2)
+ */
+export function apiKeyUnsupportedError(command) {
+    return new AuthError(`${command} requires a session (JWT) — this credential is a scoped API key, which this route does not accept. ${loginRemedyText()}`, authNextSteps());
+}
+/**
+ * The ONE place that decides what a real server-issued 401 means, for
+ * whichever credential shape produced it (#169 review finding 1). Before this, a
+ * genuine 401 always got the same "Session expired or invalid" text — true
+ * for a JWT, but wrong twice over for a scoped API key: an API key doesn't
+ * have a "session" to expire, and re-running `trawl login` fixes nothing
+ * when the ROUTE itself is JWT-only (`scraps update`/`delete`, `scraps
+ * account *`/`scraps session *`, `scraps banner`, the SSE `scraps watch` —
+ * `whoami` already catches this client-side, see apiKeyUnsupportedError
+ * above, but those five/six never had an equivalent guard).
+ *
+ * #169 review round 2 — finding 1: the FIRST fix here asserted two things
+ * never established — that the route is JWT-only, AND that "the API key in
+ * use is valid." Both are false whenever the 401 is the KEY's own fault
+ * (revoked/rotated/malformed) rather than the route's — reproduced live
+ * against `GET /api/scraps` (dual-auth, works with a key) using a revoked
+ * key: the old text confidently certified the key as valid and blamed the
+ * route, which sends the operator away from the actual problem. trawl_node's
+ * authenticateApiKey.js (modules/developers/middlewares/authenticateApiKey.js)
+ * already tells the two cases apart in the response body — `responses.error`
+ * puts the real reason in `description` ("Invalid or expired API key" /
+ * "Invalid API key format" / "Missing or invalid Authorization header") for
+ * a REJECTED key, while a JWT-only route's `passport.authenticate('jwt')`
+ * (cookie-only extractor — a Bearer header never even reaches the verify
+ * step) sends passport's own bare `Unauthorized` body with nothing to
+ * disambiguate. `extractErrorMessage` already unwraps that envelope and
+ * prefers `description` over a `message` that only echoes the reason phrase
+ * — reused here instead of re-parsing, and its plain-text fallback (`return
+ * raw`) is exactly the bare `Unauthorized` case. So: a body that resolves to
+ * anything other than that bare word IS the server naming the real cause —
+ * trust it over any guess. Anything else (unrecoverable, or genuinely just
+ * "Unauthorized") gets an honest hedge between the two live possibilities,
+ * never a pick.
+ *
+ * Deliberately driven off the REAL response (called only where a 401 just
+ * came back from the server), not a client-side allow-list of "routes a key
+ * can reach" duplicated into every command handler — the server is the only
+ * side that actually knows which routes accept a key, and a second,
+ * hand-maintained list here would silently drift the moment trawl_node opens
+ * (or closes) a route to keys. That's also why the message can't name the
+ * specific CLI command the way apiKeyUnsupportedError does: this function
+ * only ever sees the HTTP response, never which `trawl` verb issued the
+ * request.
+ *
+ * `res` is optional and read defensively (`typeof res.text === 'function'`,
+ * `.catch(() => '')`) — the SSE call site (`stream()`) passes a real
+ * `Response` in production, but its own unit tests mock a bare `{ok,
+ * status}` with no `text()` at all; a missing/failed body read just falls
+ * through to the honest hedge rather than throwing a SECOND error while
+ * already handling the first.
+ *
+ * Still an ApiError(401), not an AuthError — a real HTTP round-trip
+ * happened, so the envelope's `status:401` field must stay honest about
+ * that (see AuthError's own doc comment on why a LOCAL failure never
+ * fabricates one). Same exit 3 / kind:"auth" either way — only the message
+ * text differs. (#169 review)
+ */
+async function sessionAuthMessage(authMode, res) {
+    if (authMode === 'jwt')
+        return 'Session expired or invalid. Run: trawl login';
+    const raw = res && typeof res.text === 'function' ? await res.text().catch(() => '') : '';
+    const cause = raw ? extractErrorMessage(raw, res?.statusText) : '';
+    if (cause && cause.trim().toLowerCase() !== 'unauthorized') {
+        return `${cause} (401). ${loginRemedyText()} to use a session instead.`;
+    }
+    return `The API key was rejected (401) — either this route requires a session (JWT), or the key is invalid or revoked. ${loginRemedyText()}.`;
+}
+/**
+ * One shared header set for whichever credential `getToken()` resolved: a
+ * scoped API key (`trawl_*`) goes in `Authorization: Bearer`; a session JWT
+ * stays in the `TOKEN` cookie — trawl_node's passport JWT strategy is
+ * cookie-only on the REST surface, so a Bearer header there is silently
+ * ignored, which is why this is a SWITCH and not an addition. Never sends
+ * both — two credentials on one request is an ambiguity the server does not
+ * have to resolve in our favour. Takes the token the caller already
+ * resolved (never re-calls getToken() itself) so a request's headers and its
+ * own classification of that same token can't drift mid-flight. Used at all
+ * 5 call sites that attach a credential: request/upload/publicGet/getText/
+ * stream. (#169)
+ */
+function authHeaders(token) {
+    return getAuthMode(token) === 'apiKey' ? { Authorization: `Bearer ${token}` } : { Cookie: `TOKEN=${token}` };
+}
 const DEFAULT_TIMEOUT_MS = 30_000;
 /**
  * #91 P0 — some endpoints legitimately run 30–250s server-side: a scrap
@@ -212,9 +364,15 @@ function extractUpgradeUrl(raw) {
     }
     return null;
 }
-async function throwIfError(res, isPublic = false) {
+async function throwIfError(res, isPublic = false, authMode = 'jwt') {
     if (res.status === 401 && !isPublic) {
-        throw new ApiError(401, 'Session expired or invalid. Run: trawl login');
+        // #169 review round 2 — finding 1: sessionAuthMessage now reads the body
+        // itself (the bug this whole branch used to have was discarding it
+        // without ever calling res.text()), so it's awaited here instead of
+        // called synchronously. `next` is only overridden in apiKey mode — see
+        // authNextSteps()'s own doc comment for why jwt mode keeps the frozen
+        // default (finding 2).
+        throw new ApiError(401, await sessionAuthMessage(authMode, res), authMode === 'apiKey' ? authNextSteps() : undefined);
     }
     if (!res.ok) {
         const raw = await res.text();
@@ -249,10 +407,10 @@ async function request(path, options = {}, reqOpts = {}) {
             'Content-Type': 'application/json',
             'User-Agent': USER_AGENT,
             ...options.headers,
-            Cookie: `TOKEN=${token}`,
+            ...authHeaders(token),
         },
     }, timeoutMs);
-    await throwIfError(res);
+    await throwIfError(res, false, getAuthMode(token));
     const text = await res.text();
     try {
         if (!text)
@@ -281,10 +439,10 @@ async function upload(path, formData, reqOpts = {}) {
         signal: AbortSignal.timeout(timeoutMs),
         headers: {
             'User-Agent': USER_AGENT,
-            Cookie: `TOKEN=${token}`,
+            ...authHeaders(token),
         },
     }, timeoutMs);
-    await throwIfError(res);
+    await throwIfError(res, false, getAuthMode(token));
     const text = await res.text();
     try {
         if (!text)
@@ -340,7 +498,7 @@ async function publicGet(path, reqOpts = {}) {
     const res = await safeFetch(url, {
         headers: {
             'User-Agent': USER_AGENT,
-            ...(token ? { Cookie: `TOKEN=${token}` } : {}),
+            ...(token ? authHeaders(token) : {}),
         },
         signal: AbortSignal.timeout(timeoutMs),
     }, timeoutMs);
@@ -369,11 +527,11 @@ async function getText(path, reqOpts = {}) {
     const res = await safeFetch(url, {
         headers: {
             'User-Agent': USER_AGENT,
-            Cookie: `TOKEN=${token}`,
+            ...authHeaders(token),
         },
         signal: AbortSignal.timeout(timeoutMs),
     }, timeoutMs);
-    await throwIfError(res);
+    await throwIfError(res, false, getAuthMode(token));
     return res.text();
 }
 export const api = {
@@ -405,9 +563,22 @@ export const api = {
             headers: {
                 Accept: 'text/event-stream',
                 'User-Agent': USER_AGENT,
-                Cookie: `TOKEN=${token}`,
+                ...authHeaders(token),
             },
         }, getTimeoutMs());
+        // `scraps watch` is one of the JWT-only routes (#169 review finding 1) —
+        // singled out here (not routed through throwIfError, since this call
+        // never sets `isPublic` and the SSE fetch has no timeout signal to
+        // thread through) so a real 401 gets the same honest, auth-mode-aware
+        // message every other JWT-only route does, instead of the opaque `SSE
+        // failed: 401`. sessionAuthMessage reads `res` defensively — a real SSE
+        // Response supports `.text()` in production; only this file's own mocks
+        // sometimes don't, and that falls through to the honest hedge rather
+        // than throwing a second error (see sessionAuthMessage's doc comment).
+        if (res.status === 401) {
+            const mode = getAuthMode(token);
+            throw new ApiError(401, await sessionAuthMessage(mode, res), mode === 'apiKey' ? authNextSteps() : undefined);
+        }
         if (!res.ok || !res.body) {
             throw new ApiError(res.status, `SSE failed: ${res.status}`);
         }

package/dist/lib/config.d.ts

@@ -24,14 +24,46 @@ declare const config: Conf<TrawlConfig>;
  */
 export declare function getApiUrl(): string;
 /**
- * Resolve the effective session token.
- * Precedence: TRAWL_TOKEN env > stored `trawl login` token.
- * Lets CI/agents authenticate headlessly (`TRAWL_TOKEN=<jwt> trawl scraps list`)
- * without ever touching the on-disk config — and without a stored token being
- * silently sent to whatever TRAWL_API_URL points at instead (cross-env
- * credential misuse). Every request/upload/getText/stream call site in
- * api.ts must read the token through this, never through `config.get('token')`
- * directly. Mirrors getApiUrl(). (#68)
+ * Resolve the effective credential — a scoped API key or a session JWT.
+ * Precedence: TRAWL_API_KEY env > TRAWL_TOKEN env > stored `trawl login`
+ * token. TRAWL_API_KEY resolves first so an agent harness that carries BOTH
+ * (e.g. a scoped key set globally alongside a leftover human TRAWL_TOKEN)
+ * gets the key unambiguously, never a silent fall-through to the
+ * higher-privilege JWT. Lets CI/agents authenticate headlessly
+ * (`TRAWL_API_KEY=trawl_xxx trawl list` or `TRAWL_TOKEN=<jwt> trawl list`)
+ * without ever touching the on-disk config — and without a stored token
+ * being silently sent to whatever TRAWL_API_URL points at instead (cross-env
+ * credential misuse). Every request/upload/publicGet/getText/stream call
+ * site in api.ts must read the token through this, never through
+ * `config.get('token')` directly. Mirrors getApiUrl(). (#68, #169)
  */
 export declare function getToken(): string;
+/**
+ * Discriminate which of the two credential shapes this CLI can send a
+ * `token` is: a scoped API key (`Authorization: Bearer`) or a session JWT
+ * (`Cookie: TOKEN=`). The `trawl_` prefix is the SERVER's own test —
+ * trawl_node's `authenticateApiKey.js` checks `rawKey.startsWith('trawl_')`
+ * — not a convention invented on this side; this function exists so the two
+ * sides can never quietly drift apart on what counts as a key. Defaults to
+ * the live `getToken()` result so most callers (e.g. `whoami`'s JWT-only
+ * guard) need no argument; `api.ts`'s `authHeaders()` instead passes the
+ * exact token it already resolved for THIS request, so a request's headers
+ * and its classification of that same token can never disagree. (#169)
+ */
+export declare function getAuthMode(token?: string): 'apiKey' | 'jwt';
+/**
+ * Which of getToken()'s two env-var overrides actually won, if either —
+ * mirrors its TRAWL_API_KEY > TRAWL_TOKEN precedence exactly. Neither
+ * `trawl login` nor `trawl logout` can unset a caller's OWN environment, so
+ * whichever of these is set keeps overriding the stored config token
+ * regardless of what those commands just did (#169 review). login.ts's
+ * post-login/post-logout warnings and api.ts's apiKey-mode auth-failure
+ * messages/`next` steps all need the SAME answer to "what has to be unset
+ * before `trawl login` takes effect" — resolved once here rather than each
+ * call site re-deriving its own copy that could quietly drift from
+ * getToken()'s actual precedence. Returns null when the credential came from
+ * the stored config token instead — nothing to unset there, `trawl login`
+ * alone already fixes that case.
+ */
+export declare function getLiveAuthEnvVar(): 'TRAWL_API_KEY' | 'TRAWL_TOKEN' | null;
 export default config;

package/dist/lib/config.js

@@ -31,17 +31,60 @@ export function getApiUrl() {
     return override ? override : config.get('apiUrl');
 }
 /**
- * Resolve the effective session token.
- * Precedence: TRAWL_TOKEN env > stored `trawl login` token.
- * Lets CI/agents authenticate headlessly (`TRAWL_TOKEN=<jwt> trawl scraps list`)
- * without ever touching the on-disk config — and without a stored token being
- * silently sent to whatever TRAWL_API_URL points at instead (cross-env
- * credential misuse). Every request/upload/getText/stream call site in
- * api.ts must read the token through this, never through `config.get('token')`
- * directly. Mirrors getApiUrl(). (#68)
+ * Resolve the effective credential — a scoped API key or a session JWT.
+ * Precedence: TRAWL_API_KEY env > TRAWL_TOKEN env > stored `trawl login`
+ * token. TRAWL_API_KEY resolves first so an agent harness that carries BOTH
+ * (e.g. a scoped key set globally alongside a leftover human TRAWL_TOKEN)
+ * gets the key unambiguously, never a silent fall-through to the
+ * higher-privilege JWT. Lets CI/agents authenticate headlessly
+ * (`TRAWL_API_KEY=trawl_xxx trawl list` or `TRAWL_TOKEN=<jwt> trawl list`)
+ * without ever touching the on-disk config — and without a stored token
+ * being silently sent to whatever TRAWL_API_URL points at instead (cross-env
+ * credential misuse). Every request/upload/publicGet/getText/stream call
+ * site in api.ts must read the token through this, never through
+ * `config.get('token')` directly. Mirrors getApiUrl(). (#68, #169)
  */
 export function getToken() {
+    const apiKey = process.env['TRAWL_API_KEY']?.trim();
+    if (apiKey)
+        return apiKey;
     const override = process.env['TRAWL_TOKEN']?.trim();
     return override ? override : config.get('token');
 }
+/**
+ * Discriminate which of the two credential shapes this CLI can send a
+ * `token` is: a scoped API key (`Authorization: Bearer`) or a session JWT
+ * (`Cookie: TOKEN=`). The `trawl_` prefix is the SERVER's own test —
+ * trawl_node's `authenticateApiKey.js` checks `rawKey.startsWith('trawl_')`
+ * — not a convention invented on this side; this function exists so the two
+ * sides can never quietly drift apart on what counts as a key. Defaults to
+ * the live `getToken()` result so most callers (e.g. `whoami`'s JWT-only
+ * guard) need no argument; `api.ts`'s `authHeaders()` instead passes the
+ * exact token it already resolved for THIS request, so a request's headers
+ * and its classification of that same token can never disagree. (#169)
+ */
+export function getAuthMode(token = getToken()) {
+    return token.startsWith('trawl_') ? 'apiKey' : 'jwt';
+}
+/**
+ * Which of getToken()'s two env-var overrides actually won, if either —
+ * mirrors its TRAWL_API_KEY > TRAWL_TOKEN precedence exactly. Neither
+ * `trawl login` nor `trawl logout` can unset a caller's OWN environment, so
+ * whichever of these is set keeps overriding the stored config token
+ * regardless of what those commands just did (#169 review). login.ts's
+ * post-login/post-logout warnings and api.ts's apiKey-mode auth-failure
+ * messages/`next` steps all need the SAME answer to "what has to be unset
+ * before `trawl login` takes effect" — resolved once here rather than each
+ * call site re-deriving its own copy that could quietly drift from
+ * getToken()'s actual precedence. Returns null when the credential came from
+ * the stored config token instead — nothing to unset there, `trawl login`
+ * alone already fixes that case.
+ */
+export function getLiveAuthEnvVar() {
+    if (process.env['TRAWL_API_KEY']?.trim())
+        return 'TRAWL_API_KEY';
+    if (process.env['TRAWL_TOKEN']?.trim())
+        return 'TRAWL_TOKEN';
+    return null;
+}
 export default config;