@hunt-labs/bytekit-cli 0.1.0 → 0.2.2

package/CHANGELOG.md

@@ -0,0 +1,72 @@
+# Changelog
+
+All notable changes to `@hunt-labs/bytekit-cli` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+This file records only the delta between versions. For how to use the package
+today, see [README.md](./README.md), which remains the authoritative usage guide.
+
+## [0.2.2] - 2026-07-16
+
+### Changed
+
+- Re-release of 0.2.1. The 0.2.1 artifacts never reached npm — the prod publish's
+  `publish-sdk` step failed on a CI test-isolation flake (`cjs-require.test.ts`
+  rebuilding the shared `dist`), which is now fixed. No consumer-facing changes
+  beyond 0.2.1.
+
+## [0.2.1] - 2026-07-16
+
+### Changed
+
+- `BYTEKIT_API_KEY` / `BYTEKIT_BASE_URL` are now the primary environment
+  variables (precedence: flag > `BYTEKIT_*` > legacy `RAPIDCRAWL_*`).
+  `RAPIDCRAWL_API_KEY` / `RAPIDCRAWL_BASE_URL` continue to work as silent
+  fallbacks. `--help` text, the missing-key error, and the README now reference
+  `BYTEKIT_*`. (#2421)
+
+### Removed
+
+- The `recordings` command (the endpoint is permanently `410` deactivated). (#2421)
+
+## [0.2.0] - 2026-07-15
+
+Additive, lower-risk release — no breaking changes to existing commands.
+
+### Added
+
+- `scrape create --raw` / `-o, --output <file>`: write the raw response body to
+  stdout or a file (#2425).
+- Local `search --limit` validation via a commander `argParser`, so an invalid limit
+  is rejected before a request is sent (#2425).
+- One automatic retry on HTTP 429, honoring a clamped `Retry-After` header, in the
+  CLI transport (#2425).
+
+### Fixed
+
+- Entrypoint guard canonicalized so the `bytekit` bin runs correctly when invoked
+  through an npm/npx symlink (#2418).
+
+### 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.
+- 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`,
+  `LICENSE`, and an MIT `license` field.
+
+## [0.1.0] - 2026
+
+### Added
+
+- Initial release of the ByteKit CLI, wrapping the ByteKit SDK as shell
+  subcommands, published under the original `rapidcrawl-cli` name.
+
+[0.2.2]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/cli
+[0.2.1]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/cli
+[0.2.0]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/cli
+[0.1.0]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/cli

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hunt Labs, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,143 @@
+# @hunt-labs/bytekit-cli
+
+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).
+
+## Install
+
+```bash
+npm install -g @hunt-labs/bytekit-cli
+```
+
+This installs the `bytekit` binary on your `PATH`.
+
+To run it without installing:
+
+```bash
+npx @hunt-labs/bytekit-cli scrape create --url https://example.com
+```
+
+> **Always use the fully-qualified `@hunt-labs/bytekit-cli` name.** The bare
+> package name `bytekit` on the public npm registry belongs to an unrelated
+> third-party project — running it by that short name fetches someone else's
+> code, not this CLI. The short `bytekit` name is only ever the _binary_ you get
+> after installing `@hunt-labs/bytekit-cli`.
+
+Requires Node.js 18+.
+
+## Authentication
+
+Create an API key at [app.bytekit.com](https://app.bytekit.com) (keys are
+prefixed `sk_live_`), then either export it:
+
+```bash
+export BYTEKIT_API_KEY=sk_live_xxx
+bytekit scrape create --url https://example.com
+```
+
+or pass it per-invocation with the global `--key` flag (which takes precedence
+over the environment variable):
+
+```bash
+bytekit --key sk_live_xxx scrape create --url https://example.com
+```
+
+Precedence is `--key` flag → `BYTEKIT_API_KEY` → `RAPIDCRAWL_API_KEY` (legacy
+fallback, deprecated — kept for existing scripts, will eventually be removed).
+
+Without a key, the CLI exits with `Error: API key required. Pass --key or set BYTEKIT_API_KEY.`
+
+## Base-URL override
+
+Requests go to `https://api.bytekit.com` by default. Point the CLI at staging, a
+local gateway, or a proxy with the global `--base-url` flag or the
+`BYTEKIT_BASE_URL` environment variable (the flag wins; `RAPIDCRAWL_BASE_URL` is
+a deprecated legacy fallback):
+
+```bash
+bytekit --base-url https://api-stg.bytekit.com scrape create --url https://example.com
+export BYTEKIT_BASE_URL=http://localhost:3001
+```
+
+## Global options
+
+| Flag               | Env var                                                     | Purpose                                                              |
+| ------------------ | ----------------------------------------------------------- | -------------------------------------------------------------------- |
+| `--key <key>`      | `BYTEKIT_API_KEY` (legacy fallback: `RAPIDCRAWL_API_KEY`)   | API key used for every request.                                      |
+| `--base-url <url>` | `BYTEKIT_BASE_URL` (legacy fallback: `RAPIDCRAWL_BASE_URL`) | API base URL (default `https://api.bytekit.com`).                    |
+| `--json`           | —                                                           | Print the raw JSON response instead of the human-readable rendering. |
+
+## Commands
+
+### `scrape` — scrape URL content
+
+```bash
+bytekit scrape create --url https://example.com --format markdown
+bytekit scrape get sc_123abc
+bytekit scrape bulk create --file urls.txt --webhook-url https://your.app/hooks/bytekit
+```
+
+### `fetch` — raw, unprocessed response bodies
+
+```bash
+bytekit fetch create --url https://example.com
+bytekit fetch bulk create --file urls.txt --webhook-url https://your.app/hooks/bytekit
+```
+
+### `search` — ranked web search
+
+```bash
+bytekit search "ai web scraping" --limit 10 --country us
+```
+
+### `screenshots` — capture a page
+
+```bash
+bytekit screenshots create --url https://example.com --full-page
+bytekit screenshots get ss_123abc
+```
+
+### `bulk` — bulk screenshot jobs
+
+```bash
+bytekit bulk create --file urls.txt --webhook-url https://your.app/hooks/bytekit
+bulk_id=bulk_123abc
+bytekit bulk get "$bulk_id"
+bytekit bulk screenshots list "$bulk_id"
+```
+
+`urls.txt` is newline-delimited: one plain URL (or `{"url":"https://..."}`) per line.
+
+### `monitors` — watch a page for changes
+
+```bash
+bytekit monitors create --url https://example.com/pricing --interval-type daily \
+  --webhook-url https://your.app/hooks/bytekit
+bytekit monitors list
+bytekit monitors captures list mon_123abc
+bytekit monitors delete mon_123abc
+```
+
+### `sitemap` — crawl a site's URL graph
+
+```bash
+bytekit sitemap create --url https://example.com
+bytekit sitemap get sm_123abc
+```
+
+### `account` — account details and API keys
+
+```bash
+bytekit account get
+bytekit account api-keys list
+bytekit account api-keys create --name "ci-key"
+```
+
+## Documentation
+
+Full API reference: [bytekit.com/docs](https://bytekit.com/docs).
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/client.d.ts

@@ -3,11 +3,57 @@ export interface GlobalOptions {
     key?: string | undefined;
     baseUrl?: string | undefined;
 }
+/**
+ * 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
+ * the CLI-owned transport below can never disagree about where a request is going. A test pins
+ * this constant so the two cannot drift silently.
+ */
+export declare const DEFAULT_BASE_URL = "https://api.bytekit.com";
+/** Backoff used when a 429 arrives with no usable `Retry-After` header. */
+export declare const DEFAULT_RETRY_AFTER_MS = 1000;
+/**
+ * Floor for the honored backoff. The gateway sends `Retry-After: resetEpoch - now`, which on a
+ * 1-rps free-plan key is routinely `0` — and can be negative under clock skew. Sleeping 0 ms would
+ * burn the single retry against a limiter that has not reset yet.
+ */
+export declare const MIN_RETRY_AFTER_MS = 1000;
+/** Ceiling for the honored backoff, so a hostile or absurd header cannot hang the CLI. */
+export declare const MAX_RETRY_AFTER_MS = 60000;
+/** Exactly one retry. A second 429 is terminal — no loop. */
+export declare const MAX_RETRIES = 1;
+/**
+ * Parse a `Retry-After` header into a clamped millisecond delay.
+ *
+ * Only the delta-seconds form is honored (the gateway never sends the HTTP-date form). Anything
+ * absent, empty, non-integer or non-numeric falls back to {@link DEFAULT_RETRY_AFTER_MS}; a valid
+ * value is clamped into `[MIN_RETRY_AFTER_MS, MAX_RETRY_AFTER_MS]`.
+ */
+export declare function parseRetryAfterMs(raw: string | null): number;
+/**
+ * Build the CLI's HTTP transport: the SDK's `request` contract, plus a single bounded retry on 429.
+ *
+ * Why the CLI owns the `fetch` instead of wrapping the SDK's `request()`: the SDK throws a
+ * header-less `RapidCrawlError` and discards the `Response`, so a delegating wrapper can see
+ * `status === 429` but can never read `Retry-After`. Owning the fetch is the only way to honor the
+ * server's advertised backoff without editing the SDK.
+ *
+ * Every SDK resource dereferences `this.client.request` at call time, so installing this as an own
+ * property of the client (see {@link buildClient}) routes *all* commands through it from one seam.
+ *
+ * Retries apply to 429 only. Non-429 statuses and network rejections propagate untouched.
+ */
+export declare function createRetryingRequest(apiKey: string, baseUrl: string): RapidCrawl['request'];
 /**
  * Build an authenticated SDK client from global CLI options.
  *
- * Resolution order for apiKey: --key flag → RAPIDCRAWL_API_KEY env var.
- * Throws a descriptive error when no key is available.
+ * Resolution order (explicit input beats environment; new brand beats legacy brand):
+ *   apiKey:  --key flag → BYTEKIT_API_KEY → RAPIDCRAWL_API_KEY (legacy fallback).
+ *   baseUrl: --base-url flag → BYTEKIT_BASE_URL → RAPIDCRAWL_BASE_URL (legacy) → DEFAULT_BASE_URL.
+ * The legacy RAPIDCRAWL_* vars stay silently honored so existing setups keep working; exits with a
+ * descriptive error when no key is available.
+ *
+ * The returned client's `request` is replaced by the retrying transport, so every command inherits
+ * the 429 retry from this one seam.
  */
 export declare function buildClient(opts: GlobalOptions): RapidCrawl;
-//# sourceMappingURL=client.d.ts.map

package/dist/client.js

@@ -1,20 +1,127 @@
-import { RapidCrawl } from '@hunt-labs/bytekit-sdk';
+import { RapidCrawl, RapidCrawlError } from '@hunt-labs/bytekit-sdk';
+/**
+ * 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
+ * the CLI-owned transport below can never disagree about where a request is going. A test pins
+ * this constant so the two cannot drift silently.
+ */
+export const DEFAULT_BASE_URL = 'https://api.bytekit.com';
+/** Backoff used when a 429 arrives with no usable `Retry-After` header. */
+export const DEFAULT_RETRY_AFTER_MS = 1_000;
+/**
+ * Floor for the honored backoff. The gateway sends `Retry-After: resetEpoch - now`, which on a
+ * 1-rps free-plan key is routinely `0` — and can be negative under clock skew. Sleeping 0 ms would
+ * burn the single retry against a limiter that has not reset yet.
+ */
+export const MIN_RETRY_AFTER_MS = 1_000;
+/** Ceiling for the honored backoff, so a hostile or absurd header cannot hang the CLI. */
+export const MAX_RETRY_AFTER_MS = 60_000;
+/** Exactly one retry. A second 429 is terminal — no loop. */
+export const MAX_RETRIES = 1;
+/**
+ * Parse a `Retry-After` header into a clamped millisecond delay.
+ *
+ * Only the delta-seconds form is honored (the gateway never sends the HTTP-date form). Anything
+ * absent, empty, non-integer or non-numeric falls back to {@link DEFAULT_RETRY_AFTER_MS}; a valid
+ * value is clamped into `[MIN_RETRY_AFTER_MS, MAX_RETRY_AFTER_MS]`.
+ */
+export function parseRetryAfterMs(raw) {
+    if (raw === null)
+        return DEFAULT_RETRY_AFTER_MS;
+    const trimmed = raw.trim();
+    if (!/^-?\d+$/.test(trimmed))
+        return DEFAULT_RETRY_AFTER_MS;
+    const seconds = Number(trimmed);
+    if (!Number.isFinite(seconds))
+        return DEFAULT_RETRY_AFTER_MS;
+    return Math.min(Math.max(seconds * 1000, MIN_RETRY_AFTER_MS), MAX_RETRY_AFTER_MS);
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+/**
+ * Shape a failed response into the SDK's OWN error class, using the SDK's own body parsing.
+ *
+ * Reusing `RapidCrawlError` keeps `{status, code, message}` identical to what a direct SDK call
+ * would throw, so `handleError()`'s `'status' in err` branch still renders
+ * `Error: <message> (status: <n>)` and exits 1.
+ */
+async function toApiError(response) {
+    let code = 'internal_error';
+    let message = response.statusText;
+    try {
+        const json = (await response.json());
+        code = json.error?.code ?? code;
+        message = json.error?.message ?? message;
+    }
+    catch {
+        // leave defaults
+    }
+    return new RapidCrawlError(response.status, code, message);
+}
+/**
+ * Build the CLI's HTTP transport: the SDK's `request` contract, plus a single bounded retry on 429.
+ *
+ * Why the CLI owns the `fetch` instead of wrapping the SDK's `request()`: the SDK throws a
+ * header-less `RapidCrawlError` and discards the `Response`, so a delegating wrapper can see
+ * `status === 429` but can never read `Retry-After`. Owning the fetch is the only way to honor the
+ * server's advertised backoff without editing the SDK.
+ *
+ * Every SDK resource dereferences `this.client.request` at call time, so installing this as an own
+ * property of the client (see {@link buildClient}) routes *all* commands through it from one seam.
+ *
+ * Retries apply to 429 only. Non-429 statuses and network rejections propagate untouched.
+ */
+export function createRetryingRequest(apiKey, baseUrl) {
+    return async function request(method, path, body) {
+        for (let attempt = 0;; attempt++) {
+            const init = {
+                method,
+                headers: {
+                    Authorization: `Bearer ${apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+            };
+            if (body !== undefined) {
+                init.body = JSON.stringify(body);
+            }
+            const response = await fetch(`${baseUrl}${path}`, init);
+            if (response.ok) {
+                return (await response.json());
+            }
+            if (response.status === 429 && attempt < MAX_RETRIES) {
+                await sleep(parseRetryAfterMs(response.headers.get('Retry-After')));
+                continue;
+            }
+            throw await toApiError(response);
+        }
+    };
+}
 /**
  * Build an authenticated SDK client from global CLI options.
  *
- * Resolution order for apiKey: --key flag → RAPIDCRAWL_API_KEY env var.
- * Throws a descriptive error when no key is available.
+ * Resolution order (explicit input beats environment; new brand beats legacy brand):
+ *   apiKey:  --key flag → BYTEKIT_API_KEY → RAPIDCRAWL_API_KEY (legacy fallback).
+ *   baseUrl: --base-url flag → BYTEKIT_BASE_URL → RAPIDCRAWL_BASE_URL (legacy) → DEFAULT_BASE_URL.
+ * The legacy RAPIDCRAWL_* vars stay silently honored so existing setups keep working; exits with a
+ * descriptive error when no key is available.
+ *
+ * The returned client's `request` is replaced by the retrying transport, so every command inherits
+ * the 429 retry from this one seam.
  */
 export function buildClient(opts) {
-    const apiKey = opts.key ?? process.env['RAPIDCRAWL_API_KEY'];
+    const apiKey = opts.key ?? process.env['BYTEKIT_API_KEY'] ?? process.env['RAPIDCRAWL_API_KEY'];
     if (!apiKey) {
-        console.error('Error: API key required. Pass --key or set RAPIDCRAWL_API_KEY.');
+        console.error('Error: API key required. Pass --key or set BYTEKIT_API_KEY.');
         process.exit(1);
     }
-    const baseUrl = opts.baseUrl ?? process.env['RAPIDCRAWL_BASE_URL'];
-    return new RapidCrawl({
-        apiKey,
-        ...(baseUrl !== undefined ? { baseUrl } : {}),
-    });
+    const baseUrl = opts.baseUrl ??
+        process.env['BYTEKIT_BASE_URL'] ??
+        process.env['RAPIDCRAWL_BASE_URL'] ??
+        DEFAULT_BASE_URL;
+    const client = new RapidCrawl({ apiKey, baseUrl });
+    client.request = createRetryingRequest(apiKey, baseUrl);
+    return client;
 }
-//# sourceMappingURL=client.js.map

package/dist/commands/account.d.ts

@@ -3,4 +3,3 @@ import { type GlobalOptions } from '../client.js';
 export declare function makeAccountCommand(getGlobal: () => GlobalOptions & {
     json: boolean;
 }): Command;
-//# sourceMappingURL=account.d.ts.map

package/dist/commands/account.js

@@ -12,7 +12,10 @@ export function makeAccountCommand(getGlobal) {
         const g = getGlobal();
         const client = buildClient(g);
         try {
-            const result = await client.account.apiKeys.create({ name: opts.name });
+            // The API's field is `label`, not `name` — sending `{ name }` created an
+            // UNLABELLED key, because the gateway ignored the unknown field (#2426:
+            // the SDK's newly derived request type is what surfaced this).
+            const result = await client.account.apiKeys.create({ label: opts.name });
             printResult(result, g.json);
         }
         catch (err) {
@@ -55,7 +58,9 @@ export function makeAccountCommand(getGlobal) {
         const g = getGlobal();
         const client = buildClient(g);
         try {
-            const result = await client.account.apiKeys.update(id, { name: opts.name });
+            // As above: the API's field is `label`, so `--name` never actually
+            // renamed the key.
+            const result = await client.account.apiKeys.update(id, { label: opts.name });
             printResult(result, g.json);
         }
         catch (err) {
@@ -93,4 +98,3 @@ export function makeAccountCommand(getGlobal) {
     });
     return cmd;
 }
-//# sourceMappingURL=account.js.map

package/dist/commands/bulk.d.ts

@@ -3,4 +3,3 @@ import { type GlobalOptions } from '../client.js';
 export declare function makeBulkCommand(getGlobal: () => GlobalOptions & {
     json: boolean;
 }): Command;
-//# sourceMappingURL=bulk.d.ts.map

package/dist/commands/bulk.js

@@ -53,4 +53,3 @@ export function makeBulkCommand(getGlobal) {
     });
     return cmd;
 }
-//# sourceMappingURL=bulk.js.map

package/dist/commands/fetch.d.ts

@@ -3,4 +3,3 @@ import { type GlobalOptions } from '../client.js';
 export declare function makeFetchCommand(getGlobal: () => GlobalOptions & {
     json: boolean;
 }): Command;
-//# sourceMappingURL=fetch.d.ts.map

package/dist/commands/fetch.js

@@ -77,4 +77,3 @@ export function makeFetchCommand(getGlobal) {
     });
     return cmd;
 }
-//# sourceMappingURL=fetch.js.map

package/dist/commands/monitors.d.ts

@@ -3,4 +3,3 @@ import { type GlobalOptions } from '../client.js';
 export declare function makeMonitorsCommand(getGlobal: () => GlobalOptions & {
     json: boolean;
 }): Command;
-//# sourceMappingURL=monitors.d.ts.map

package/dist/commands/monitors.js

@@ -112,4 +112,3 @@ export function makeMonitorsCommand(getGlobal) {
     });
     return cmd;
 }
-//# sourceMappingURL=monitors.js.map

package/dist/commands/scrape.d.ts

@@ -3,4 +3,3 @@ import { type GlobalOptions } from '../client.js';
 export declare function makeScrapeCommand(getGlobal: () => GlobalOptions & {
     json: boolean;
 }): Command;
-//# sourceMappingURL=scrape.d.ts.map

package/dist/commands/scrape.js

@@ -1,6 +1,6 @@
 import { Command } from 'commander';
 import { buildClient } from '../client.js';
-import { printResult, handleError } from '../output.js';
+import { printResult, handleError, resolveOutputMode, emitResult } from '../output.js';
 import { parseUrlLines } from '../lib/url-lines.js';
 export function makeScrapeCommand(getGlobal) {
     const cmd = new Command('scrape').description('Scrape URL content');
@@ -43,6 +43,8 @@ export function makeScrapeCommand(getGlobal) {
         .description('Create a scrape job')
         .requiredOption('--url <url>', 'URL to scrape')
         .option('--format <format>', 'Output format (e.g. markdown, html); sent as the formats array')
+        .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)')
         .action(async (opts) => {
         const g = getGlobal();
         const client = buildClient(g);
@@ -53,8 +55,15 @@ export function makeScrapeCommand(getGlobal) {
         if (opts.format !== undefined)
             body['formats'] = [opts.format];
         try {
+            // 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
+            // would escape as an unhandled rejection and print a RAW STACK TRACE instead of
+            // handleError()'s clean one-liner. buildClient() does no network I/O, so rejecting the
+            // --json/--raw conflict here still happens before any request is issued.
+            const mode = resolveOutputMode({ json: g.json, raw: opts.raw, output: opts.output });
             const result = await client.scrape.create(body);
-            printResult(result, g.json);
+            emitResult(result, mode, { file: opts.output }, opts.format);
         }
         catch (err) {
             handleError(err);
@@ -76,4 +85,3 @@ export function makeScrapeCommand(getGlobal) {
     });
     return cmd;
 }
-//# sourceMappingURL=scrape.js.map

package/dist/commands/screenshots.d.ts

@@ -3,4 +3,3 @@ import { type GlobalOptions } from '../client.js';
 export declare function makeScreenshotsCommand(getGlobal: () => GlobalOptions & {
     json: boolean;
 }): Command;
-//# sourceMappingURL=screenshots.d.ts.map

package/dist/commands/screenshots.js

@@ -13,7 +13,7 @@ export function makeScreenshotsCommand(getGlobal) {
         const client = buildClient(g);
         const body = { url: opts.url };
         if (opts.fullPage === true)
-            body['full_page'] = true;
+            body.full_page = true;
         try {
             const result = await client.screenshots.create(body);
             printResult(result, g.json);
@@ -38,4 +38,3 @@ export function makeScreenshotsCommand(getGlobal) {
     });
     return cmd;
 }
-//# sourceMappingURL=screenshots.js.map

package/dist/commands/search.d.ts

@@ -1,6 +1,15 @@
 import { Command } from 'commander';
 import { type GlobalOptions } from '../client.js';
+/**
+ * Validate `--limit` locally, before any HTTP request is issued.
+ *
+ * Commander runs an option's argParser during parsing — ahead of the action callback — so a
+ * rejection here means the client is never built and no request body is constructed. The strict
+ * `/^\d+$/` test (rather than Number.isInteger alone) deterministically rejects `abc`, ``, `1.5`,
+ * `-5`, `1e2`, `0x10`, `+1` and `Infinity`, all of which `Number()` would otherwise coerce into a
+ * NaN (→ `limit: null` on the wire) or a silently-wrong value.
+ */
+export declare function parseLimit(value: string): number;
 export declare function makeSearchCommand(getGlobal: () => GlobalOptions & {
     json: boolean;
 }): Command;
-//# sourceMappingURL=search.d.ts.map

package/dist/commands/search.js

@@ -1,4 +1,4 @@
-import { Command } from 'commander';
+import { Command, InvalidArgumentError } from 'commander';
 import { buildClient } from '../client.js';
 import { printResult, handleError } from '../output.js';
 /**
@@ -14,12 +14,32 @@ function renderTable(response) {
         console.log(`   ${result.snippet}`);
     }
 }
+const LIMIT_MIN = 1;
+const LIMIT_MAX = 100;
+/**
+ * Validate `--limit` locally, before any HTTP request is issued.
+ *
+ * Commander runs an option's argParser during parsing — ahead of the action callback — so a
+ * rejection here means the client is never built and no request body is constructed. The strict
+ * `/^\d+$/` test (rather than Number.isInteger alone) deterministically rejects `abc`, ``, `1.5`,
+ * `-5`, `1e2`, `0x10`, `+1` and `Infinity`, all of which `Number()` would otherwise coerce into a
+ * NaN (→ `limit: null` on the wire) or a silently-wrong value.
+ */
+export function parseLimit(value) {
+    const invalid = new InvalidArgumentError(`--limit must be a whole number between ${LIMIT_MIN} and ${LIMIT_MAX}.`);
+    if (!/^\d+$/.test(value))
+        throw invalid;
+    const n = Number(value);
+    if (n < LIMIT_MIN || n > LIMIT_MAX)
+        throw invalid;
+    return n;
+}
 export function makeSearchCommand(getGlobal) {
     return new Command('search')
         .description('Run a web search and return ranked results')
         .argument('<query>', 'Search query')
         .option('--type <type>', 'Search index to query: web (default), news, or images')
-        .option('--limit <n>', 'Maximum number of results to return (1–100)')
+        .option('--limit <n>', 'Maximum number of results to return (1–100)', parseLimit)
         .option('--country <code>', 'Two-letter country code to localize results (e.g. us, de)')
         .option('--language <code>', 'Two-letter language code for results (e.g. en, fr)')
         .option('--date-range <window>', 'Restrict results to a recency window: any (default), hour, day, week, month, or year')
@@ -34,7 +54,7 @@ export function makeSearchCommand(getGlobal) {
         if (opts.type !== undefined)
             body.type = opts.type;
         if (opts.limit !== undefined)
-            body.limit = Number(opts.limit);
+            body.limit = opts.limit;
         if (opts.country !== undefined)
             body.country = opts.country;
         if (opts.language !== undefined)
@@ -55,4 +75,3 @@ export function makeSearchCommand(getGlobal) {
         }
     });
 }
-//# sourceMappingURL=search.js.map

package/dist/commands/sitemap.d.ts

@@ -3,4 +3,3 @@ import { type GlobalOptions } from '../client.js';
 export declare function makeSitemapCommand(getGlobal: () => GlobalOptions & {
     json: boolean;
 }): Command;
-//# sourceMappingURL=sitemap.d.ts.map

package/dist/commands/sitemap.js

@@ -34,4 +34,3 @@ export function makeSitemapCommand(getGlobal) {
     });
     return cmd;
 }
-//# sourceMappingURL=sitemap.js.map