@hunt-labs/bytekit-cli 0.5.0 → 0.7.0

package/dist/commands/fetch.js

@@ -1,11 +1,13 @@
 import { Command, InvalidArgumentError } from 'commander';
 import { buildClient } from '../client.js';
 import { printResult, emitFetchResult, handleError } from '../output.js';
-import { parseUrlLines } from '../lib/url-lines.js';
-import { parseIntFlag, parseEnum, parseCacheTtl } from '../lib/parse-flags.js';
+import { parseBulkLines } from '../lib/url-lines.js';
+import { parseIntFlag, parseEnum, parseCacheTtl, parseJsonFlag } from '../lib/parse-flags.js';
 const FETCH_FORMATS = ['markdown', 'html'];
 /** The `FetchRequest.markdown_mode` spec enum (create/POST only — excluded from the GET query). */
 const MARKDOWN_MODES = ['article', 'raw', 'llm'];
+/** The `markdown_links` / `markdown_images` render-mode enum (shared with `scrape create`). */
+const MARKDOWN_RENDER_MODES = ['inline', 'references', 'none', 'text'];
 /**
  * Validate `--format` locally, before any HTTP request is issued.
  *
@@ -28,14 +30,32 @@ export function makeFetchCommand(getGlobal) {
     bulkCmd
         .command('create')
         .description('Create a bulk fetch job')
-        .requiredOption('--file <path>', 'Path to newline-delimited file of URLs (plain URL or {"url":"..."} per line)')
+        .requiredOption('--file <path>', 'Path to a newline-delimited file. Each line is a plain URL, or a JSON object carrying "url" plus per-item config. A line whose only key is "url" behaves exactly as before (sent as a bare URL string); any line with additional keys switches the payload to the per-item shape.')
         .requiredOption('--webhook-url <url>', 'HTTPS webhook URL notified when the job completes')
+        .option('--webhook-secret <secret>', 'HMAC secret used to sign the completion webhook (omitted → unsigned)')
+        .option('--defaults <json>', 'Defaults applied to every entry, as a JSON object (omitted → none). Unknown keys are rejected by /v1/bulk (422) and ignored by scrape bulk / fetch bulk; fetch bulk additionally rejects browser-only keys (cookies, wait_until, wait_for_selector, delay_ms) with a 400.', (v) => parseJsonFlag('--defaults', v, 'object'))
+        .option('--metadata <json>', `Arbitrary metadata echoed on the job envelope, as a JSON object, e.g. '{"run":"7"}' (omitted → none)`, (v) => parseJsonFlag('--metadata', v, 'object'))
+        // Deliberately NO --custom: /v1/fetch/bulk has no top-level `custom` property
+        // (validators/fetch-bulk.ts:52-62), so the flag would be silently stripped (#2596 drift D2).
+        // FetchBulkBodySchema itself stays non-strict (issue #2648 only makes the per-item
+        // FetchBulkItemOverrideSchema reject unknown keys), so this top-level behavior is unchanged.
         .action(async (opts) => {
         const g = getGlobal();
-        const client = buildClient(g);
         try {
-            const urls = parseUrlLines(opts.file);
-            const result = await client.fetch.bulk.create({ urls, webhook_url: opts.webhookUrl });
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
+            // /v1/fetch/bulk has NO `items` property — its `urls` is a
+            // `string | FetchBulkItemOverride` union (validators/fetch-bulk.ts:57), so both line
+            // shapes ride there directly and no promotion step is needed (#2596 drift D3).
+            const urls = parseBulkLines(opts.file);
+            const body = { urls, webhook_url: opts.webhookUrl };
+            if (opts.webhookSecret !== undefined)
+                body['webhook_secret'] = opts.webhookSecret;
+            if (opts.defaults !== undefined)
+                body['defaults'] = opts.defaults;
+            if (opts.metadata !== undefined)
+                body['metadata'] = opts.metadata;
+            const result = await client.fetch.bulk.create(body);
             printResult(result, g.json);
         }
         catch (err) {
@@ -47,8 +67,9 @@ export function makeFetchCommand(getGlobal) {
         .description('Get a bulk fetch job')
         .action(async (id) => {
         const g = getGlobal();
-        const client = buildClient(g);
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = await client.fetch.bulk.get(id);
             printResult(result, g.json);
         }
@@ -65,23 +86,64 @@ export function makeFetchCommand(getGlobal) {
         .option('--country <cc>', 'Two-letter country code to route the request through (e.g. us, de)')
         .option('--timeout-ms <n>', 'Per-request timeout in milliseconds', (v) => parseIntFlag('--timeout-ms', v))
         .option('--cache-ttl <ttl>', 'Cache freshness: 0, Nh (hours), or Nd (days), e.g. 48h, 2d, 0 (omitted → server default)', (v) => parseCacheTtl('--cache-ttl', v))
-        // `--markdown-mode` is POST-only: FetchGetOpts excludes it, so adding it to `get` below would be
-        // a compile error — the create/get asymmetry is correct by construction.
+        // The markdown surface below is POST-only: FetchGetOpts excludes it, so adding any of it to
+        // `get` would be a compile error — the create/get asymmetry is correct by construction.
         .option('--markdown-mode <mode>', `Markdown mode: ${MARKDOWN_MODES.join(', ')}`, (v) => parseEnum('--markdown-mode', MARKDOWN_MODES, v))
+        .option('--markdown-query <q>', 'BM25 query string for relevance-ranked markdown filtering (omitted → disabled)')
+        .option('--markdown-links <mode>', `Link rendering: ${MARKDOWN_RENDER_MODES.join(', ')} (omitted → server default)`, (v) => parseEnum('--markdown-links', MARKDOWN_RENDER_MODES, v))
+        .option('--markdown-images <mode>', `Image retention: ${MARKDOWN_RENDER_MODES.join(', ')} (omitted → server default)`, (v) => parseEnum('--markdown-images', MARKDOWN_RENDER_MODES, v))
+        .option('--with-links-summary', 'Append a Links footer to the markdown output (omitted → off)')
+        .option('--with-images-summary', 'Append an Images footer to the markdown output (omitted → off)')
+        .option('--markdown-compact', 'Collapse excessive whitespace in the markdown output (omitted → off)')
+        .option('--markdown-filter-images', 'Filter low-signal images from the markdown output (omitted → off)')
+        .option('--markdown-include-media', 'Return rich link/image objects and a tables array (omitted → off)')
+        .option('--markdown-include-warnings', 'Include markdown-pipeline and tag-filter warnings (omitted → off)')
+        .option('--markdown-include-stats', 'Include a top-level stats object (chars, tokens, blocks) (omitted → off)')
+        .option('--custom <json>', `User payload echoed on the envelope as a JSON object, e.g. '{"job":"1"}' (omitted → none)`, (v) => parseJsonFlag('--custom', v, 'object'))
         .option('-o, --output <file>', 'Write the fetched body bytes to the given file path')
         .action(async (opts) => {
         const g = getGlobal();
-        const client = buildClient(g);
+        // Omit-when-absent body, in the `body: Record<string, unknown>` form every other command
+        // file uses (scrape.ts:230-268 is the exemplar). The five pre-existing fields keep the
+        // exact same wire output they had as inline spreads; a boolean is written ONLY on
+        // `=== true`, so it never serializes `false` (#2480 E1).
+        const body = { url: opts.url };
+        if (opts.format !== undefined)
+            body['format'] = opts.format;
+        if (opts.country !== undefined)
+            body['country'] = opts.country;
+        if (opts.timeoutMs !== undefined)
+            body['timeout_ms'] = opts.timeoutMs;
+        if (opts.cacheTtl !== undefined)
+            body['cache_ttl'] = opts.cacheTtl;
+        if (opts.markdownMode !== undefined)
+            body['markdown_mode'] = opts.markdownMode;
+        if (opts.markdownQuery !== undefined)
+            body['markdown_query'] = opts.markdownQuery;
+        if (opts.markdownLinks !== undefined)
+            body['markdown_links'] = opts.markdownLinks;
+        if (opts.markdownImages !== undefined)
+            body['markdown_images'] = opts.markdownImages;
+        if (opts.withLinksSummary === true)
+            body['with_links_summary'] = true;
+        if (opts.withImagesSummary === true)
+            body['with_images_summary'] = true;
+        if (opts.markdownCompact === true)
+            body['markdown_compact'] = true;
+        if (opts.markdownFilterImages === true)
+            body['markdown_filter_images'] = true;
+        if (opts.markdownIncludeMedia === true)
+            body['markdown_include_media'] = true;
+        if (opts.markdownIncludeWarnings === true)
+            body['markdown_include_warnings'] = true;
+        if (opts.markdownIncludeStats === true)
+            body['markdown_include_stats'] = true;
+        if (opts.custom !== undefined)
+            body['custom'] = opts.custom;
         try {
-            const result = await client.fetch.create({
-                url: opts.url,
-                // Each optional field is spread ONLY when its flag is present (#2480 E1).
-                ...(opts.format !== undefined ? { format: opts.format } : {}),
-                ...(opts.country !== undefined ? { country: opts.country } : {}),
-                ...(opts.timeoutMs !== undefined ? { timeout_ms: opts.timeoutMs } : {}),
-                ...(opts.cacheTtl !== undefined ? { cache_ttl: opts.cacheTtl } : {}),
-                ...(opts.markdownMode !== undefined ? { markdown_mode: opts.markdownMode } : {}),
-            });
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
+            const result = await client.fetch.create(body);
             emitFetchResult(result, g.json, { file: opts.output });
         }
         catch (err) {
@@ -99,8 +161,9 @@ export function makeFetchCommand(getGlobal) {
         .option('-o, --output <file>', 'Write the fetched body bytes to the given file path')
         .action(async (opts) => {
         const g = getGlobal();
-        const client = buildClient(g);
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = await client.fetch.get({
                 url: opts.url,
                 ...(opts.format !== undefined ? { format: opts.format } : {}),

package/dist/commands/monitors.js

@@ -20,11 +20,25 @@ export function makeMonitorsCommand(getGlobal) {
     capturesCmd
         .command('list <id>')
         .description('List captures for a monitor')
-        .action(async (id) => {
+        .option('--limit <n>', 'Maximum number of captures to return', (v) => parseIntFlag('--limit', v))
+        .option('--cursor <cursor>', 'Pagination cursor from a previous page')
+        .action(async (id, opts) => {
         const g = getGlobal();
-        const client = buildClient(g);
+        // Same omit-when-absent rule as `monitors list` (#2480): build the params object with
+        // ONLY the flags the caller passed, and call captures.list with a single argument (never
+        // captures.list(id, {}) / captures.list(id, undefined)) when no query flag is passed, so
+        // the inverse-case request-shape assertion stays byte-identical to today (#2594 DoD-4).
+        const params = {};
+        if (opts.limit !== undefined)
+            params.limit = opts.limit;
+        if (opts.cursor !== undefined)
+            params.cursor = opts.cursor;
         try {
-            const result = await client.monitors.captures.list(id);
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
+            const result = Object.keys(params).length > 0
+                ? await client.monitors.captures.list(id, params)
+                : await client.monitors.captures.list(id);
             printResult(result, g.json);
         }
         catch (err) {
@@ -36,6 +50,14 @@ export function makeMonitorsCommand(getGlobal) {
         .command('create')
         .description('Create a page-change monitor')
         .requiredOption('--url <url>', 'URL to monitor')
+        // `--interval-type` is passed through VERBATIM and validated by the API, not locally — a
+        // deliberate choice recorded for #2686 item 5's open question, matching what `search`'s
+        // `--type`/`--date-range` already do. A local enum list is a second source of truth that
+        // drifts from the spec silently: the CLI would start rejecting a value the API has begun
+        // accepting, and the error text would come from a stale copy rather than the server. The
+        // siblings that DO validate locally (`--type`, `--markdown-mode`, `--device`, …) are the
+        // enums this package chose to pin; nothing here should be read as those being wrong, only as
+        // the pass-through being intentional rather than an oversight.
         .requiredOption('--interval-type <type>', 'Check interval: hourly, daily, weekly, or cron')
         .requiredOption('--webhook-url <url>', 'HTTPS webhook URL notified on change')
         .option('--cron <expr>', 'Cron expression (required when --interval-type is cron, e.g. "0 * * * *")')
@@ -48,9 +70,9 @@ export function makeMonitorsCommand(getGlobal) {
         .option('--webhook-headers <json>', `Extra webhook headers as a JSON object, e.g. '{"X-Sig":"abc"}' (omitted → none)`, (v) => parseJsonFlag('--webhook-headers', v, 'object'))
         .option('--options <json>', `Screenshot-monitor options as a JSON object (omitted → server defaults)`, (v) => parseJsonFlag('--options', v, 'object'))
         .option('--scrape-options <json>', `Scrape-monitor options as a JSON object (type=scrape only; omitted → server defaults)`, (v) => parseJsonFlag('--scrape-options', v, 'object'))
+        .option('--metadata <json>', `Arbitrary metadata echoed on the monitor envelope, as a JSON object, e.g. '{"run":"7"}' (omitted → none)`, (v) => parseJsonFlag('--metadata', v, 'object'))
         .action(async (opts) => {
         const g = getGlobal();
-        const client = buildClient(g);
         // Omit-when-absent body (same rule as scrape.ts): each key is written ONLY when its flag is
         // present, so a bare create never materializes a server default (#2480 E1). Typed via an
         // assertion at the call site — the wire body is pinned by request-shapes.test.ts.
@@ -75,7 +97,11 @@ export function makeMonitorsCommand(getGlobal) {
             body['options'] = opts.options;
         if (opts.scrapeOptions !== undefined)
             body['scrape_options'] = opts.scrapeOptions;
+        if (opts.metadata !== undefined)
+            body['metadata'] = opts.metadata;
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = await client.monitors.create(body);
             printResult(result, g.json);
         }
@@ -94,7 +120,6 @@ export function makeMonitorsCommand(getGlobal) {
         // with no runtime change.
         .action(async (opts) => {
         const g = getGlobal();
-        const client = buildClient(g);
         // Build the params object with the same omit-when-absent rule as the body builders. When NO
         // query flag is passed, call list() with ZERO arguments (never list({}) / list(undefined)) so
         // the inverse-case request-shape assertion `monitors.list` args length 0 stays green (#2480).
@@ -106,6 +131,8 @@ export function makeMonitorsCommand(getGlobal) {
         if (opts.status !== undefined)
             params.status = opts.status;
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = Object.keys(params).length > 0
                 ? await client.monitors.list(params)
                 : await client.monitors.list();
@@ -120,8 +147,9 @@ export function makeMonitorsCommand(getGlobal) {
         .description('Get a monitor by ID')
         .action(async (id) => {
         const g = getGlobal();
-        const client = buildClient(g);
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = await client.monitors.get(id);
             printResult(result, g.json);
         }
@@ -132,6 +160,7 @@ export function makeMonitorsCommand(getGlobal) {
     cmd
         .command('update <id>')
         .description('Update a monitor (including pause/resume via --status)')
+        .option('--url <url>', 'New URL to monitor (omitted → unchanged)')
         .option('--interval-type <type>', 'New check interval: hourly, daily, weekly, or cron')
         .option('--cron <expr>', 'New cron expression (when interval-type is cron, e.g. "0 * * * *")')
         .option('--webhook-url <url>', 'New HTTPS webhook URL')
@@ -144,10 +173,14 @@ export function makeMonitorsCommand(getGlobal) {
         .option('--webhook-headers <json>', `New webhook headers as a JSON object, e.g. '{"X-Sig":"abc"}'`, (v) => parseJsonFlag('--webhook-headers', v, 'object'))
         .option('--options <json>', `New screenshot-monitor options as a JSON object`, (v) => parseJsonFlag('--options', v, 'object'))
         .option('--scrape-options <json>', `New scrape-monitor options as a JSON object`, (v) => parseJsonFlag('--scrape-options', v, 'object'))
+        .option('--metadata <json>', `New metadata as a JSON object, e.g. '{"run":"7"}' (omitted → unchanged)`, (v) => parseJsonFlag('--metadata', v, 'object'))
         .action(async (id, opts) => {
         const g = getGlobal();
-        const client = buildClient(g);
         const body = {};
+        // `url` IS settable on PATCH (openapi.yaml MonitorUpdateRequest) — unlike `type`, which
+        // stays immutable and deliberately has no flag (#1984).
+        if (opts.url !== undefined)
+            body['url'] = opts.url;
         if (opts.intervalType !== undefined)
             body['interval_type'] = opts.intervalType;
         if (opts.cron !== undefined)
@@ -168,7 +201,11 @@ export function makeMonitorsCommand(getGlobal) {
             body['options'] = opts.options;
         if (opts.scrapeOptions !== undefined)
             body['scrape_options'] = opts.scrapeOptions;
+        if (opts.metadata !== undefined)
+            body['metadata'] = opts.metadata;
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = await client.monitors.update(id, body);
             printResult(result, g.json);
         }
@@ -181,8 +218,9 @@ export function makeMonitorsCommand(getGlobal) {
         .description('Delete a monitor')
         .action(async (id) => {
         const g = getGlobal();
-        const client = buildClient(g);
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = await client.monitors.delete(id);
             printResult(result, g.json);
         }

package/dist/commands/scrape.js

@@ -1,7 +1,7 @@
 import { Command } from 'commander';
 import { buildClient } from '../client.js';
 import { printResult, handleError, resolveOutputMode, emitResult } from '../output.js';
-import { parseUrlLines } from '../lib/url-lines.js';
+import { parseBulkLines, toBulkItems } from '../lib/url-lines.js';
 import { parseIntFlag, parseEnum, parseCsv, parseCacheTtl, parseJsonFlag, collectFormats, } from '../lib/parse-flags.js';
 /** The `ScrapeRequest.markdown_mode` spec enum. */
 const MARKDOWN_MODES = ['article', 'raw', 'llm'];
@@ -45,15 +45,35 @@ export function makeScrapeCommand(getGlobal) {
     bulkCmd
         .command('create')
         .description('Create a bulk scrape job')
-        .requiredOption('--file <path>', 'Path to newline-delimited file of URLs (plain URL or {"url":"..."} per line)')
+        .requiredOption('--file <path>', 'Path to a newline-delimited file. Each line is a plain URL, or a JSON object carrying "url" plus per-item config. A line whose only key is "url" behaves exactly as before (sent as a bare URL string); any line with additional keys switches the payload to the per-item shape.')
         .requiredOption('--webhook-url <url>', 'HTTPS webhook URL notified when the job completes')
+        .option('--webhook-secret <secret>', 'HMAC secret used to sign the completion webhook (omitted → unsigned)')
+        .option('--defaults <json>', 'Defaults applied to every entry, as a JSON object (omitted → none). Unknown keys are rejected by /v1/bulk (422) and ignored by scrape bulk / fetch bulk; fetch bulk additionally rejects browser-only keys (cookies, wait_until, wait_for_selector, delay_ms) with a 400.', (v) => parseJsonFlag('--defaults', v, 'object'))
+        .option('--metadata <json>', `Arbitrary metadata echoed on the job envelope, as a JSON object, e.g. '{"run":"7"}' (omitted → none)`, (v) => parseJsonFlag('--metadata', v, 'object'))
+        // /v1/scrape/bulk is the ONE bulk endpoint with a top-level `custom`
+        // (validators/scrape-bulk.ts:88). Per-entry `custom` arrives through --file lines instead.
+        .option('--custom <json>', `User payload echoed on every scrape entry, as a JSON object, e.g. '{"job":"1"}' (omitted → none; a per-entry value in --file wins)`, (v) => parseJsonFlag('--custom', v, 'object'))
         .action(async (opts) => {
         const g = getGlobal();
-        const client = buildClient(g);
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             // readFileSync throws ENOENT on missing file — caught by handleError below
-            const urls = parseUrlLines(opts.file);
-            const result = await client.scrape.bulk.create({ urls, webhook_url: opts.webhookUrl });
+            const lines = parseBulkLines(opts.file);
+            // `urls` XOR `items` (validators/scrape-bulk.ts:91-98) — send exactly one, keeping the
+            // pre-#2596 `{ urls, webhook_url }` body byte-identical for url-only files (E2).
+            const body = lines.every((l) => typeof l === 'string')
+                ? { urls: lines, webhook_url: opts.webhookUrl }
+                : { items: toBulkItems(lines), webhook_url: opts.webhookUrl };
+            if (opts.webhookSecret !== undefined)
+                body['webhook_secret'] = opts.webhookSecret;
+            if (opts.defaults !== undefined)
+                body['defaults'] = opts.defaults;
+            if (opts.metadata !== undefined)
+                body['metadata'] = opts.metadata;
+            if (opts.custom !== undefined)
+                body['custom'] = opts.custom;
+            const result = await client.scrape.bulk.create(body);
             printResult(result, g.json);
         }
         catch (err) {
@@ -65,8 +85,9 @@ export function makeScrapeCommand(getGlobal) {
         .description('Get a bulk scrape job')
         .action(async (id) => {
         const g = getGlobal();
-        const client = buildClient(g);
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = await client.scrape.bulk.get(id);
             printResult(result, g.json);
         }
@@ -82,6 +103,12 @@ export function makeScrapeCommand(getGlobal) {
         // Repeatable AND CSV-aware: `--format raw_html --format markdown` and `--format raw_html,markdown`
         // both send formats: ['raw_html','markdown']. Sent as the `formats` array; omitted → server
         // default. `--raw`/`-o` require EXACTLY ONE format (validated pre-request; see the action).
+        //
+        // The format VALUES travel to the server unvalidated — deliberate, and recorded here for
+        // #2686 item 5's open question (same rationale as `monitors --interval-type` and `search`'s
+        // `--type`/`--date-range`). The persisted-format vocabulary grows with the spec, and a local
+        // enum list is a second source of truth that drifts silently: the CLI would reject a format
+        // the API has begun serving, and the error would come from a stale copy rather than the API.
         .option('--format <format>', 'Output format; repeat or comma-separate for multiple (e.g. --format raw_html --format markdown, or --format raw_html,markdown). Sent as the formats array; omitted → server default.', collectFormats)
         .option('--country <cc>', 'Two-letter country code to route the request through (e.g. us, de)')
         .option('--timeout-ms <n>', 'Per-request timeout in milliseconds', (v) => parseIntFlag('--timeout-ms', v))
@@ -118,7 +145,6 @@ export function makeScrapeCommand(getGlobal) {
         .option('-o, --output <file>', 'Write the output to the given file path (implies --raw unless --json is set)')
         .action(async (opts) => {
         const g = getGlobal();
-        const client = buildClient(g);
         const body = { url: opts.url };
         // The v1 scrape validator expects `formats` (array). The --format collector already
         // accumulates repeated/CSV occurrences into an array; write it verbatim, omitting the key
@@ -187,6 +213,8 @@ export function makeScrapeCommand(getGlobal) {
         if (opts.mobile === true)
             body['mobile'] = true;
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             // FIRST statement inside the try — deliberately NOT hoisted next to buildClient() where
             // the other handlers put pre-request logic. index.ts drives commander with .parse(), not
             // .parseAsync(), so nothing awaits this action's promise: a throw raised above the try
@@ -245,11 +273,12 @@ export function makeScrapeCommand(getGlobal) {
         .description('Get a scrape job by ID (use --raw/-o/--format to retrieve a completed body)')
         .option('--raw', 'Print the requested format body raw, with no JSON wrapper')
         .option('-o, --output <file>', 'Write the output to the given file path (implies --raw unless --json is set)')
-        .option('--format <format>', 'Which persisted format to emit raw when several are present')
+        .option('--format <format>', 'Which persisted format to emit — only takes effect with --raw/-o; ignored otherwise')
         .action(async (id, opts) => {
         const g = getGlobal();
-        const client = buildClient(g);
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             // Mirror `scrape create`'s output path: resolveOutputMode FIRST inside the try (so a
             // --json/--raw conflict rejects before the request), then emitResult. The request body is
             // unchanged — scrape.get(id) takes no options — so the inverse-case arg-length assertion in