@hunt-labs/bytekit-cli 0.7.1 → 0.8.1

package/CHANGELOG.md

@@ -10,6 +10,95 @@ today, see [README.md](./README.md), which remains the authoritative usage guide
 
 ## [Unreleased]
 
+## [0.8.1] - 2026-08-13
+
+### Fixed
+
+- **`bytekit search` explains a malformed `200` instead of leaking a `TypeError`.** A server
+  answering `200 {"ok":true}` — a proxy, a stub, a future envelope change — drove the human-mode
+  renderer into `Error: response.results is not iterable`, which named an internal expression
+  rather than the field the body was missing. It now reports, on one line and with no stack trace,
+  `search: the response carries no "results" array — the server returned an unexpected 200 body. Re-run with --json to inspect it.`
+  and exits `1`. A `results` value that is present but not an array is caught by the same gate: a
+  **string** was previously iterated CHARACTER BY CHARACTER, printing one garbled row per character
+  and exiting `0`. Unchanged: an empty `results: []` is still a successful zero-hit search that
+  prints nothing and exits `0`; valid responses render byte-identically; and `--json` never reaches
+  the renderer, so it keeps dumping the raw body at exit `0` — which is how you inspect an
+  unexpected body.
+
+### Added
+
+- **`screenshots … -o <file>` now says so when the filename contradicts the captured format.**
+  `--format` is omitted far more often than not and the server default is **jpeg**, so
+  `bytekit screenshots create --url … -o shot.png` wrote JPEG bytes into a `.png`-named file
+  silently, at exit `0`; `screenshots get` has no `--format` flag at all, so it could not even be
+  told what it was downloading. Both now print one advisory line to **stderr** —
+  `Note: the screenshot was captured as jpeg, but shot.png names .png. The file holds jpeg bytes — pass --format png to capture it as png.`
+  The captured format is read from the artifact URL's own path, which is the only place the CLI can
+  observe it. **Advisory, not enforcement:** the bytes written and the exit code are unchanged, and
+  the note goes to stderr, so `-o -` pipelines and stdout redirects stay byte-identical. It stays
+  silent unless both the destination and the artifact name a recognized image format and the two
+  differ — `.jpg` and `.jpeg` are the same format, and an extension-less destination, a non-image
+  extension, `-o -`, or an artifact URL with no usable extension all make no claim to contradict. A
+  not-ready poll is untouched: it still prints its bare id and poll note at exit `2`.
+
+### Changed
+
+- **The README now documents the whole flag surface, and says which reference wins.** Every flag
+  worked and every flag appeared in `--help`; the README simply framed subsets as exhaustive, so
+  `bulk create`'s `--webhook-secret` / `--defaults` / `--metadata`, `scrape bulk create`'s
+  `--custom`, `sitemap create`'s `--webhook-url` / `--webhook-secret` / `--cache-ttl` /
+  `--compact` / `--process` / `--metadata`, `monitors create` and `monitors update`'s `--cron`
+  (required with `--interval-type cron`) and `--metadata` plus the rest of `update`'s surface,
+  `fetch create`'s ten markdown flags and `--custom`, and `screenshots create`'s `--headers` /
+  `--cookies` / `--metadata` were all undocumented. All of them are documented now, and a note at
+  the top of the README states that `--help` is the authoritative flag reference. **Required flags
+  are marked as such** — `--file` and `--webhook-url` on all three bulk creators, `--url` /
+  `--interval-type` / `--webhook-url` on `monitors create`, and `--url` on `scrape create`,
+  `screenshots create`, `sitemap create` and both `fetch` verbs — so no reader mistakes one for
+  optional. Note in particular that a **bulk job has no poll-only mode**: `--webhook-url` is
+  mandatory there, unlike on `sitemap create` where omitting it really does mean poll-only. A test
+  asserts the parity in the direction that matters — every flag the parser accepts must appear in
+  the README — so this cannot drift again silently. No command, flag or behavior changed.
+
+- **Alignment-release note, carried forward from this version's original cut.** `0.8.0` published
+  to npm at `2026-08-11T21:18:01.304Z`. Doc comments in `src/client.ts` and
+  `src/package-version.ts` were reworded **after** the commit that introduced the `0.8.0` version
+  string — they had re-spelled the `X-ByteKit-Client` header name in prose, which issue #2906's
+  pre-merge gate 1 counts. No command, flag, exit code, or runtime behavior differs from `0.8.0`
+  on account of _those_ comments.
+
+  `0.8.1` was cut for that reason because `check-release-drift` (#2680) is version-gated and
+  anchors on the commit that introduced a version, not on the commit whose tree was actually
+  published. Once `0.8.0` reached npm, any shipped-file change after that anchor reads as
+  post-release drift. Bumping moves the anchor past those comments. `0.8.1` had not yet reached
+  npm when the entries above landed, so they ride this same pending release rather than stranding
+  it as a never-published version.
+
+## [0.8.0] - 2026-08-11
+
+### Added
+
+- **Every outgoing request now carries `X-ByteKit-Client: cli/<version>`.** The CLI identifies
+  itself with the sanctioned `client_surface` marker (issue #2906, slice 3 of #2701), so `bytekit`
+  usage is distinguishable in ByteKit's own analytics from both raw API calls (`api_direct`) and
+  programmatic `@hunt-labs/bytekit-sdk` usage (`sdk_ts`) instead of being counted as one of them.
+  `cli` is a member of the closed `client_surface` vocabulary declared in issue #2904; the version
+  affix is this package's own version, resolved from `package.json` at runtime — the same value
+  `bytekit --version` prints.
+
+  Set at exactly ONE place — the header literal inside the private transport core all three CLI
+  transports funnel through — so it rides on every command, on the JSON path, on the raw
+  `/v1/fetch` path, and on the 429 retry attempt alike. **Nothing else about a request changed:**
+  same `Authorization` and `Content-Type`, same body bytes, same per-attempt abort budget, same
+  single-retry 429 behavior, same error taxonomy, same exit codes and output shapes. The marker
+  carries no user data and cannot be set, overridden or read from the command line — `--headers`
+  is a _scrape_ option that travels in the request body to the captured site, and never touches
+  the CLI's own request headers.
+
+  Minor rather than patch because the wire format of every request changes, even though no
+  documented command behavior does. A gateway that does not yet recognize the header ignores it.
+
 ## [0.7.1] - 2026-08-10
 
 ### Changed
@@ -429,7 +518,7 @@ Additive, lower-risk release — no breaking changes to existing commands.
   `workspace:^`, added `engines`, `keywords`, `homepage`, `bugs`, `README.md`,
   `LICENSE`, and an MIT `license` field.
 
-## [0.1.0] - 2026
+## [0.1.0] - 2026-07-13
 
 ### Added
 

package/README.md

@@ -4,6 +4,12 @@ Command-line interface for the [ByteKit](https://bytekit.com) API — scrape,
 fetch, screenshot, search, crawl sitemaps, and manage page monitors from your
 shell. Wraps [`@hunt-labs/bytekit-sdk`](https://www.npmjs.com/package/@hunt-labs/bytekit-sdk).
 
+> **`--help` is the authoritative flag reference.** Every command and subcommand
+> accepts it — `bytekit sitemap create --help`, `bytekit monitors update --help` —
+> and the list it prints is generated from the code that parses your argv, so it
+> is never out of date. This README documents the same surface in prose for
+> reading; where the two ever disagree, `--help` is right.
+
 ## Install
 
 ```bash
@@ -86,9 +92,13 @@ bytekit scrape get sc_123abc
 bytekit scrape bulk create --file urls.txt --webhook-url https://your.app/hooks/bytekit
 ```
 
-`scrape create` also accepts the full `ScrapeRequest` surface, each flag omitted
-from the request when absent (a boolean flag never sends `false`, so a server
-default is never materialized):
+`scrape bulk create` takes the shared bulk-job flags plus `--custom` — see
+[`bulk`](#bulk--bulk-screenshot-jobs).
+
+`scrape create` **requires** `--url <url>`. It also accepts the full
+`ScrapeRequest` surface below, each of those flags omitted from the request when
+absent (a boolean flag never sends `false`, so a server default is never
+materialized):
 
 | Flag                                                   | Effect                                                                                                                                                                                             |
 | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -183,9 +193,33 @@ 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 accept `--country <cc>`, `--timeout-ms <n>`, and `--cache-ttl <ttl>`
-(`0`, `Nh`, or `Nd`), each omitted when absent. `--markdown-mode`
-(`article`, `raw`, `llm`) is `fetch create` only.
+Both verbs **require** `--url <url>`. Both also accept `--format <format>`
+(`markdown` or `html`), `--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 bulk create` takes the shared bulk-job flags — see
+[`bulk`](#bulk--bulk-screenshot-jobs).
 
 ### `search` — ranked web search
 
@@ -206,7 +240,8 @@ bytekit screenshots create --url https://example.com --device mobile --format pn
 bytekit screenshots get ss_123abc -o shot.png
 ```
 
-`screenshots create` accepts `--device` (`desktop`, `mobile`), `--viewport WxH`
+`screenshots create` **requires** `--url <url>`. It also accepts `--device`
+(`desktop`, `mobile`), `--viewport WxH`
 (e.g. `1280x720`), `--format` (`jpeg`, `png`), `--quality <n>`, `--wait-until`
 (`load`, `domcontentloaded`, `networkidle`), `--clip x,y,w,h`, and `--async`
 (queue and return a job envelope). Each flag is omitted from the request when
@@ -214,7 +249,10 @@ absent.
 
 It also accepts `--wait-for-selector <sel>`, `--delay-ms <n>`,
 `--device-scale-factor` (`1` or `2`), `--dark-mode`, `--include-html`,
-`--country <cc>`, `--language <lang>`, and three **tri-state** blocker pairs:
+`--country <cc>`, `--language <lang>`, three JSON flags — `--headers <json>`
+(extra request headers as an object, e.g. `'{"X-A":"b"}'`), `--cookies <json>`
+(an array of `{name,value,domain}`), and `--metadata <json>` (echoed back on the
+screenshot envelope) — and three **tri-state** blocker pairs:
 `--block-ads` / `--no-block-ads`, `--block-cookie-banners` /
 `--no-block-cookie-banners`, and `--scroll` / `--no-scroll`. Each of these three
 defaults to `true` server-side, so passing neither half omits the key entirely
@@ -227,6 +265,23 @@ stdout). Because `-o` writes BINARY on `screenshots`, it cannot be combined with
 `--async` + `-o` prints the queued job envelope and skips the download (the
 image is not ready yet).
 
+**`-o` never converts — it names the file, `--format` names the bytes.** The
+server default format is **jpeg**, so `-o shot.png` on a capture that did not
+pass `--format png` writes JPEG bytes into a `.png`-named file. When the
+destination's extension and the captured format disagree, the CLI prints one
+advisory line to stderr and downloads anyway:
+
+```text
+Note: the screenshot was captured as jpeg, but shot.png names .png.
+The file holds jpeg bytes — pass --format png to capture it as png.
+```
+
+The bytes written and the exit code are unchanged — it is a note, not a refusal,
+and it goes to stderr so `-o -` pipelines and stdout redirects stay
+byte-identical. It stays silent when the two agree (`.jpg` and `.jpeg` are the
+same format), and when the destination makes no format claim at all (`-o -`, no
+extension, or a non-image extension).
+
 ### `bulk` — bulk screenshot jobs
 
 ```bash
@@ -237,8 +292,36 @@ bytekit bulk cancel "$bulk_id"
 bytekit bulk screenshots list "$bulk_id"
 ```
 
-`urls.txt` is newline-delimited: one plain URL (or `{"url":"https://..."}`) per line.
-`bulk cancel <id>` stops an in-flight job.
+`urls.txt` is newline-delimited: one plain URL (or `{"url":"https://..."}`) per
+line. A line whose only key is `url` is sent as a bare URL string; any line with
+additional keys switches that entry to the per-item shape. `bulk cancel <id>`
+stops an in-flight job; `bulk get <id>` and `bulk screenshots list <id>` take no
+flags.
+
+The three bulk-job creators — `bulk create`, `scrape bulk create` and
+`fetch bulk create` — share one flag set:
+
+| Flag                        | Effect                                                                                                 |
+| --------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `--file <path>`             | **Required.** The newline-delimited input file described above.                                        |
+| `--webhook-url <url>`       | **Required.** HTTPS webhook notified when the job completes.                                           |
+| `--webhook-secret <secret>` | HMAC secret used to sign that completion webhook. Omitted → unsigned.                                  |
+| `--defaults <json>`         | Defaults applied to every entry, as a JSON object. Omitted → none.                                     |
+| `--metadata <json>`         | Arbitrary metadata echoed on the job envelope, as a JSON object, e.g. `'{"run":"7"}'`. Omitted → none. |
+
+A bulk job has **no poll-only mode**. `--file` and `--webhook-url` are both
+required on all three creators — omitting either is a usage error raised before
+any request is sent (`error: required option '--webhook-url <url>' not
+specified`), and the API declares `webhook_url` required as well. The three
+optional flags are omitted from the request when absent.
+
+`--defaults` is validated differently per endpoint: `bulk` rejects unknown keys
+with a `422`, while `scrape bulk` and `fetch bulk` ignore them — and `fetch bulk`
+additionally rejects the browser-only keys (`cookies`, `wait_until`,
+`wait_for_selector`, `delay_ms`) with a `400`.
+
+`scrape bulk create` adds one flag the other two do not have: `--custom <json>`,
+a user payload echoed on every scrape entry (a per-entry value in `--file` wins).
 
 ### `monitors` — watch a page for changes
 
@@ -260,14 +343,34 @@ each omitted when absent.
 page through a monitor's capture history — pass the response's `next_cursor`
 back as `--cursor` to fetch the next page. Both flags are omitted when absent.
 
-`monitors update` gains `--status` (`active` | `paused` — pause and resume from
-the shell), `--change-threshold <pct>` (accepts a float), `--notify-on`
-(`change`, `every`), `--webhook-secret <secret>`, and three JSON-object flags:
-`--webhook-headers`, `--options`, and `--scrape-options` (e.g.
-`--options '{"device":"mobile"}'`). `monitors create` accepts the same set plus
-`--type` (`screenshot` | `scrape`). `--type` is **create-only** — a monitor's
-type is immutable, so `monitors update` deliberately has no `--type`. Every flag
-is omitted from the request when absent.
+`monitors create` and `monitors update` share almost all of their flags. On
+`update` every one is optional and omitted from the request when absent, so
+`monitors update` changes only what you name. Three are **required on `create`**
+and marked below:
+
+| Flag                        | Effect                                                                                     |
+| --------------------------- | ------------------------------------------------------------------------------------------ |
+| `--url <url>`               | **Required on `create`.** URL to monitor.                                                  |
+| `--interval-type <type>`    | **Required on `create`.** Check interval: `hourly`, `daily`, `weekly`, or `cron`.          |
+| `--cron <expr>`             | Cron expression — **required** when `--interval-type` is `cron`, e.g. `'0 * * * *'`.       |
+| `--webhook-url <url>`       | **Required on `create`.** HTTPS webhook notified on change.                                |
+| `--change-threshold <pct>`  | Change percentage that triggers a notification (accepts a float).                          |
+| `--notify-on <event>`       | When to notify: `change`, `every`.                                                         |
+| `--webhook-secret <secret>` | HMAC secret for webhook signature verification.                                            |
+| `--webhook-headers <json>`  | Extra webhook headers as a JSON object, e.g. `'{"X-Sig":"abc"}'`.                          |
+| `--options <json>`          | Screenshot-monitor options as a JSON object, e.g. `--options '{"device":"mobile"}'`.       |
+| `--scrape-options <json>`   | Scrape-monitor options as a JSON object (`--type scrape` only).                            |
+| `--metadata <json>`         | Arbitrary metadata echoed on the monitor envelope, as a JSON object, e.g. `'{"run":"7"}'`. |
+
+Two flags are not shared. `--type` (`screenshot` | `scrape`) is **create-only** —
+a monitor's type is immutable, so `monitors update` deliberately has none.
+`--status` (`active` | `paused`, to pause and resume from the shell) is
+**update-only**.
+
+```bash
+bytekit monitors create --url https://example.com/pricing --interval-type cron \
+  --cron '0 * * * *' --webhook-url https://your.app/hooks/bytekit
+```
 
 ### `sitemap` — crawl a site's URL graph
 
@@ -276,8 +379,24 @@ bytekit sitemap create --url https://example.com --strategy deep --max-depth 3 -
 bytekit sitemap get sm_123abc
 ```
 
-`sitemap create` accepts `--strategy` (`quick`, `standard`, `deep`),
-`--max-depth <n>`, and `--max-urls <n>`, each omitted when absent.
+`sitemap get <id>` takes no flags. `sitemap create` accepts:
+
+| Flag                        | Effect                                                                                                                                  |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `--url <url>`               | **Required.** Root URL to crawl.                                                                                                        |
+| `--strategy <strategy>`     | Crawl strategy: `quick`, `standard`, `deep`. Omitted → server default `standard`.                                                       |
+| `--max-depth <n>`           | Maximum crawl depth, 1–5. Omitted → server default `2`.                                                                                 |
+| `--max-urls <n>`            | Maximum URLs to collect. Omitted → server default `5000`.                                                                               |
+| `--webhook-url <url>`       | HTTPS webhook notified when the crawl completes. Omitted → poll-only, no delivery.                                                      |
+| `--webhook-secret <secret>` | HMAC secret used to sign that completion webhook. Omitted → unsigned.                                                                   |
+| `--cache-ttl <ttl>`         | Cache freshness: `0`, `Nh` (hours), or `Nd` (days), e.g. `48h`, `30d`. Omitted → server default `30d`; max `90d`, enforced server-side. |
+| `--compact`                 | Return a compact result payload. Omitted → server default off.                                                                          |
+| `--process <json>`          | Post-crawl processing directive as a JSON object, e.g. `'{"action":"summarize"}'`. Omitted → none.                                      |
+| `--metadata <json>`         | Arbitrary metadata echoed on the job envelope, as a JSON object, e.g. `'{"run":"7"}'`. Omitted → none.                                  |
+
+Only `--url` is required; every other flag is omitted from the request when
+absent. Unlike a bulk job, a sitemap crawl really is poll-only without
+`--webhook-url`.
 
 ### `account` — account details
 

package/dist/client.js

@@ -1,4 +1,5 @@
 import { ByteKit, ByteKitError, ByteKitConnectionError } from '@hunt-labs/bytekit-sdk';
+import { PACKAGE_VERSION } from './package-version.js';
 /**
  * The API host the SDK itself defaults to. The SDK's copy is module-private, so the CLI declares
  * its own and always passes an explicit `baseUrl` to the constructor — that way the SDK client and
@@ -289,6 +290,26 @@ async function sendWithRetry(apiKey, baseUrl, timeoutMs, method, path, body, rea
             headers: {
                 Authorization: `Bearer ${apiKey}`,
                 'Content-Type': 'application/json',
+                // The `client_surface` marker (issue #2906, slice 3 of #2701). THE CLI'S ONLY EMIT SITE:
+                // all three CLI transports funnel through this function, and this literal is rebuilt
+                // inside the retry loop, so the 429 retry attempt carries it too (E4) without a second
+                // site to keep in sync.
+                //
+                // The header name below (`CLIENT_SURFACE_HEADER`) and the closed surface vocabulary
+                // (`CLIENT_SURFACES`) are declared in `@bytekit/analytics-contract` — deliberately spelled
+                // as literals here rather than imported, because that package must never become a runtime
+                // dependency of the published CLI (#2906 E6). `__tests__/client-surface-marker.test.ts`
+                // imports the contract as a TEST-ONLY devDependency and binds these literals to the
+                // registry, which is what keeps the two from drifting.
+                //
+                // Grep gate 1 (#2906) counts occurrences of the header name in `src/` outside tests and
+                // expects exactly ONE — so this comment names the CONSTANT rather than re-spelling the
+                // string, and the single occurrence below is the emit site itself.
+                //
+                // The version affix comes from the package manifest via the shared `PACKAGE_VERSION`
+                // helper — the same value commander reports for `--version` — never a second hardcoded
+                // version string.
+                'X-ByteKit-Client': `cli/${PACKAGE_VERSION}`,
             },
         };
         if (body !== undefined) {

package/dist/commands/screenshots.d.ts

@@ -12,6 +12,32 @@ export declare function parseClip(value: string): {
     width: number;
     height: number;
 };
+/**
+ * The advisory note for a `-o` destination whose extension contradicts the captured format, or
+ * undefined when there is nothing to say (#2956 item 3).
+ *
+ * THE DEFECT: `--format` is omitted far more often than not, and the server default is **jpeg** —
+ * so `screenshots create --url … -o shot.png` wrote JPEG bytes into a `.png`-named file, silently,
+ * at exit 0. The mislabelled file then propagated to whatever consumed it next. `screenshots get`
+ * has no `--format` flag at all, so it could not even be told what it was downloading.
+ *
+ * ADVISORY, NOT ENFORCEMENT — this returns a message; the caller writes it to STDERR and proceeds.
+ * The bytes on disk and the exit code are untouched, because the caller may well have meant it
+ * (`-o` is also how you rename an artifact), and because refusing the write would throw away a
+ * capture that was already taken and billed. It stays on the `-o` write path rather than moving
+ * into `downloadArtifact`: that helper is format-agnostic and has no business knowing about image
+ * extensions.
+ *
+ * Silent unless BOTH sides name a recognized image format AND they differ. Nothing to compare —
+ * `-o -` (stdout, no filename to mislabel), an extension-less or non-image destination, an
+ * artifact URL with no usable extension — means no note, never a guessed one.
+ *
+ * `-o -` needs no special case of its own: the literal `-` carries no extension, so
+ * {@link formatFromPath} already returns undefined for it. An explicit early return was written
+ * first and then removed — no mutation of it could turn a test red, which is the definition of a
+ * line that guards nothing. The stdout case stays PINNED by a test either way.
+ */
+export declare function formatMismatchNote(imageUrl: string, dest: string): string | undefined;
 export declare function makeScreenshotsCommand(getGlobal: () => GlobalOptions & {
     json: boolean;
 }): Command;

package/dist/commands/screenshots.js

@@ -99,6 +99,91 @@ function notReadyScreenshot(result) {
         return undefined;
     return { id: obj.id, status };
 }
+/**
+ * Image extensions this CLI recognizes, mapped to their canonical format name.
+ *
+ * `jpg` and `jpeg` are the SAME format under two spellings — collapsing them here is what keeps
+ * the note off `-o shot.jpg`, which is the commonest spelling of a perfectly correct destination.
+ * The set is deliberately small: it exists to decide whether a name makes a FORMAT CLAIM at all,
+ * and an extension outside it (`.bin`, `.tmp`, none) makes none.
+ */
+const IMAGE_EXTENSIONS = {
+    jpg: 'jpeg',
+    jpeg: 'jpeg',
+    png: 'png',
+};
+/**
+ * The canonical image format named by a path's extension, or undefined when it names none.
+ *
+ * Reads the extension off the last path SEGMENT so a directory containing a dot cannot supply one,
+ * and requires a non-empty stem so a dotfile (`.png`) is a name, not an extension.
+ */
+function formatFromPath(path) {
+    const segment = path.slice(path.lastIndexOf('/') + 1);
+    const dot = segment.lastIndexOf('.');
+    if (dot <= 0)
+        return undefined;
+    return IMAGE_EXTENSIONS[segment.slice(dot + 1).toLowerCase()];
+}
+/**
+ * The format the artifact was actually captured in, read off its `image_url`, or undefined.
+ *
+ * `screenshotKey` (`packages/worker/src/storage/b2.ts:60`) builds the object key as
+ * `screenshots/<account>/<date>/<screenshot_id>.<format>`, so the URL's PATHNAME extension is the
+ * captured format — the only place the CLI can observe it. `ScreenshotResponse`
+ * (`docs/api/openapi.yaml`) carries no `format` field, and `screenshots get` has no `--format`
+ * flag, so neither the envelope nor the argv can answer this on the poll path.
+ *
+ * The pathname — never the raw string. A completed `image_url` is an AWS SigV4 PRESIGNED URL
+ * (`?X-Amz-Credential=…&X-Amz-Signature=…`, `gateway/src/lib/signed-url.ts`), and a
+ * `lastIndexOf('.')` over the whole string reads the signature instead of the key. An unparseable
+ * URL yields undefined rather than throwing: this is advisory, and it runs immediately before a
+ * download that must not be blocked by it.
+ */
+function capturedFormat(imageUrl) {
+    try {
+        return formatFromPath(new URL(imageUrl).pathname);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The advisory note for a `-o` destination whose extension contradicts the captured format, or
+ * undefined when there is nothing to say (#2956 item 3).
+ *
+ * THE DEFECT: `--format` is omitted far more often than not, and the server default is **jpeg** —
+ * so `screenshots create --url … -o shot.png` wrote JPEG bytes into a `.png`-named file, silently,
+ * at exit 0. The mislabelled file then propagated to whatever consumed it next. `screenshots get`
+ * has no `--format` flag at all, so it could not even be told what it was downloading.
+ *
+ * ADVISORY, NOT ENFORCEMENT — this returns a message; the caller writes it to STDERR and proceeds.
+ * The bytes on disk and the exit code are untouched, because the caller may well have meant it
+ * (`-o` is also how you rename an artifact), and because refusing the write would throw away a
+ * capture that was already taken and billed. It stays on the `-o` write path rather than moving
+ * into `downloadArtifact`: that helper is format-agnostic and has no business knowing about image
+ * extensions.
+ *
+ * Silent unless BOTH sides name a recognized image format AND they differ. Nothing to compare —
+ * `-o -` (stdout, no filename to mislabel), an extension-less or non-image destination, an
+ * artifact URL with no usable extension — means no note, never a guessed one.
+ *
+ * `-o -` needs no special case of its own: the literal `-` carries no extension, so
+ * {@link formatFromPath} already returns undefined for it. An explicit early return was written
+ * first and then removed — no mutation of it could turn a test red, which is the definition of a
+ * line that guards nothing. The stdout case stays PINNED by a test either way.
+ */
+export function formatMismatchNote(imageUrl, dest) {
+    const requested = formatFromPath(dest);
+    if (requested === undefined)
+        return undefined;
+    const actual = capturedFormat(imageUrl);
+    if (actual === undefined || actual === requested)
+        return undefined;
+    const ext = dest.slice(dest.lastIndexOf('.'));
+    return (`Note: the screenshot was captured as ${actual}, but ${dest} names ${ext}. ` +
+        `The file holds ${actual} bytes — pass --format ${requested} to capture it as ${requested}.`);
+}
 /**
  * The failure carried by the FLAT `error_code`/`error_message` fields, or undefined (#2792).
  *
@@ -220,7 +305,15 @@ async function emitScreenshot(result, opts) {
             process.exitCode = QUEUED_EXIT_CODE;
             return;
         }
-        await downloadArtifact(extractImageUrl(result), opts.output);
+        const imageUrl = extractImageUrl(result);
+        // Advisory only — see {@link formatMismatchNote}. Emitted BEFORE the download so the note is
+        // never lost to a failing fetch, and to STDERR so `-o -` pipelines and stdout redirects stay
+        // byte-identical. It is deliberately unreachable from the not-ready branch above (no artifact
+        // exists, so there is no format to compare) and from `extractImageUrl`'s throw paths.
+        const note = formatMismatchNote(imageUrl, opts.output);
+        if (note !== undefined)
+            console.error(note);
+        await downloadArtifact(imageUrl, opts.output);
         return;
     }
     printResult(result, opts.json);

package/dist/commands/search.js

@@ -6,8 +6,33 @@ import { printResult, handleError } from '../output.js';
  *
  * The CLI never surfaces provider-specific fields — only the ranked result
  * columns the API returns.
+ *
+ * GUARD (#2956 item 1): `response.results` is typed as required, but the type describes what the
+ * API PROMISES, not what a given 200 actually carried — a proxy, a stub server, or a future
+ * envelope change can all answer `200 {"ok":true}`. Two distinct defects came out of trusting the
+ * type here:
+ *
+ * - a MISSING (or null) `results` drove the `for…of` below into
+ *   `TypeError: response.results is not iterable`, which reached stderr as the CLI's whole
+ *   diagnostic. It named an internal expression instead of the field, and left the caller with no
+ *   next move;
+ * - a `results` that is a STRING is iterable, so it did not throw at all — it printed one garbled
+ *   row per CHARACTER and exited 0, which is the quieter of the two failures.
+ *
+ * `Array.isArray` is therefore the gate (not a truthiness or length test), and it is checked
+ * BEFORE any row is written so a malformed body can never produce a half-rendered table. An EMPTY
+ * array stays a successful zero-hit search: it prints nothing and exits 0.
+ *
+ * The thrown error is a plain `Error` raised inside the action's `try`, so it reaches
+ * `handleError` — one `Error: `-prefixed stderr line, exit 1, no stack trace — exactly like every
+ * other command's unexpected-body diagnostic. It points at `--json`, which bypasses this renderer
+ * entirely and dumps the raw body, because inspecting that body is the caller's actual next step.
  */
 function renderTable(response) {
+    if (!Array.isArray(response.results)) {
+        throw new Error('search: the response carries no "results" array — the server returned an unexpected 200 body. ' +
+            'Re-run with --json to inspect it.');
+    }
     for (const result of response.results) {
         console.log(`${result.position}. ${result.title}`);
         console.log(`   ${result.url}`);

package/dist/index.js

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
 import { realpathSync } from 'node:fs';
-import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import { makeScrapeCommand } from './commands/scrape.js';
 import { makeScreenshotsCommand } from './commands/screenshots.js';
@@ -13,12 +12,10 @@ import { makeSearchCommand } from './commands/search.js';
 import { makeAccountCommand } from './commands/account.js';
 import { makeUsageCommand } from './commands/usage.js';
 import { makeWebhookDeliveriesCommand } from './commands/webhook-deliveries.js';
-// Resolve version from package.json at runtime (supports compiled output).
-const require = createRequire(import.meta.url);
-// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-const pkg = require('../package.json');
-// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
-const version = typeof pkg.version === 'string' ? pkg.version : '0.1.0';
+// Resolved from package.json at runtime (supports compiled output). Shared with `client.ts`'s
+// `client_surface` marker (#2906) so `--version` and the emitted `cli/<version>` affix can never
+// disagree.
+import { PACKAGE_VERSION as version } from './package-version.js';
 /** Construct the root CLI program. Exported so tests can inspect identity/structure without parsing argv. */
 export function buildProgram() {
     const program = new Command();

package/dist/package-version.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Fallback `'0.1.0'` is carried over verbatim from the pre-#2906 inline resolution in `index.ts`.
+ * It cannot be reached from a correctly packed tarball; it exists so a malformed manifest degrades
+ * to a parseable semver instead of `undefined` leaking into `--version` output or onto the wire.
+ */
+export declare const PACKAGE_VERSION: string;

package/dist/package-version.js

@@ -0,0 +1,31 @@
+import { createRequire } from 'node:module';
+/**
+ * This package's own version, resolved at runtime from `package.json`.
+ *
+ * Two consumers share it so the CLI can never report one version to `--version` and affix another
+ * to its outgoing `client_surface` marker: `index.ts` (commander's `.version()`) and `client.ts`
+ * (the `cli/<version>` marker header, issue #2906 — spelled once, at that emit site).
+ *
+ * THIS MODULE MUST STAY DIRECTLY UNDER `src/`. `tsconfig.json` sets `rootDir: ./src` and
+ * `outDir: ./dist`, so `src/package-version.ts` compiles to `dist/package-version.js` and the
+ * `../package.json` below resolves to the PACKAGE ROOT from both trees. A copy of this block under
+ * `src/lib/` would compile to `dist/lib/`, where `../package.json` resolves to `dist/package.json`
+ * — a path that does not exist in the published tarball (`files` ships `dist` + `CHANGELOG.md`,
+ * not the manifest at that depth). `__tests__/entrypoint.test.ts` spawns the BUILT `dist` entry
+ * with `--version` and asserts the output equals the manifest version, so that dist-depth
+ * resolution is proven by an existing live test rather than argued.
+ *
+ * `createRequire(import.meta.url)` rather than a JSON import: the package is `type: module` and
+ * import attributes are still not uniformly available across the `engines.node: >=18` floor.
+ */
+const require = createRequire(import.meta.url);
+// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+const pkg = require('../package.json');
+/**
+ * Fallback `'0.1.0'` is carried over verbatim from the pre-#2906 inline resolution in `index.ts`.
+ * It cannot be reached from a correctly packed tarball; it exists so a malformed manifest degrades
+ * to a parseable semver instead of `undefined` leaking into `--version` output or onto the wire.
+ */
+export const PACKAGE_VERSION = 
+// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+typeof pkg.version === 'string' ? pkg.version : '0.1.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hunt-labs/bytekit-cli",
-  "version": "0.7.1",
+  "version": "0.8.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.6.1"
+    "@hunt-labs/bytekit-sdk": "^0.7.1"
   },
   "scripts": {
     "build": "rm -rf dist tsconfig.tsbuildinfo && tsc",