@hunt-labs/bytekit-cli 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -8,6 +8,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 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.3.0] - 2026-07-21
+
+### Removed (**BREAKING**)
+
+- The legacy `RAPIDCRAWL_API_KEY` and `RAPIDCRAWL_BASE_URL` environment-variable
+  fallbacks (kept as a one-minor-version bridge in #2421) are removed. Use
+  `BYTEKIT_API_KEY` and `BYTEKIT_BASE_URL` (or the `--key` / `--base-url` flags).
+  (#2473)
+
+### Fixed
+
+- `bytekit fetch get` / `fetch create` no longer crash on non-JSON bodies. The
+  transport JSON-parsed every 2xx response, but `/v1/fetch` returns the fetched
+  content AS the body. The fetch command now prints the raw body by default, or
+  the `X-Fetch-*` metadata as JSON with `--json`; `fetch bulk` and every other
+  command still parse JSON. (#2467)
+- `204 No Content` / empty-body responses (e.g. `monitors delete`,
+  `account api-keys revoke`) no longer throw a JSON-parse error, including after
+  a 429 retry. (#2467, #2468)
+- `search --type images` no longer prints an `undefined` snippet line for
+  results that omit the field. (#2479)
+
+### Added
+
+- `scrape create` accepts the full `ScrapeRequest` surface: `--country`,
+  `--timeout-ms`, `--markdown-mode`, `--async`, `--webhook-url`,
+  `--token-budget`, `--clean-markdown`, `--include-tags`, `--exclude-tags`,
+  `--mobile`. Each flag is omitted from the request when absent. (#2480)
+- `screenshots create` accepts `--device`, `--viewport WxH`, `--format`,
+  `--quality`, `--wait-until`, `--clip x,y,w,h`, and `--async`; `-o <file>`
+  on `screenshots create`/`get` downloads the captured image bytes (`-o -` for
+  stdout). `-o` cannot be combined with `--json` on screenshots. (#2480)
+- `monitors list` accepts `--limit`, `--cursor`, and `--status` query
+  filters. (#2480)
+- `account api-keys reveal <ak_id>`: prints the key masked by default
+  (`sk_live_…2345`); pass `--show` for the full plaintext. (#2480)
+- Per-attempt transport timeout (120s, mirroring the SDK default): a hung
+  request now fails with `code: 'timeout'` instead of hanging forever. Network
+  failures are mapped onto the SDK's connection-error taxonomy
+  (`timeout` / `aborted` / `connection`), and error output renders the API or
+  connection error code. (#2479)
+- A queued async job (HTTP 202) under `--raw` prints the job envelope with its
+  `sc_` id instead of an empty body. (#2479)
+
+### Changed (**BREAKING**)
+
+- `fetch --format` is validated locally against the spec union
+  `'markdown' | 'html'`; off-spec values are rejected with a clear error before
+  a request is sent (previously forwarded as-is). (#2475)
+
 ## [0.2.2] - 2026-07-16
 
 ### Changed
@@ -66,6 +116,7 @@ Additive, lower-risk release — no breaking changes to existing commands.
 - Initial release of the ByteKit CLI, wrapping the ByteKit SDK as shell
   subcommands, published under the original `rapidcrawl-cli` name.
 
+[0.3.0]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/cli
 [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

package/README.md

@@ -43,8 +43,7 @@ over the environment variable):
 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).
+Precedence is `--key` flag → `BYTEKIT_API_KEY`.
 
 Without a key, the CLI exits with `Error: API key required. Pass --key or set BYTEKIT_API_KEY.`
 
@@ -52,8 +51,7 @@ Without a key, the CLI exits with `Error: API key required. Pass --key or set BY
 
 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):
+`BYTEKIT_BASE_URL` environment variable (the flag wins):
 
 ```bash
 bytekit --base-url https://api-stg.bytekit.com scrape create --url https://example.com
@@ -62,11 +60,11 @@ 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. |
+| Flag               | Env var            | Purpose                                                                                                                                 |
+| ------------------ | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `--key <key>`      | `BYTEKIT_API_KEY`  | API key used for every request.                                                                                                         |
+| `--base-url <url>` | `BYTEKIT_BASE_URL` | API base URL (default `https://api.bytekit.com`).                                                                                       |
+| `--json`           | —                  | Print the raw JSON response instead of the human-readable rendering (for `fetch`, prints the `X-Fetch-*` metadata instead of the body). |
 
 ## Commands
 
@@ -78,6 +76,27 @@ 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`):
+
+| Flag                     | Effect                                                  |
+| ------------------------ | ------------------------------------------------------- |
+| `--country <cc>`         | Route through a country (e.g. `us`, `de`).              |
+| `--timeout-ms <n>`       | Per-request timeout in milliseconds.                    |
+| `--markdown-mode <mode>` | Markdown extraction mode: `article`, `raw`, `llm`.      |
+| `--async`                | Queue the scrape and return a job envelope immediately. |
+| `--webhook-url <url>`    | Webhook notified when an async scrape completes.        |
+| `--token-budget <n>`     | Cap the markdown returned to `n` tokens.                |
+| `--clean-markdown`       | LLM-clean the markdown (billed 3x).                     |
+| `--include-tags <csv>`   | Comma-separated HTML tags to keep.                      |
+| `--exclude-tags <csv>`   | Comma-separated HTML tags to drop.                      |
+| `--mobile`               | Render with a mobile viewport/user-agent.               |
+
+`--async` combined with `--raw` (or a bare `-o`) prints the queued job envelope
+(the `sc_` id + status) rather than a format body, since a queued scrape has no
+body yet. On `scrape`, `-o` writes the same text rendering the terminal would
+show, so it is legal alongside `--json`.
+
 ### `fetch` — raw, unprocessed response bodies
 
 ```bash
@@ -95,9 +114,22 @@ bytekit search "ai web scraping" --limit 10 --country us
 
 ```bash
 bytekit screenshots create --url https://example.com --full-page
-bytekit screenshots get ss_123abc
+bytekit screenshots create --url https://example.com --device mobile --format png -o shot.png
+bytekit screenshots get ss_123abc -o shot.png
 ```
 
+`screenshots create` 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
+absent.
+
+`-o <file>` downloads the captured image bytes to that file (use `-o -` for
+stdout). Because `-o` writes BINARY on `screenshots`, it cannot be combined with
+`--json` (that would emit binary into a JSON pipeline) — pass one or the other.
+`--async` + `-o` prints the queued job envelope and skips the download (the
+image is not ready yet).
+
 ### `bulk` — bulk screenshot jobs
 
 ```bash
@@ -114,11 +146,15 @@ bytekit bulk screenshots list "$bulk_id"
 ```bash
 bytekit monitors create --url https://example.com/pricing --interval-type daily \
   --webhook-url https://your.app/hooks/bytekit
-bytekit monitors list
+bytekit monitors list --limit 25 --status active
 bytekit monitors captures list mon_123abc
 bytekit monitors delete mon_123abc
 ```
 
+`monitors list` accepts `--limit <n>`, `--cursor <cursor>`, and `--status`
+(`active`, `processing`, `paused`, `cancelled`, `suspended`) as query filters,
+each omitted when absent.
+
 ### `sitemap` — crawl a site's URL graph
 
 ```bash
@@ -132,8 +168,14 @@ bytekit sitemap get sm_123abc
 bytekit account get
 bytekit account api-keys list
 bytekit account api-keys create --name "ci-key"
+bytekit account api-keys reveal ak_123abc          # masked by default
+bytekit account api-keys reveal ak_123abc --show   # full plaintext
 ```
 
+`account api-keys reveal` prints a live secret, so it MASKS the key by default
+(`sk_live_…2345`). Pass `--show` for the full plaintext, or `--json` for the
+full envelope (for scripts).
+
 ## Documentation
 
 Full API reference: [bytekit.com/docs](https://bytekit.com/docs).

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { RapidCrawl } from '@hunt-labs/bytekit-sdk';
+import { ByteKit } from '@hunt-labs/bytekit-sdk';
 export interface GlobalOptions {
     key?: string | undefined;
     baseUrl?: string | undefined;
@@ -22,6 +22,17 @@ export declare const MIN_RETRY_AFTER_MS = 1000;
 export declare const MAX_RETRY_AFTER_MS = 60000;
 /** Exactly one retry. A second 429 is terminal — no loop. */
 export declare const MAX_RETRIES = 1;
+/**
+ * Default CLIENT-SIDE abort budget for a single fetch attempt, in ms.
+ *
+ * Mirrors the SDK's own `DEFAULT_TIMEOUT_MS` (120s). Overriding `client.request` with this
+ * transport had discarded the SDK's default, so a hung server hung the CLI forever; this restores
+ * the same bound. The budget is **per attempt**, not per command: the single 429 retry (and its
+ * backoff sleep) gets a fresh budget, so the retry can never be cut short by time already spent on
+ * the first attempt. A future `--timeout` flag would override this default; today only the default
+ * exists.
+ */
+export declare const DEFAULT_TIMEOUT_MS = 120000;
 /**
  * Parse a `Retry-After` header into a clamped millisecond delay.
  *
@@ -34,7 +45,7 @@ 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
+ * header-less `ByteKitError` 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.
  *
@@ -43,17 +54,16 @@ export declare function parseRetryAfterMs(raw: string | null): number;
  *
  * Retries apply to 429 only. Non-429 statuses and network rejections propagate untouched.
  */
-export declare function createRetryingRequest(apiKey: string, baseUrl: string): RapidCrawl['request'];
+export declare function createRetryingRequest(apiKey: string, baseUrl: string, timeoutMs?: number): ByteKit['request'];
 /**
  * Build an authenticated SDK client from global CLI options.
  *
- * 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.
+ * Resolution order (explicit input beats environment):
+ *   apiKey:  --key flag → BYTEKIT_API_KEY.
+ *   baseUrl: --base-url flag → BYTEKIT_BASE_URL → DEFAULT_BASE_URL.
+ * 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;
+export declare function buildClient(opts: GlobalOptions): ByteKit;

package/dist/client.js

@@ -1,4 +1,4 @@
-import { RapidCrawl, RapidCrawlError } from '@hunt-labs/bytekit-sdk';
+import { ByteKit, ByteKitError, ByteKitConnectionError } 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
@@ -18,6 +18,69 @@ export const MIN_RETRY_AFTER_MS = 1_000;
 export const MAX_RETRY_AFTER_MS = 60_000;
 /** Exactly one retry. A second 429 is terminal — no loop. */
 export const MAX_RETRIES = 1;
+/**
+ * Default CLIENT-SIDE abort budget for a single fetch attempt, in ms.
+ *
+ * Mirrors the SDK's own `DEFAULT_TIMEOUT_MS` (120s). Overriding `client.request` with this
+ * transport had discarded the SDK's default, so a hung server hung the CLI forever; this restores
+ * the same bound. The budget is **per attempt**, not per command: the single 429 retry (and its
+ * backoff sleep) gets a fresh budget, so the retry can never be cut short by time already spent on
+ * the first attempt. A future `--timeout` flag would override this default; today only the default
+ * exists.
+ */
+export const DEFAULT_TIMEOUT_MS = 120_000;
+/** The abort reason used when a per-attempt budget elapses; `name` maps it to `code: 'timeout'`. */
+function timeoutReason(ms) {
+    const reason = new Error(`ByteKit: request timed out after ${ms}ms`);
+    reason.name = 'TimeoutError';
+    return reason;
+}
+/**
+ * A per-attempt abort budget: an `AbortController` fired by a `setTimeout`.
+ *
+ * Deliberately NOT `AbortSignal.timeout` (which the SDK prefers): that schedules on a timer the
+ * test runner's fake timers cannot advance, so the transport's timeout would be untestable under
+ * `vi.useFakeTimers()`. CLI requests are short-lived and single-shot, so the GC advantage
+ * `AbortSignal.timeout` buys the long-running SDK does not apply here. The timer is `unref`'d so a
+ * pending budget never keeps the process alive, and `cleanup()` clears it on every exit path.
+ */
+function createAttemptBudget(ms) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(timeoutReason(ms)), ms);
+    timer.unref?.();
+    return {
+        signal: controller.signal,
+        cleanup: () => clearTimeout(timer),
+    };
+}
+/**
+ * Map a `fetch` rejection (no HTTP response was produced) onto the SDK's `ByteKitConnectionError`
+ * taxonomy, so a CLI failure carries the same `{name, code, cause}` a direct SDK call would.
+ *
+ * `timedOut` is true when this attempt's own budget fired the abort, which is the reliable
+ * discriminator (undici rejects with the signal's reason, whose `name` we also inspect as a
+ * fallback for a caller-style AbortError).
+ */
+function toConnectionError(err, method, path, timedOut) {
+    const rawName = typeof err === 'object' && err !== null && 'name' in err ? err.name : undefined;
+    const name = typeof rawName === 'string' ? rawName : '';
+    let code;
+    if (timedOut || name === 'TimeoutError') {
+        code = 'timeout';
+    }
+    else if (name === 'AbortError') {
+        code = 'aborted';
+    }
+    else {
+        code = 'connection';
+    }
+    const detail = code === 'timeout'
+        ? 'request timed out'
+        : code === 'aborted'
+            ? 'request aborted'
+            : 'connection failed before a response was received';
+    return new ByteKitConnectionError(code, `ByteKit: ${method} ${path} — ${detail}`, { cause: err });
+}
 /**
  * Parse a `Retry-After` header into a clamped millisecond delay.
  *
@@ -44,7 +107,7 @@ function sleep(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
+ * Reusing `ByteKitError` 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.
  */
@@ -59,13 +122,41 @@ async function toApiError(response) {
     catch {
         // leave defaults
     }
-    return new RapidCrawlError(response.status, code, message);
+    return new ByteKitError(response.status, code, message);
+}
+/**
+ * Is this request targeting a `/v1/fetch` CONTENT endpoint (POST or GET), whose body IS the fetched
+ * content rather than a JSON envelope?
+ *
+ * Keyed off the request TARGET, never the response content-type: a fetched page can itself serve
+ * `application/json`, and that body must still be returned raw, not parsed. The `/v1/fetch/bulk`
+ * job endpoints are NOT content endpoints — they return a JSON envelope and keep parsing as JSON.
+ */
+function isFetchContentPath(path) {
+    return (path.split('?')[0] ?? path) === '/v1/fetch';
+}
+/** Title-Case an HTTP header name segment-by-segment: `x-fetch-status` → `X-Fetch-Status`. */
+function titleCaseHeader(name) {
+    return name
+        .split('-')
+        .map((seg) => seg.charAt(0).toUpperCase() + seg.slice(1).toLowerCase())
+        .join('-');
+}
+/** Collect the `X-Fetch-*` response headers into a Title-Cased metadata object. */
+function collectFetchMetadata(headers) {
+    const meta = {};
+    headers.forEach((value, key) => {
+        if (key.toLowerCase().startsWith('x-fetch-')) {
+            meta[titleCaseHeader(key)] = value;
+        }
+    });
+    return meta;
 }
 /**
  * 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
+ * header-less `ByteKitError` 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.
  *
@@ -74,7 +165,7 @@ async function toApiError(response) {
  *
  * Retries apply to 429 only. Non-429 statuses and network rejections propagate untouched.
  */
-export function createRetryingRequest(apiKey, baseUrl) {
+export function createRetryingRequest(apiKey, baseUrl, timeoutMs = DEFAULT_TIMEOUT_MS) {
     return async function request(method, path, body) {
         for (let attempt = 0;; attempt++) {
             const init = {
@@ -87,9 +178,44 @@ export function createRetryingRequest(apiKey, baseUrl) {
             if (body !== undefined) {
                 init.body = JSON.stringify(body);
             }
-            const response = await fetch(`${baseUrl}${path}`, init);
+            // Per-attempt abort budget: a fresh timer for THIS fetch. A budget of 0 disables it.
+            const budget = timeoutMs > 0 ? createAttemptBudget(timeoutMs) : undefined;
+            if (budget !== undefined) {
+                init.signal = budget.signal;
+            }
+            let response;
+            try {
+                response = await fetch(`${baseUrl}${path}`, init);
+            }
+            catch (err) {
+                // No HTTP response was produced (timeout, abort, socket/DNS/TLS). Re-throw as the SDK's
+                // own ByteKitConnectionError so a hung server can never hang the CLI and a network failure
+                // no longer surfaces as a bare `Error: fetch failed`.
+                throw toConnectionError(err, method, path, budget?.signal.aborted === true);
+            }
+            finally {
+                // Clear the timer on every exit path — success, HTTP error, or abort — so a healthy
+                // request leaves no dangling 120s timer.
+                budget?.cleanup();
+            }
             if (response.ok) {
-                return (await response.json());
+                // A /v1/fetch content response body IS the fetched content (HTML/markdown/binary), with its
+                // metadata in X-Fetch-* headers. Return the raw bytes untouched — JSON-parsing it is the
+                // #2467 DOA crash. Every other endpoint returns a JSON envelope, parsed below.
+                if (isFetchContentPath(path)) {
+                    const bodyBytes = Buffer.from(await response.arrayBuffer());
+                    const fetchResult = {
+                        __bytekitFetchBody: true,
+                        body: bodyBytes,
+                        metadata: collectFetchMetadata(response.headers),
+                    };
+                    return fetchResult;
+                }
+                const text = await response.text();
+                if (response.status === 204 || text.trim().length === 0) {
+                    return undefined;
+                }
+                return JSON.parse(text);
             }
             if (response.status === 429 && attempt < MAX_RETRIES) {
                 await sleep(parseRetryAfterMs(response.headers.get('Retry-After')));
@@ -102,26 +228,22 @@ export function createRetryingRequest(apiKey, baseUrl) {
 /**
  * Build an authenticated SDK client from global CLI options.
  *
- * 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.
+ * Resolution order (explicit input beats environment):
+ *   apiKey:  --key flag → BYTEKIT_API_KEY.
+ *   baseUrl: --base-url flag → BYTEKIT_BASE_URL → DEFAULT_BASE_URL.
+ * 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['BYTEKIT_API_KEY'] ?? process.env['RAPIDCRAWL_API_KEY'];
+    const apiKey = opts.key ?? process.env['BYTEKIT_API_KEY'];
     if (!apiKey) {
         console.error('Error: API key required. Pass --key or set BYTEKIT_API_KEY.');
         process.exit(1);
     }
-    const baseUrl = opts.baseUrl ??
-        process.env['BYTEKIT_BASE_URL'] ??
-        process.env['RAPIDCRAWL_BASE_URL'] ??
-        DEFAULT_BASE_URL;
-    const client = new RapidCrawl({ apiKey, baseUrl });
+    const baseUrl = opts.baseUrl ?? process.env['BYTEKIT_BASE_URL'] ?? DEFAULT_BASE_URL;
+    const client = new ByteKit({ apiKey, baseUrl });
     client.request = createRetryingRequest(apiKey, baseUrl);
     return client;
 }

package/dist/commands/account.js

@@ -1,6 +1,28 @@
 import { Command } from 'commander';
 import { buildClient } from '../client.js';
 import { printResult, handleError } from '../output.js';
+/** Visible lead-in of the masked form: the `sk_live_`/`sk_test_` prefix (or first 8 chars). */
+const MASK_PREFIX_CHARS = 8;
+/** Visible tail of the masked form, shown only when enough of the middle stays hidden. */
+const MASK_SUFFIX_CHARS = 4;
+/** Minimum number of characters the `…` must actually hide before a suffix may be shown. */
+const MIN_MASKED_CHARS = 8;
+/**
+ * Mask a plaintext API key for human display: show the `sk_live_`/`sk_test_` prefix (or the first
+ * 8 chars) and the last 4, with the secret middle replaced by `…`. The last-4 suffix is shown ONLY
+ * when at least MIN_MASKED_CHARS of the middle stay hidden (key length >= 8 + 4 + 8 = 20): on a
+ * 13–19-char key, `slice(0, 8) + slice(-4)` would hide as little as one character, and at 12 or
+ * fewer the prefix and suffix overlap outright — either way the "mask" would leak most of a live
+ * secret, so everything after the recognized prefix is masked instead (#2480).
+ */
+function maskKey(key) {
+    const prefixMatch = /^(sk_(?:live|test)_)/.exec(key);
+    if (key.length < MASK_PREFIX_CHARS + MASK_SUFFIX_CHARS + MIN_MASKED_CHARS) {
+        const prefix = prefixMatch ? prefixMatch[1] : key.slice(0, MASK_PREFIX_CHARS);
+        return `${prefix}…`;
+    }
+    return `${key.slice(0, MASK_PREFIX_CHARS)}…${key.slice(-MASK_SUFFIX_CHARS)}`;
+}
 export function makeAccountCommand(getGlobal) {
     const cmd = new Command('account').description('Account and API key operations');
     const apiKeysCmd = new Command('api-keys').description('API key management');
@@ -67,6 +89,33 @@ export function makeAccountCommand(getGlobal) {
             handleError(err);
         }
     });
+    apiKeysCmd
+        .command('reveal <id>')
+        .description('Reveal an API key value (masked by default; use --show for plaintext)')
+        .option('--show', 'Print the full plaintext key instead of the masked form')
+        .action(async (id, opts) => {
+        const g = getGlobal();
+        const client = buildClient(g);
+        try {
+            const result = await client.account.apiKeys.reveal(id);
+            // Masking decision (#2480 E10): `reveal` prints a LIVE secret to a terminal that may be
+            // logged or screen-shared, so plaintext is opt-in. Default (human) mode masks the key
+            // (prefix + last-4, e.g. `sk_live_…2345`); `--show` prints the full plaintext; `--json`
+            // emits the full envelope verbatim for machine consumption.
+            if (g.json) {
+                printResult(result, true);
+            }
+            else if (opts.show === true) {
+                console.log(result.key);
+            }
+            else {
+                console.log(maskKey(result.key));
+            }
+        }
+        catch (err) {
+            handleError(err);
+        }
+    });
     apiKeysCmd
         .command('revoke <id>')
         .description('Revoke an API key (idempotent)')

package/dist/commands/fetch.d.ts

@@ -1,5 +1,19 @@
 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,7 +1,24 @@
-import { Command } from 'commander';
+import { Command, InvalidArgumentError } from 'commander';
 import { buildClient } from '../client.js';
-import { printResult, handleError } from '../output.js';
+import { printResult, emitFetchResult, handleError } from '../output.js';
 import { parseUrlLines } from '../lib/url-lines.js';
+const FETCH_FORMATS = ['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 function parseFormat(value) {
+    if (!FETCH_FORMATS.includes(value)) {
+        throw new InvalidArgumentError(`--format must be one of: ${FETCH_FORMATS.join(', ')}.`);
+    }
+    return value;
+}
 export function makeFetchCommand(getGlobal) {
     const cmd = new Command('fetch').description('Fetch URL content operations');
     const bulkCmd = new Command('bulk').description('Bulk fetch operations');
@@ -41,7 +58,7 @@ export function makeFetchCommand(getGlobal) {
         .command('create')
         .description('Fetch URL content (POST)')
         .requiredOption('--url <url>', 'URL to fetch')
-        .option('--format <format>', 'Response format')
+        .option('--format <format>', 'Response format (markdown or html)', parseFormat)
         .action(async (opts) => {
         const g = getGlobal();
         const client = buildClient(g);
@@ -50,7 +67,7 @@ export function makeFetchCommand(getGlobal) {
                 url: opts.url,
                 ...(opts.format !== undefined ? { format: opts.format } : {}),
             });
-            printResult(result, g.json);
+            emitFetchResult(result, g.json);
         }
         catch (err) {
             handleError(err);
@@ -60,7 +77,7 @@ 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')
+        .option('--format <format>', 'Response format (markdown or html)', parseFormat)
         .action(async (opts) => {
         const g = getGlobal();
         const client = buildClient(g);
@@ -69,7 +86,7 @@ export function makeFetchCommand(getGlobal) {
                 url: opts.url,
                 ...(opts.format !== undefined ? { format: opts.format } : {}),
             });
-            printResult(result, g.json);
+            emitFetchResult(result, g.json);
         }
         catch (err) {
             handleError(err);

package/dist/commands/monitors.js

@@ -1,6 +1,9 @@
 import { Command } from 'commander';
 import { buildClient } from '../client.js';
 import { printResult, handleError } from '../output.js';
+import { parseEnum, parseIntFlag } from '../lib/parse-flags.js';
+/** The `listMonitors` `status` query enum. */
+const MONITOR_STATUSES = ['active', 'processing', 'paused', 'cancelled', 'suspended'];
 export function makeMonitorsCommand(getGlobal) {
     const cmd = new Command('monitors').description('Page-change monitor operations');
     const capturesCmd = new Command('captures').description('Monitor capture sub-resources');
@@ -29,13 +32,18 @@ export function makeMonitorsCommand(getGlobal) {
         .action(async (opts) => {
         const g = getGlobal();
         const client = buildClient(g);
+        // Key-checked subset of the SDK's MonitorCreateRequest. The CLI intentionally omits the
+        // spec-required-with-@default fields (type, change_threshold, notify_on) and relies on
+        // the server-side defaults, so the final call needs an explicit assertion — type-level
+        // only; the wire body is unchanged (pinned by __tests__/request-shapes.test.ts).
         const body = {
             url: opts.url,
+            // Commander delivers a plain string; the server validates the enum (422 on a bad value).
             interval_type: opts.intervalType,
             webhook_url: opts.webhookUrl,
         };
         if (opts.cron !== undefined)
-            body['cron_expression'] = opts.cron;
+            body.cron_expression = opts.cron;
         try {
             const result = await client.monitors.create(body);
             printResult(result, g.json);
@@ -47,11 +55,26 @@ export function makeMonitorsCommand(getGlobal) {
     cmd
         .command('list')
         .description('List all monitors')
-        .action(async () => {
+        .option('--limit <n>', 'Maximum number of monitors to return', (v) => parseIntFlag('--limit', v))
+        .option('--cursor <cursor>', 'Pagination cursor from a previous page')
+        .option('--status <status>', `Filter by status: ${MONITOR_STATUSES.join(', ')} (default active)`, (v) => parseEnum('--status', MONITOR_STATUSES, v))
+        .action(async (opts) => {
         const g = getGlobal();
         const client = buildClient(g);
+        // Build the params object with the same omit-when-absent rule as the body builders. When NO
+        // query flag is passed, call list() with ZERO arguments (never list({}) / list(undefined)) so
+        // the inverse-case request-shape assertion `monitors.list` args length 0 stays green (#2480).
+        const params = {};
+        if (opts.limit !== undefined)
+            params.limit = opts.limit;
+        if (opts.cursor !== undefined)
+            params.cursor = opts.cursor;
+        if (opts.status !== undefined)
+            params.status = opts.status;
         try {
-            const result = await client.monitors.list();
+            const result = Object.keys(params).length > 0
+                ? await client.monitors.list(params)
+                : await client.monitors.list();
             printResult(result, g.json);
         }
         catch (err) {