@hunt-labs/bytekit-cli 0.2.2 → 0.5.0

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,92 @@ 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`.
+ *
+ * The budget spans the WHOLE attempt — time-to-headers **and** the response body read (#2546).
+ * Arming it only until headers arrive left `response.text()` / `response.arrayBuffer()` unbounded,
+ * so a server that answered with headers and then stalled its body hung the CLI forever.
+ *
+ * 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),
+    };
+}
+/** The `name` of an error-shaped value, or `undefined` when it carries none. */
+const nameOf = (e) => typeof e === 'object' && e !== null && 'name' in e ? String(e.name) : undefined;
+/** The `cause` of an error-shaped value, or `undefined` when it carries none. */
+const causeOf = (e) => typeof e === 'object' && e !== null && 'cause' in e ? e.cause : undefined;
+/**
+ * The abort-taxonomy name of a rejection, seeing through undici's mid-body wrapper.
+ *
+ * When a request is aborted while its BODY is streaming, undici does not reject with the abort
+ * reason itself — it rejects with `TypeError: terminated` carrying the reason on `.cause` (#2546).
+ * A name-only check would read that as a plain connection failure. Nothing that reached this
+ * function before #2546 carried a `.cause`, so every previously-asserted classification is
+ * unchanged; a `.cause` whose own name is not abort-shaped still falls through to `'connection'`.
+ */
+function abortNameOf(err) {
+    const top = nameOf(err);
+    if (top === 'TimeoutError' || top === 'AbortError')
+        return top;
+    return nameOf(causeOf(err));
+}
+/**
+ * Map a `fetch` or body-read rejection (no usable HTTP payload 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 — or a wrapper carrying it, see
+ * {@link abortNameOf} — whose `name` we also inspect as a fallback for a caller-style AbortError).
+ */
+function toConnectionError(err, method, path, timedOut) {
+    const name = abortNameOf(err) ?? '';
+    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 +130,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,69 +145,174 @@ async function toApiError(response) {
     catch {
         // leave defaults
     }
-    return new RapidCrawlError(response.status, code, message);
+    return new ByteKitError(response.status, code, message);
 }
 /**
- * Build the CLI's HTTP transport: the SDK's `request` contract, plus a single bounded retry on 429.
+ * Perform the authenticated round-trip with a single bounded retry on 429, returning whatever the
+ * caller's `readBody` continuation makes of the successful response.
+ *
+ * This is the CLI's one transport core: it owns auth, the per-attempt abort budget, the 429 retry,
+ * and the error taxonomy — mirroring the SDK's own private `send()`. Taking the body reader as a
+ * continuation (rather than handing the `Response` back with its body unread) is what lets the two
+ * public transports built on it ({@link createRetryingRequest} and {@link createRetryingRequestRaw})
+ * differ ONLY in how they decode a successful body, so no endpoint can ever ride one behavior and
+ * miss the other (#2535: `/v1/fetch` silently bypassed the retry because only `request` was
+ * overridden) — while keeping the abort budget armed ACROSS that read (#2546).
+ *
+ * The budget spans headers **and** body. Returning the `Response` used to end the guarded region
+ * at the headers boundary, leaving `response.text()` / `response.arrayBuffer()` — and
+ * `toApiError`'s error-body `response.json()` — unbounded: a server that sent headers and then
+ * stalled its body hung the CLI forever. `readBody` therefore MUST only consume the stream;
+ * `JSON.parse` / `TextDecoder` run in the callers, OUTSIDE the guard, so a malformed body still
+ * surfaces its own parse error instead of being remapped to a connection error.
  *
- * 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
+ * The budget stays PER ATTEMPT: `cleanup()` runs in an attempt-wide `finally`, and the 429 retry
+ * sleep happens after that `finally` — so a retry can never be cut short by time already spent on
+ * the first attempt.
+ *
+ * Why the CLI owns the `fetch` instead of wrapping the SDK's transports: the SDK throws a
+ * 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.
  *
- * 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);
+async function sendWithRetry(apiKey, baseUrl, timeoutMs, method, path, body, readBody) {
+    for (let attempt = 0;; attempt++) {
+        const init = {
+            method,
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                'Content-Type': 'application/json',
+            },
+        };
+        if (body !== undefined) {
+            init.body = JSON.stringify(body);
+        }
+        // Per-attempt abort budget: a fresh timer for THIS attempt. A budget of 0 disables it.
+        const budget = timeoutMs > 0 ? createAttemptBudget(timeoutMs) : undefined;
+        if (budget !== undefined) {
+            init.signal = budget.signal;
+        }
+        // Set only by the 429-retry branch below — the one path that falls out of the `try` rather
+        // than returning or throwing. Left `undefined` on every other path, which never reaches the
+        // `sleep` after the `finally`.
+        let retryAfterMs;
+        try {
+            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);
             }
-            const response = await fetch(`${baseUrl}${path}`, init);
             if (response.ok) {
-                return (await response.json());
+                try {
+                    return await readBody(response);
+                }
+                catch (err) {
+                    // A body read that never completes is aborted by the same budget; undici then rejects
+                    // the stream (#2546). Map it into the same taxonomy the headers phase uses.
+                    throw toConnectionError(err, method, path, budget?.signal.aborted === true);
+                }
             }
             if (response.status === 429 && attempt < MAX_RETRIES) {
-                await sleep(parseRetryAfterMs(response.headers.get('Retry-After')));
-                continue;
+                retryAfterMs = parseRetryAfterMs(response.headers.get('Retry-After'));
+            }
+            else {
+                // `toApiError` reads the error body, so it too runs inside the budget.
+                throw await toApiError(response);
             }
-            throw await toApiError(response);
         }
+        finally {
+            // Clear the timer on every exit path — success (body read included), HTTP error, or
+            // abort — so a healthy request leaves no dangling 120s timer.
+            budget?.cleanup();
+        }
+        // OUTSIDE the budget's `finally`: the backoff is not spent against any attempt's budget, and
+        // the next attempt arms a fresh one. The `??` is unreachable in practice (only the branch
+        // that assigns `retryAfterMs` falls through to here) and exists solely to keep the delay a
+        // `number` without an assertion; it uses the same value `parseRetryAfterMs(null)` returns.
+        await sleep(retryAfterMs ?? DEFAULT_RETRY_AFTER_MS);
+    }
+}
+/**
+ * Build the CLI's JSON transport: the SDK's `request` contract, plus the single bounded 429 retry.
+ *
+ * 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 JSON commands through it from one
+ * seam. `/v1/fetch` does NOT ride this transport — it rides `requestRaw` (see
+ * {@link createRetryingRequestRaw}); `/v1/fetch/bulk` is a JSON job envelope and does.
+ */
+export function createRetryingRequest(apiKey, baseUrl, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    return async function request(method, path, body) {
+        // The reader consumes the stream and nothing else, so the abort budget covers the read
+        // (#2546) while the 204/empty guard and `JSON.parse` stay OUTSIDE the guarded region —
+        // a malformed 200 body must still surface its own SyntaxError, never a connection error.
+        // Read-first ordering is preserved verbatim from before #2546: `.text()` is called
+        // unconditionally, and only then is the status inspected.
+        const { status, text } = await sendWithRetry(apiKey, baseUrl, timeoutMs, method, path, body, async (response) => ({ status: response.status, text: await response.text() }));
+        if (status === 204 || text.trim().length === 0) {
+            return undefined;
+        }
+        return JSON.parse(text);
+    };
+}
+/**
+ * Build the CLI's RAW transport: the SDK's `requestRaw` contract, plus the same bounded 429 retry.
+ *
+ * `/v1/fetch` returns the fetched content AS the body (HTML, markdown, or true binary) with its
+ * metadata in `X-Fetch-*` headers, so the SDK routes it through `requestRaw` rather than the JSON
+ * `request`. The CLI must override BOTH seams or fetch commands silently bypass the retry and the
+ * CLI's error taxonomy — the #2535 defect, where only `request` was replaced.
+ *
+ * The returned shape is the SDK's `requestRaw` contract verbatim (`{body, bytes, headers, status}`)
+ * so `FetchResource` builds an ordinary `FetchResult` from it and the CLI never forks fetch
+ * handling away from the SDK. `bytes` is byte-exact (binary-safe); `body` is the best-effort UTF-8
+ * decode, matching the SDK's own semantics.
+ */
+export function createRetryingRequestRaw(apiKey, baseUrl, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    return async function requestRaw(method, path, body) {
+        // As in `createRetryingRequest`: the reader only drains the stream (so the abort budget
+        // covers it, #2546); the UTF-8 decode happens outside the guarded region.
+        const { bytes, headers, status } = await sendWithRetry(apiKey, baseUrl, timeoutMs, method, path, body, async (response) => ({
+            bytes: new Uint8Array(await response.arrayBuffer()),
+            headers: response.headers,
+            status: response.status,
+        }));
+        return {
+            body: new TextDecoder('utf-8').decode(bytes),
+            bytes,
+            headers,
+            status,
+        };
     };
 }
 /**
  * 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.
+ * The returned client's `request` AND `requestRaw` are both replaced by the retrying transports, so
+ * every command inherits the 429 retry — JSON commands via `request`, the `/v1/fetch` content
+ * commands via `requestRaw`. Overriding only `request` is the #2535 defect: the SDK's fetch
+ * resource rides `requestRaw`, so fetch bypassed the retry and the CLI's error taxonomy entirely.
  */
 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);
+    client.requestRaw = createRetryingRequestRaw(apiKey, baseUrl);
     return client;
 }

package/dist/commands/account.d.ts

@@ -1,5 +1,16 @@
 import { Command } from 'commander';
 import { type GlobalOptions } from '../client.js';
+/**
+ * The `account` command group.
+ *
+ * Key management is DELIBERATELY absent (#2536). Those operations are mounted behind
+ * `clerkSession(db)` in the gateway and are annotated `x-internal: true` / `x-sdk-scope: internal`
+ * in the OpenAPI spec, so a bearer `sk_` key — the CLI's only credential — can never satisfy them.
+ * Keys are managed from the dashboard instead. Widening the gateway to accept bearer auth was
+ * rejected on security grounds: the reveal operation returns the live plaintext of any key on the
+ * account and there is no per-key scope model, so any leaked key would become a full
+ * account-credential factory. `internal-scope-guard.test.ts` mechanically enforces this boundary.
+ */
 export declare function makeAccountCommand(getGlobal: () => GlobalOptions & {
     json: boolean;
 }): Command;

package/dist/commands/account.js

@@ -1,87 +1,19 @@
 import { Command } from 'commander';
 import { buildClient } from '../client.js';
 import { printResult, handleError } from '../output.js';
+/**
+ * The `account` command group.
+ *
+ * Key management is DELIBERATELY absent (#2536). Those operations are mounted behind
+ * `clerkSession(db)` in the gateway and are annotated `x-internal: true` / `x-sdk-scope: internal`
+ * in the OpenAPI spec, so a bearer `sk_` key — the CLI's only credential — can never satisfy them.
+ * Keys are managed from the dashboard instead. Widening the gateway to accept bearer auth was
+ * rejected on security grounds: the reveal operation returns the live plaintext of any key on the
+ * account and there is no per-key scope model, so any leaked key would become a full
+ * account-credential factory. `internal-scope-guard.test.ts` mechanically enforces this boundary.
+ */
 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');
-    apiKeysCmd
-        .command('create')
-        .description('Create a new API key')
-        .requiredOption('--name <name>', 'Display name for the key')
-        .action(async (opts) => {
-        const g = getGlobal();
-        const client = buildClient(g);
-        try {
-            // 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) {
-            handleError(err);
-        }
-    });
-    apiKeysCmd
-        .command('list')
-        .description('List all API keys')
-        .action(async () => {
-        const g = getGlobal();
-        const client = buildClient(g);
-        try {
-            const result = await client.account.apiKeys.list();
-            printResult(result, g.json);
-        }
-        catch (err) {
-            handleError(err);
-        }
-    });
-    apiKeysCmd
-        .command('get <id>')
-        .description('Get an API key by ID')
-        .action(async (id) => {
-        const g = getGlobal();
-        const client = buildClient(g);
-        try {
-            const result = await client.account.apiKeys.get(id);
-            printResult(result, g.json);
-        }
-        catch (err) {
-            handleError(err);
-        }
-    });
-    apiKeysCmd
-        .command('update <id>')
-        .description('Update an API key')
-        .requiredOption('--name <name>', 'New display name')
-        .action(async (id, opts) => {
-        const g = getGlobal();
-        const client = buildClient(g);
-        try {
-            // 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) {
-            handleError(err);
-        }
-    });
-    apiKeysCmd
-        .command('revoke <id>')
-        .description('Revoke an API key (idempotent)')
-        .action(async (id) => {
-        const g = getGlobal();
-        const client = buildClient(g);
-        try {
-            const result = await client.account.apiKeys.revoke(id);
-            printResult(result, g.json);
-        }
-        catch (err) {
-            handleError(err);
-        }
-    });
-    cmd.addCommand(apiKeysCmd);
+    const cmd = new Command('account').description('Account operations');
     cmd
         .command('get')
         .description('Get the authenticated account')

package/dist/commands/bulk.js

@@ -51,5 +51,19 @@ export function makeBulkCommand(getGlobal) {
             handleError(err);
         }
     });
+    cmd
+        .command('cancel <id>')
+        .description('Cancel an in-flight bulk job')
+        .action(async (id) => {
+        const g = getGlobal();
+        const client = buildClient(g);
+        try {
+            const result = await client.bulk.cancel(id);
+            printResult(result, g.json);
+        }
+        catch (err) {
+            handleError(err);
+        }
+    });
     return cmd;
 }

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,27 @@
-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';
+import { parseIntFlag, parseEnum, parseCacheTtl } from '../lib/parse-flags.js';
+const FETCH_FORMATS = ['markdown', 'html'];
+/** The `FetchRequest.markdown_mode` spec enum (create/POST only — excluded from the GET query). */
+const MARKDOWN_MODES = ['article', 'raw', 'llm'];
+/**
+ * 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,16 +61,28 @@ 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)
+        .option('--country <cc>', 'Two-letter country code to route the request through (e.g. us, de)')
+        .option('--timeout-ms <n>', 'Per-request timeout in milliseconds', (v) => parseIntFlag('--timeout-ms', v))
+        .option('--cache-ttl <ttl>', 'Cache freshness: 0, Nh (hours), or Nd (days), e.g. 48h, 2d, 0 (omitted → server default)', (v) => parseCacheTtl('--cache-ttl', v))
+        // `--markdown-mode` is POST-only: FetchGetOpts excludes it, so adding it to `get` below would be
+        // a compile error — the create/get asymmetry is correct by construction.
+        .option('--markdown-mode <mode>', `Markdown mode: ${MARKDOWN_MODES.join(', ')}`, (v) => parseEnum('--markdown-mode', MARKDOWN_MODES, v))
+        .option('-o, --output <file>', 'Write the fetched body bytes to the given file path')
         .action(async (opts) => {
         const g = getGlobal();
         const client = buildClient(g);
         try {
             const result = await client.fetch.create({
                 url: opts.url,
+                // Each optional field is spread ONLY when its flag is present (#2480 E1).
                 ...(opts.format !== undefined ? { format: opts.format } : {}),
+                ...(opts.country !== undefined ? { country: opts.country } : {}),
+                ...(opts.timeoutMs !== undefined ? { timeout_ms: opts.timeoutMs } : {}),
+                ...(opts.cacheTtl !== undefined ? { cache_ttl: opts.cacheTtl } : {}),
+                ...(opts.markdownMode !== undefined ? { markdown_mode: opts.markdownMode } : {}),
             });
-            printResult(result, g.json);
+            emitFetchResult(result, g.json, { file: opts.output });
         }
         catch (err) {
             handleError(err);
@@ -60,7 +92,11 @@ 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)
+        .option('--country <cc>', 'Two-letter country code to route the request through (e.g. us, de)')
+        .option('--timeout-ms <n>', 'Per-request timeout in milliseconds', (v) => parseIntFlag('--timeout-ms', v))
+        .option('--cache-ttl <ttl>', 'Cache freshness: 0, Nh (hours), or Nd (days), e.g. 48h, 2d, 0 (omitted → server default)', (v) => parseCacheTtl('--cache-ttl', v))
+        .option('-o, --output <file>', 'Write the fetched body bytes to the given file path')
         .action(async (opts) => {
         const g = getGlobal();
         const client = buildClient(g);
@@ -68,8 +104,11 @@ export function makeFetchCommand(getGlobal) {
             const result = await client.fetch.get({
                 url: opts.url,
                 ...(opts.format !== undefined ? { format: opts.format } : {}),
+                ...(opts.country !== undefined ? { country: opts.country } : {}),
+                ...(opts.timeoutMs !== undefined ? { timeout_ms: opts.timeoutMs } : {}),
+                ...(opts.cacheTtl !== undefined ? { cache_ttl: opts.cacheTtl } : {}),
             });
-            printResult(result, g.json);
+            emitFetchResult(result, g.json, { file: opts.output });
         }
         catch (err) {
             handleError(err);