@hunt-labs/bytekit-cli 0.8.1 → 0.9.1

package/CHANGELOG.md

@@ -10,6 +10,67 @@ today, see [README.md](./README.md), which remains the authoritative usage guide
 
 ## [Unreleased]
 
+## [0.9.1] - 2026-08-27
+
+### Fixed
+
+- **A rejected request now names the field that was rejected.** When the API answers
+  `422 validation_error`, its envelope carries `details.fieldErrors` — the field the server
+  refused and what it will accept. The CLI dropped it twice over: its own transport parser never
+  read `error.details` off the envelope (the SDK has read it since `@hunt-labs/bytekit-sdk@0.6.0`),
+  and `handleError` rendered only the message, code and status. The result was
+  `Error: Invalid request body. (validation_error, status: 422)` and nothing else, in human and
+  `--json` modes alike, leaving `curl` as the only way to find out which field was wrong (#3538).
+
+  ```console
+  $ bytekit scrape create --url https://example.com --country zzzz
+  Error: Invalid request body. (validation_error, status: 422)
+  Details:
+    fieldErrors.country: String must contain exactly 2 character(s)
+  ```
+
+  The block is rendered on **stderr**, below the existing one-liner, and is **bounded** — at most
+  ten lines of at most 200 characters, with a `… and <n> more` line when there are further
+  entries — so an oversized or deeply nested `details` can never become a multi-KB dump in a
+  terminal. Nothing else changed: the `Error: ` prefix, the `(<code>, status: <n>)` suffix, exit
+  code `1` and the silence of stdout are all as before, and an error carrying no `details` (or a
+  `details` that is not a JSON object) prints exactly the single line it printed in `0.9.0`.
+  `--json` stdout stays byte-for-byte pipe-clean, because every byte of this goes to stderr.
+
+  The bound covers **depth** as well as size: the renderer descends at most eight array levels into
+  a `details` value and elides anything deeper as `…`. The line and width caps are applied after
+  that walk has finished, so on their own they could not stop a `details` payload nested thousands
+  of arrays deep — a body `JSON.parse` accepts, so a server can send one — from overflowing the
+  stack and printing a Node `RangeError` trace in place of the one-line error (#3633). Every
+  `details` shape the API sends renders byte-identically: nothing real is more than one array level
+  deep.
+
+  The same bound now covers the **object** arm of that walk. A `details` value that is a JSON object
+  was serialized with a bare `JSON.stringify`, which is itself natively recursive and overflowed the
+  stack on its own: flattening the key by one level bounds WHICH values are rendered, not how deep
+  each one is serialized, so a deeply object-nested payload still printed a `RangeError` trace
+  (#3647). Objects nested more than eight levels below the flattened key now elide as `…`, exactly
+  as over-deep arrays do. Everything shallower renders byte-identically, both live shapes included.
+
+## [0.9.0] - 2026-08-20
+
+### Removed
+
+- **BREAKING: `--cookies` and `--headers` are gone from `scrape create` and `screenshots create`**
+  (#3242). The API no longer accepts caller-supplied cookies or request headers on any capture
+  endpoint, so passing either flag is now an unknown-option error before any request is issued,
+  and a body carrying those keys is rejected by the server with `400 validation_error`. There is
+  no deprecation window, feature flag, or compatibility header.
+
+  ```bash
+  # before
+  bytekit scrape create --url https://example.com --cookies '[{"name":"session","value":"abc"}]'
+  # after — the flag does not exist
+  bytekit scrape create --url https://example.com
+  ```
+
+  `--webhook-headers` on `monitors` is a different flag and is unaffected.
+
 ## [0.8.1] - 2026-08-13
 
 ### Fixed
@@ -75,6 +136,16 @@ today, see [README.md](./README.md), which remains the authoritative usage guide
   npm when the entries above landed, so they ride this same pending release rather than stranding
   it as a never-published version.
 
+- **Corrected a false legacy-name claim carried since the rename (#2950).** The `0.8.0`-era note
+  below said the prior `rapidcrawl-cli` name "remains installable at its last version but is
+  deprecated." Verified 2026-08-13: `rapidcrawl-cli` returns npm `404` ("is not in this
+  registry"), and `npm deprecate rapidcrawl-cli@'*'` fails with the same `404` — there is no
+  published version left for a deprecation notice to attach to, so the claim never held. No
+  registry stub or deprecation was possible to publish (npm has nothing to act on); root
+  `CLAUDE.md` carried the same false claim and is corrected alongside this entry. Users of the old
+  name should install `@hunt-labs/bytekit-cli` directly. No command, flag, or runtime behavior
+  changes.
+
 ## [0.8.0] - 2026-08-11
 
 ### Added
@@ -511,8 +582,10 @@ Additive, lower-risk release — no breaking changes to existing commands.
 ### Changed
 
 - Package renamed to `@hunt-labs/bytekit-cli` (the `@bytekit` npm scope was
-  unobtainable); the `bin` name stays `bytekit`. The prior `rapidcrawl-cli` name
-  remains installable at its last version but is deprecated.
+  unobtainable); the `bin` name stays `bytekit`. ~~The prior `rapidcrawl-cli` name
+  remains installable at its last version but is deprecated.~~ **Corrected in
+  0.8.1 (see below): that claim does not hold — `rapidcrawl-cli` 404s on npm and
+  there is no published version left to deprecate.**
 - Consumer call sites propagate the SDK's narrowed, spec-derived request types (#2426).
 - Publish-ready packaging metadata: dropped `main`, unpinned the SDK dependency to
   `workspace:^`, added `engines`, `keywords`, `homepage`, `bugs`, `README.md`,

package/README.md

@@ -171,7 +171,7 @@ exits `0`.
 
 ```bash
 bytekit fetch create --url https://example.com
-bytekit fetch get --url https://example.com --format markdown
+bytekit fetch get --url https://example.com
 bytekit fetch get --url https://example.com/logo.png -o logo.png
 bytekit fetch bulk create --file urls.txt --webhook-url https://your.app/hooks/bytekit
 ```
@@ -193,30 +193,11 @@ Note the acronym casing — `X-Fetch-ID` and `X-Fetch-URL`, not `X-Fetch-Id` /
 `X-Fetch-Url`. (Versions up to 0.6.0 emitted the Title-Cased spellings; see the
 CHANGELOG.)
 
-Both verbs **require** `--url <url>`. Both also accept `--format <format>`
-(`markdown` or `html`), `--country <cc>`, `--timeout-ms <n>`, `--cache-ttl <ttl>`
+Both verbs **require** `--url <url>`. They accept `--country <cc>`, `--timeout-ms <n>`, `--cache-ttl <ttl>`
 (`0`, `Nh`, or `Nd`), and `-o, --output <file>` — each of those omitted from the
 request when absent.
 
-`fetch create` accepts the full markdown-pipeline surface on top of that, which
-`fetch get` does not:
-
-| Flag                          | Effect                                                                       |
-| ----------------------------- | ---------------------------------------------------------------------------- |
-| `--markdown-mode <mode>`      | Markdown extraction mode: `article`, `raw`, `llm`.                           |
-| `--markdown-query <q>`        | BM25 query for relevance-ranked markdown filtering. Omitted → disabled.      |
-| `--markdown-links <mode>`     | Link rendering: `inline`, `references`, `none`, `text`.                      |
-| `--markdown-images <mode>`    | Image retention: `inline`, `references`, `none`, `text`.                     |
-| `--with-links-summary`        | Append a Links footer to the markdown.                                       |
-| `--with-images-summary`       | Append an Images footer to the markdown.                                     |
-| `--markdown-compact`          | Collapse excessive whitespace.                                               |
-| `--markdown-filter-images`    | Filter low-signal images.                                                    |
-| `--markdown-include-media`    | Return rich link/image objects and a tables array.                           |
-| `--markdown-include-warnings` | Include markdown-pipeline and tag-filter warnings.                           |
-| `--markdown-include-stats`    | Include a top-level stats object (chars, tokens, blocks).                    |
-| `--custom <json>`             | User payload echoed on the envelope, as a JSON object, e.g. `'{"job":"1"}'`. |
-
-Each is omitted when absent, so a server default is never materialized.
+`fetch create` and `fetch get` send only the raw-fetch options listed above.
 
 `fetch bulk create` takes the shared bulk-job flags — see
 [`bulk`](#bulk--bulk-screenshot-jobs).

package/dist/client.js

@@ -231,15 +231,29 @@ function drainBestEffort(body, abort) {
  *     envelope shape, so a flat 502 rendered `internal_error` instead of `search_provider_error`).
  *
  * The explicit `!== null` guard on the envelope check matters — `typeof null` is `'object'`.
+ *
+ * The envelope's structured `details` is mirrored too (#3538). The SDK grew that read in #2685 and
+ * this copy did not follow, so a `422 validation_error`'s `fieldErrors` — the one fact naming WHICH
+ * field the server rejected — was parsed away before `handleError()` could render it: the same
+ * drift class as #2586, in the same function. Only the envelope arm reads it, and only when it is a
+ * JSON object: the flat vendor-masked arm has no envelope to read from and must never grow a
+ * phantom `details`, and `ByteKitErrorDetails` promises something indexable, so an array or a
+ * scalar is dropped rather than surfaced. `error-parser-parity.test.ts` compares this field against
+ * the real SDK's parser on a shared corpus.
  */
 async function toApiError(response) {
     let code = 'internal_error';
     let message = response.statusText;
+    let details;
     try {
         const json = (await response.json());
         if (typeof json.error === 'object' && json.error !== null) {
             code = json.error.code ?? code;
             message = json.error.message ?? message;
+            const raw = json.error.details;
+            if (typeof raw === 'object' && raw !== null && !Array.isArray(raw)) {
+                details = raw;
+            }
         }
         else if (typeof json.error === 'string' && json.error.length > 0) {
             // The string IS the error code. `message` falls back to it only when the response carried
@@ -251,7 +265,7 @@ async function toApiError(response) {
     catch {
         // leave defaults
     }
-    return new ByteKitError(response.status, code, message);
+    return new ByteKitError(response.status, code, message, details);
 }
 /**
  * Perform the authenticated round-trip with a single bounded retry on 429, returning whatever the

package/dist/commands/fetch.d.ts

@@ -1,19 +1,5 @@
 import { Command } from 'commander';
 import { type GlobalOptions } from '../client.js';
-/** The `/v1/fetch` spec union for `format` — mirrors `FetchOpts['format']` in the SDK. */
-type FetchFormat = 'markdown' | 'html';
-/**
- * Validate `--format` locally, before any HTTP request is issued.
- *
- * The SDK's `FetchOpts.format` is narrowed to the spec union `'markdown' | 'html'`
- * (#2475), so an off-spec value like `pdf` is a compile-time error at the call site.
- * Commander runs an option's argParser during parsing — ahead of the action callback —
- * so rejecting here means the client is never built and no request is issued, and the
- * caller gets an actionable message instead of a server 422 (same convention as
- * `parseLimit` in search.ts).
- */
-export declare function parseFormat(value: string): FetchFormat;
 export declare function makeFetchCommand(getGlobal: () => GlobalOptions & {
     json: boolean;
 }): Command;
-export {};

package/dist/commands/fetch.js

@@ -1,29 +1,8 @@
-import { Command, InvalidArgumentError } from 'commander';
+import { Command } from 'commander';
 import { buildClient } from '../client.js';
 import { printResult, emitFetchResult, handleError } from '../output.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.
- *
- * The SDK's `FetchOpts.format` is narrowed to the spec union `'markdown' | 'html'`
- * (#2475), so an off-spec value like `pdf` is a compile-time error at the call site.
- * Commander runs an option's argParser during parsing — ahead of the action callback —
- * so rejecting here means the client is never built and no request is issued, and the
- * caller gets an actionable message instead of a server 422 (same convention as
- * `parseLimit` in search.ts).
- */
-export function parseFormat(value) {
-    if (!FETCH_FORMATS.includes(value)) {
-        throw new InvalidArgumentError(`--format must be one of: ${FETCH_FORMATS.join(', ')}.`);
-    }
-    return value;
-}
+import { parseIntFlag, parseCacheTtl, parseJsonFlag } from '../lib/parse-flags.js';
 export function makeFetchCommand(getGlobal) {
     const cmd = new Command('fetch').description('Fetch URL content operations');
     const bulkCmd = new Command('bulk').description('Bulk fetch operations');
@@ -82,23 +61,9 @@ export function makeFetchCommand(getGlobal) {
         .command('create')
         .description('Fetch URL content (POST)')
         .requiredOption('--url <url>', 'URL to fetch')
-        .option('--format <format>', 'Response format (markdown or html)', parseFormat)
         .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))
-        // 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) => {
@@ -108,36 +73,12 @@ export function makeFetchCommand(getGlobal) {
         // 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 {
@@ -154,7 +95,6 @@ export function makeFetchCommand(getGlobal) {
         .command('get')
         .description('Fetch URL content (GET via query params)')
         .requiredOption('--url <url>', 'URL to fetch')
-        .option('--format <format>', 'Response format (markdown or html)', parseFormat)
         .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))
@@ -166,7 +106,6 @@ export function makeFetchCommand(getGlobal) {
             const client = buildClient(g);
             const result = await client.fetch.get({
                 url: opts.url,
-                ...(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 } : {}),

package/dist/commands/scrape.js

@@ -48,7 +48,7 @@ export function makeScrapeCommand(getGlobal) {
         .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('--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 (wait_until, wait_for_selector, delay_ms) with a 400. `cookies` and `headers` are no longer accepted by any capture endpoint and 400 (#3242).', (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.
@@ -115,8 +115,6 @@ export function makeScrapeCommand(getGlobal) {
         .option('--markdown-mode <mode>', `Markdown extraction 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('--cache-ttl <ttl>', 'Cache freshness: 0, Nh (hours), or Nd (days), e.g. 48h, 2d, 0 (omitted → server default)', (v) => parseCacheTtl('--cache-ttl', v))
-        .option('--cookies <json>', `Cookies as a JSON array, e.g. '[{"name":"a","value":"b"}]' (omitted → none)`, (v) => parseJsonFlag('--cookies', v, 'array'))
-        .option('--headers <json>', `Extra request headers as a JSON object, e.g. '{"X-A":"b"}' (omitted → none)`, (v) => parseJsonFlag('--headers', v, 'object'))
         .option('--delay-ms <n>', 'Post-load delay in milliseconds before capture', (v) => parseIntFlag('--delay-ms', v))
         .option('--events <csv>', `Webhook events (comma-separated): ${SCRAPE_EVENTS.join(', ')} (omitted → server default)`, (v) => parseCsv(v).map((e) => parseEnum('--events', SCRAPE_EVENTS, e)))
         .option('--token-encoding <enc>', `Tokenizer for --token-budget: ${TOKEN_ENCODINGS.join(', ')} (omitted → server default)`, (v) => parseEnum('--token-encoding', TOKEN_ENCODINGS, v))
@@ -164,10 +162,6 @@ export function makeScrapeCommand(getGlobal) {
             body['markdown_query'] = opts.markdownQuery;
         if (opts.cacheTtl !== undefined)
             body['cache_ttl'] = opts.cacheTtl;
-        if (opts.cookies !== undefined)
-            body['cookies'] = opts.cookies;
-        if (opts.headers !== undefined)
-            body['headers'] = opts.headers;
         if (opts.delayMs !== undefined)
             body['delay_ms'] = opts.delayMs;
         if (opts.events !== undefined)

package/dist/commands/screenshots.js

@@ -346,8 +346,6 @@ export function makeScreenshotsCommand(getGlobal) {
         .option('--include-html', 'Include the rendered HTML alongside the screenshot')
         .option('--country <cc>', 'Two-letter country code to route the request through (e.g. us, de)')
         .option('--language <lang>', 'Accept-Language override (e.g. en-US)')
-        .option('--headers <json>', `Extra request headers as a JSON object, e.g. '{"X-A":"b"}' (omitted → none)`, (v) => parseJsonFlag('--headers', v, 'object'))
-        .option('--cookies <json>', `Cookies as a JSON array of {name,value,domain}, e.g. '[{"name":"a","value":"b","domain":"example.com"}]' (omitted → none)`, (v) => parseJsonFlag('--cookies', v, 'array'))
         .option('--metadata <json>', `Arbitrary metadata echoed on the screenshot envelope, as a JSON object, e.g. '{"run":"7"}' (omitted → none)`, (v) => parseJsonFlag('--metadata', v, 'object'))
         .option('--async', 'Queue the screenshot and return a job envelope immediately (no wait)')
         .option('-o, --output <file>', 'Download the captured image to this file path (use - for stdout). Not valid with --json.')
@@ -394,12 +392,8 @@ export function makeScreenshotsCommand(getGlobal) {
             body['country'] = opts.country;
         if (opts.language !== undefined)
             body['language'] = opts.language;
-        // The server defaults headers/cookies/metadata to {} / [] / {}; writing an empty
-        // container on a bare create would materialize those defaults (#2480 E1).
-        if (opts.headers !== undefined)
-            body['headers'] = opts.headers;
-        if (opts.cookies !== undefined)
-            body['cookies'] = opts.cookies;
+        // The server defaults metadata to {}; writing an empty container on a bare
+        // create would materialize that default (#2480 E1).
         if (opts.metadata !== undefined)
             body['metadata'] = opts.metadata;
         try {

package/dist/lib/parse-flags.d.ts

@@ -31,7 +31,7 @@ export declare function parseNumberFlag(flag: string, value: string): number;
 export declare function parseCacheTtl(flag: string, value: string): string;
 /**
  * Parse a JSON-object- or JSON-array-valued flag (#2545). The ONLY `JSON.parse` call site for CLI
- * flag values — every JSON-shaped flag (`--cookies`, `--headers`, `--custom`,
+ * flag values — every JSON-shaped flag (`--custom`, `--metadata`, `--defaults`,
  * `--webhook-headers`, `--options`, `--scrape-options`) routes through here, so command modules
  * carry no raw `JSON.parse` (grep-gated). Rejects malformed JSON AND a value whose top-level shape
  * does not match `expect`, with a copy-pasteable example in the message (E5).

package/dist/lib/parse-flags.js

@@ -57,7 +57,7 @@ export function parseCacheTtl(flag, value) {
 }
 /**
  * Parse a JSON-object- or JSON-array-valued flag (#2545). The ONLY `JSON.parse` call site for CLI
- * flag values — every JSON-shaped flag (`--cookies`, `--headers`, `--custom`,
+ * flag values — every JSON-shaped flag (`--custom`, `--metadata`, `--defaults`,
  * `--webhook-headers`, `--options`, `--scrape-options`) routes through here, so command modules
  * carry no raw `JSON.parse` (grep-gated). Rejects malformed JSON AND a value whose top-level shape
  * does not match `expect`, with a copy-pasteable example in the message (E5).

package/dist/lib/url-lines.d.ts

@@ -30,12 +30,12 @@ export type BulkLine = string | Record<string, unknown>;
  *
  * The rejection message for a malformed line (#2596 cr-1 / E12) names the 1-based PHYSICAL line
  * NUMBER (i.e. the line's own position in the file, counting blank lines) and the line's own KEY
- * NAMES only — never the raw line or any value. A `--file` line is where per-item `cookies`,
- * `headers`, and auth-bearing `metadata` now live (#2596), so echoing the raw line back would
- * leak session tokens and similar secrets to stderr, CI logs, and shell transcripts. Because the
- * raw line is deliberately never echoed, the line number is the ONLY locator left in the message —
- * it must be computed BEFORE blank lines are filtered out, or it silently mis-locates the bad
- * entry whenever the file contains blank lines above it (#2596 cr-2).
+ * NAMES only — never the raw line or any value. A `--file` line is where auth-bearing per-item
+ * `metadata` lives (#2596; per-item `cookies`/`headers` were removed in #3242), so echoing the
+ * raw line back would leak session tokens and similar secrets to stderr, CI logs, and shell
+ * transcripts. Because the raw line is deliberately never echoed, the line number is the ONLY
+ * locator left in the message — it must be computed BEFORE blank lines are filtered out, or it
+ * silently mis-locates the bad entry whenever the file contains blank lines above it (#2596 cr-2).
  */
 export declare function parseBulkLines(file: string): BulkLine[];
 /**

package/dist/lib/url-lines.js

@@ -24,12 +24,12 @@ import { InvalidArgumentError } from 'commander';
  *
  * The rejection message for a malformed line (#2596 cr-1 / E12) names the 1-based PHYSICAL line
  * NUMBER (i.e. the line's own position in the file, counting blank lines) and the line's own KEY
- * NAMES only — never the raw line or any value. A `--file` line is where per-item `cookies`,
- * `headers`, and auth-bearing `metadata` now live (#2596), so echoing the raw line back would
- * leak session tokens and similar secrets to stderr, CI logs, and shell transcripts. Because the
- * raw line is deliberately never echoed, the line number is the ONLY locator left in the message —
- * it must be computed BEFORE blank lines are filtered out, or it silently mis-locates the bad
- * entry whenever the file contains blank lines above it (#2596 cr-2).
+ * NAMES only — never the raw line or any value. A `--file` line is where auth-bearing per-item
+ * `metadata` lives (#2596; per-item `cookies`/`headers` were removed in #3242), so echoing the
+ * raw line back would leak session tokens and similar secrets to stderr, CI logs, and shell
+ * transcripts. Because the raw line is deliberately never echoed, the line number is the ONLY
+ * locator left in the message — it must be computed BEFORE blank lines are filtered out, or it
+ * silently mis-locates the bad entry whenever the file contains blank lines above it (#2596 cr-2).
  */
 export function parseBulkLines(file) {
     return readFileSync(file, 'utf8')

package/dist/output.d.ts

@@ -204,6 +204,14 @@ export declare function printResult(data: unknown, jsonMode: boolean): void;
  * error carrying an unrelated string `.code` (a Node errno error) gets NO code suffix. When a
  * status is present but no code (a hand-built error), the suffix is `(status: <n>)` with no empty
  * placeholder — never `(, status: <n>)`.
+ *
+ * When the error carries a structured `details` object — which a `422 validation_error` populates
+ * with zod's `fieldErrors`, naming WHICH field was rejected and what it accepts — a bounded
+ * `Details:` block follows on the SAME stderr write (#3538, see {@link detailBlock}). An error
+ * with no renderable `details` is byte-identical to before: one line, same text, same exit code.
+ *
+ * Everything goes to stderr, so `--json` stdout stays pipe-clean without this function needing to
+ * know which output mode is in effect.
  */
 export declare function handleError(err: unknown): void;
 export {};

package/dist/output.js

@@ -398,6 +398,151 @@ function errorCode(err) {
     const raw = err.code;
     return typeof raw === 'string' && raw.length > 0 ? raw : undefined;
 }
+/**
+ * Human-mode bound on the rendered `details` block (#3538 E1).
+ *
+ * `details` is typed `unknown` on the wire — the API spec declares no schema for it — so nothing
+ * stops it from being arbitrarily large or deeply nested. Ten lines of at most 200 characters caps
+ * the block at ~2 KB: wider and longer than every validation envelope the API is observed to send
+ * (a handful of fields, one sentence each, so nothing real is ever truncated), and small enough
+ * that a pathological payload lands as a readable block rather than a multi-KB JSON dump.
+ */
+const DETAIL_MAX_LINES = 10;
+const DETAIL_MAX_LINE_CHARS = 200;
+/**
+ * Bound on the descent inside {@link detailValueText}: the array walk (#3633) and the object
+ * serialization in {@link detailJson} (#3647), which are the function's two recursive arms.
+ *
+ * The two caps above bound the block that is PRINTED; they are applied in {@link detailBlock},
+ * after the walk that builds each line has already finished, so neither of them bounds the walk
+ * itself. A `details` payload nested a few thousand arrays deep survives `JSON.parse` on the CLI's
+ * Node runtime, so a server can deliver one, and the descent overflowed the stack — the CLI dying
+ * with a raw `RangeError` trace instead of its documented one-line error.
+ *
+ * Eight levels is far past anything with meaning to render: the live shapes bottom out at ONE
+ * array level below the key {@link detailEntries} flattens, and a field→messages list has nowhere
+ * deeper to go. Below the bound the descent stops and emits the ellipsis, so an over-deep value is
+ * elided in the same visible way an over-long one is — never dropped, which would render a
+ * legitimate list as silence.
+ */
+const DETAIL_MAX_DEPTH = 8;
+/** A JSON object — the only `details` shape that has field→messages structure to render. */
+function isDetailRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * One detail value as a single line of text.
+ *
+ * Arrays are the zod `fieldErrors` shape — several messages about one field — and are joined with
+ * `; `. An object at this depth is already the SECOND level of nesting (see {@link detailEntries})
+ * and is emitted as compact JSON rather than flattened further: past that depth the key path is
+ * longer than the value it names.
+ *
+ * `depth` counts array levels already descended and is bounded by {@link DETAIL_MAX_DEPTH} (#3633);
+ * the object arm carries the SAME bound through {@link detailJson} (#3647), and every remaining arm
+ * terminates on its own.
+ */
+function detailValueText(value, depth = 0) {
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value)) {
+        if (depth >= DETAIL_MAX_DEPTH)
+            return '…';
+        return value
+            .map((item) => detailValueText(item, depth + 1))
+            .filter((t) => t !== '')
+            .join('; ');
+    }
+    if (isDetailRecord(value))
+        return detailJson(value);
+    return String(value);
+}
+/**
+ * Compact JSON for an object detail value, bounded to {@link DETAIL_MAX_DEPTH} nesting levels
+ * (#3647).
+ *
+ * #3633 bounded the array descent above; this arm used a bare `JSON.stringify`, which is itself
+ * natively recursive and overflowed the stack on its own. The one-level flatten in
+ * {@link detailEntries} bounds the WALK, not the SERIALIZATION: `{a: {b: X}}` yields the single
+ * entry `a.b` whose value `X` was handed straight to `JSON.stringify`, which then recursed to the
+ * bottom of `X` — the same raw `RangeError` in place of the documented one-line error, from the
+ * arm next door.
+ *
+ * The bound is the same eight levels and is applied by a replacer, so everything shallower than it
+ * serializes through the untouched native path and renders byte-identically: escaping, key order,
+ * dropped `undefined`s, `toJSON`. `ancestors` is the chain of holders the replacer is currently
+ * inside — `this` is the holder of each visited key, so popping back to it yields the depth — and
+ * only a value that would RECURSE is elided, which is what keeps a leaf sitting at the bound
+ * rendering exactly as the array arm's leaf at the same depth does.
+ */
+function detailJson(value) {
+    const ancestors = [];
+    return JSON.stringify(value, function (_key, entry) {
+        while (ancestors.length > 0 && ancestors[ancestors.length - 1] !== this)
+            ancestors.pop();
+        if (ancestors.length >= DETAIL_MAX_DEPTH && typeof entry === 'object' && entry !== null) {
+            return '…';
+        }
+        ancestors.push(entry);
+        return entry;
+    });
+}
+/**
+ * The `key → value` pairs to render, flattened by exactly ONE level.
+ *
+ * Two `details` shapes are live (both pinned verbatim from staging by the SDK's parser suite):
+ * a 422 `validation_error` carries zod's `flatten()` output — `{formErrors, fieldErrors}` — where
+ * the field name lives one level down under `fieldErrors`; a 400 `invalid_url` carries a flat
+ * record (`{url, field, reason}`). One level of flattening renders both with a single rule and no
+ * per-shape special case: `fieldErrors.formats: …` and `url: …` respectively.
+ */
+function detailEntries(details) {
+    const entries = [];
+    for (const [key, value] of Object.entries(details)) {
+        if (isDetailRecord(value)) {
+            for (const [inner, innerValue] of Object.entries(value)) {
+                entries.push([`${key}.${inner}`, innerValue]);
+            }
+        }
+        else {
+            entries.push([key, value]);
+        }
+    }
+    return entries;
+}
+/**
+ * The stderr block that renders a `ByteKitError.details` (#3538), or `''` when there is nothing to
+ * render.
+ *
+ * A `422 validation_error` envelope carries `details.fieldErrors` naming the offending field and
+ * its allowed values; the CLI printed only `message`/`code`/`status`, so the one fact the caller
+ * needed was dropped and reproducing the call with curl was the only recourse.
+ *
+ * Returns `''` — leaving the rendered line byte-identical to before — whenever `details` is
+ * absent, is not a JSON object (the untyped spec field permits a string, an array, `null`), or
+ * carries no non-empty value. `formErrors: []` on a passing form is the ordinary case of the last
+ * one: an empty bag is not a reason.
+ */
+function detailBlock(details) {
+    if (!isDetailRecord(details))
+        return '';
+    const lines = detailEntries(details).flatMap(([key, value]) => {
+        const text = detailValueText(value);
+        return text === '' ? [] : [`  ${key}: ${text}`];
+    });
+    if (lines.length === 0)
+        return '';
+    const shown = lines.length > DETAIL_MAX_LINES
+        ? [
+            ...lines.slice(0, DETAIL_MAX_LINES - 1),
+            `  … and ${lines.length - (DETAIL_MAX_LINES - 1)} more`,
+        ]
+        : lines;
+    return [
+        'Details:',
+        ...shown.map((line) => line.length > DETAIL_MAX_LINE_CHARS ? `${line.slice(0, DETAIL_MAX_LINE_CHARS - 1)}…` : line),
+    ].join('\n');
+}
 /**
  * Handle a CLI command error: print to stderr and signal exit 1.
  *
@@ -427,6 +572,14 @@ function errorCode(err) {
  * error carrying an unrelated string `.code` (a Node errno error) gets NO code suffix. When a
  * status is present but no code (a hand-built error), the suffix is `(status: <n>)` with no empty
  * placeholder — never `(, status: <n>)`.
+ *
+ * When the error carries a structured `details` object — which a `422 validation_error` populates
+ * with zod's `fieldErrors`, naming WHICH field was rejected and what it accepts — a bounded
+ * `Details:` block follows on the SAME stderr write (#3538, see {@link detailBlock}). An error
+ * with no renderable `details` is byte-identical to before: one line, same text, same exit code.
+ *
+ * Everything goes to stderr, so `--json` stdout stays pipe-clean without this function needing to
+ * know which output mode is in effect.
  */
 export function handleError(err) {
     if (err instanceof Error) {
@@ -440,7 +593,8 @@ export function handleError(err) {
         else if (code !== undefined) {
             suffix = ` (${code})`;
         }
-        console.error(`Error: ${err.message}${suffix}`);
+        const details = detailBlock(err.details);
+        console.error(`Error: ${err.message}${suffix}${details === '' ? '' : `\n${details}`}`);
     }
     else {
         console.error(`Error: ${String(err)}`);

package/dist/test-helpers/build-scratch.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Build a scratch COPY of packages/cli (issue #3270), mirroring
+ * `packages/sdk-typescript/src/test-helpers/build-scratch.ts` (issue #2423 cr-2).
+ *
+ * `entrypoint.test.ts` and `queued-raw-flush.test.ts` both need a built `dist/index.js` and both
+ * used to rebuild the shared, workspace `packages/cli/dist` in place whenever it was missing —
+ * racing each other's build under vitest's default parallel file execution on a checkout with no
+ * prior `pnpm build` (one file's `existsSync` check passes while the other's build is still
+ * writing `dist/`).
+ *
+ * So instead: copy the tracked, on-disk source (never `dist/`, `tsconfig.tsbuildinfo`, or
+ * `node_modules` — those are the mutable/heavy bits) into a scratch tree that mirrors the real
+ * repo's relative layout (`<scratch>/tsconfig.base.json`, `<scratch>/packages/cli/**`), symlink in
+ * the real `node_modules` (read-only from the child process's point of view — nothing here writes
+ * back into it), and let the caller run the package's own `npm run build` / `npm pack` scripts
+ * against that copy. The real `packages/cli/dist` is never read and never written by either suite.
+ *
+ * @param pkgRoot packages/cli (the real, workspace-shared package root)
+ * @param repoRoot the monorepo root (for tsconfig.base.json, which the scratch tsconfig extends)
+ * @param scratchRoot a fresh tmp dir (e.g. from mkdtempSync) to build the scratch tree under
+ * @returns the scratch package dir (`<scratchRoot>/packages/cli`)
+ */
+export declare function createBuildScratch(pkgRoot: string, repoRoot: string, scratchRoot: string): string;

package/dist/test-helpers/build-scratch.js

@@ -0,0 +1,41 @@
+// Test-only fixture, compiled like any other `src` file (not excluded from the tsc build) — same
+// tradeoff sdk-typescript's own copy of this helper documents: a small compiled fixture lands in
+// `dist/test-helpers/`, but excluding it breaks ESLint's typed-lint project-service resolution.
+import { mkdirSync, cpSync, copyFileSync, symlinkSync } from 'node:fs';
+import { basename, join } from 'node:path';
+/**
+ * Build a scratch COPY of packages/cli (issue #3270), mirroring
+ * `packages/sdk-typescript/src/test-helpers/build-scratch.ts` (issue #2423 cr-2).
+ *
+ * `entrypoint.test.ts` and `queued-raw-flush.test.ts` both need a built `dist/index.js` and both
+ * used to rebuild the shared, workspace `packages/cli/dist` in place whenever it was missing —
+ * racing each other's build under vitest's default parallel file execution on a checkout with no
+ * prior `pnpm build` (one file's `existsSync` check passes while the other's build is still
+ * writing `dist/`).
+ *
+ * So instead: copy the tracked, on-disk source (never `dist/`, `tsconfig.tsbuildinfo`, or
+ * `node_modules` — those are the mutable/heavy bits) into a scratch tree that mirrors the real
+ * repo's relative layout (`<scratch>/tsconfig.base.json`, `<scratch>/packages/cli/**`), symlink in
+ * the real `node_modules` (read-only from the child process's point of view — nothing here writes
+ * back into it), and let the caller run the package's own `npm run build` / `npm pack` scripts
+ * against that copy. The real `packages/cli/dist` is never read and never written by either suite.
+ *
+ * @param pkgRoot packages/cli (the real, workspace-shared package root)
+ * @param repoRoot the monorepo root (for tsconfig.base.json, which the scratch tsconfig extends)
+ * @param scratchRoot a fresh tmp dir (e.g. from mkdtempSync) to build the scratch tree under
+ * @returns the scratch package dir (`<scratchRoot>/packages/cli`)
+ */
+export function createBuildScratch(pkgRoot, repoRoot, scratchRoot) {
+    const pkgDest = join(scratchRoot, 'packages/cli');
+    mkdirSync(join(scratchRoot, 'packages'), { recursive: true });
+    copyFileSync(join(repoRoot, 'tsconfig.base.json'), join(scratchRoot, 'tsconfig.base.json'));
+    cpSync(pkgRoot, pkgDest, {
+        recursive: true,
+        filter: (src) => {
+            const name = basename(src);
+            return name !== 'node_modules' && name !== 'dist' && name !== 'tsconfig.tsbuildinfo';
+        },
+    });
+    symlinkSync(join(pkgRoot, 'node_modules'), join(pkgDest, 'node_modules'), 'dir');
+    return pkgDest;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hunt-labs/bytekit-cli",
-  "version": "0.8.1",
+  "version": "0.9.1",
   "description": "ByteKit CLI — wraps @hunt-labs/bytekit-sdk as shell subcommands",
   "license": "MIT",
   "type": "module",
@@ -41,7 +41,7 @@
   ],
   "dependencies": {
     "commander": "^12.0.0",
-    "@hunt-labs/bytekit-sdk": "^0.7.1"
+    "@hunt-labs/bytekit-sdk": "^0.9.1"
   },
   "scripts": {
     "build": "rm -rf dist tsconfig.tsbuildinfo && tsc",