@hunt-labs/bytekit-cli 0.3.0 → 0.5.0

package/dist/client.js

@@ -38,6 +38,10 @@ function timeoutReason(ms) {
 /**
  * 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
@@ -53,17 +57,36 @@ function createAttemptBudget(ms) {
         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` 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.
+ * 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, whose `name` we also inspect as a
- * fallback for a caller-style AbortError).
+ * 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 rawName = typeof err === 'object' && err !== null && 'name' in err ? err.name : undefined;
-    const name = typeof rawName === 'string' ? rawName : '';
+    const name = abortNameOf(err) ?? '';
     let code;
     if (timedOut || name === 'TimeoutError') {
         code = 'timeout';
@@ -125,64 +148,57 @@ async function toApiError(response) {
     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?
+ * Perform the authenticated round-trip with a single bounded retry on 429, returning whatever the
+ * caller's `readBody` continuation makes of the successful response.
  *
- * 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.
+ * 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
+ * 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, timeoutMs = DEFAULT_TIMEOUT_MS) {
-    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);
-            }
-            // 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;
-            }
+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);
@@ -193,36 +209,86 @@ export function createRetryingRequest(apiKey, baseUrl, timeoutMs = DEFAULT_TIMEO
                 // 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) {
-                // 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;
+                try {
+                    return await readBody(response);
                 }
-                const text = await response.text();
-                if (response.status === 204 || text.trim().length === 0) {
-                    return undefined;
+                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);
                 }
-                return JSON.parse(text);
             }
             if (response.status === 429 && attempt < MAX_RETRIES) {
-                await sleep(parseRetryAfterMs(response.headers.get('Retry-After')));
-                continue;
+                retryAfterMs = parseRetryAfterMs(response.headers.get('Retry-After'));
             }
-            throw await toApiError(response);
+            else {
+                // `toApiError` reads the error body, so it too runs inside the budget.
+                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,
+        };
     };
 }
 /**
@@ -233,8 +299,10 @@ export function createRetryingRequest(apiKey, baseUrl, timeoutMs = DEFAULT_TIMEO
  *   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'];
@@ -245,5 +313,6 @@ export function buildClient(opts) {
     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,136 +1,19 @@
 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).
+ * 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.
  */
-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');
-    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('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)')
-        .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.js

@@ -2,7 +2,10 @@ import { Command, InvalidArgumentError } from 'commander';
 import { buildClient } from '../client.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.
  *
@@ -59,15 +62,27 @@ export function makeFetchCommand(getGlobal) {
         .description('Fetch URL content (POST)')
         .requiredOption('--url <url>', 'URL to fetch')
         .option('--format <format>', 'Response format (markdown or html)', parseFormat)
+        .option('--country <cc>', 'Two-letter country code to route the request through (e.g. us, de)')
+        .option('--timeout-ms <n>', 'Per-request timeout in milliseconds', (v) => parseIntFlag('--timeout-ms', v))
+        .option('--cache-ttl <ttl>', 'Cache freshness: 0, Nh (hours), or Nd (days), e.g. 48h, 2d, 0 (omitted → server default)', (v) => parseCacheTtl('--cache-ttl', v))
+        // `--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 } : {}),
             });
-            emitFetchResult(result, g.json);
+            emitFetchResult(result, g.json, { file: opts.output });
         }
         catch (err) {
             handleError(err);
@@ -78,6 +93,10 @@ export function makeFetchCommand(getGlobal) {
         .description('Fetch URL content (GET via query params)')
         .requiredOption('--url <url>', 'URL to fetch')
         .option('--format <format>', 'Response format (markdown or html)', parseFormat)
+        .option('--country <cc>', 'Two-letter country code to route the request through (e.g. us, de)')
+        .option('--timeout-ms <n>', 'Per-request timeout in milliseconds', (v) => parseIntFlag('--timeout-ms', v))
+        .option('--cache-ttl <ttl>', 'Cache freshness: 0, Nh (hours), or Nd (days), e.g. 48h, 2d, 0 (omitted → server default)', (v) => parseCacheTtl('--cache-ttl', v))
+        .option('-o, --output <file>', 'Write the fetched body bytes to the given file path')
         .action(async (opts) => {
         const g = getGlobal();
         const client = buildClient(g);
@@ -85,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 } : {}),
             });
-            emitFetchResult(result, g.json);
+            emitFetchResult(result, g.json, { file: opts.output });
         }
         catch (err) {
             handleError(err);