@hunt-labs/bytekit-cli 0.3.0 → 0.6.0

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

@@ -1,7 +1,8 @@
 import { Command } from 'commander';
 import { buildClient } from '../client.js';
 import { printResult, handleError } from '../output.js';
-import { parseUrlLines } from '../lib/url-lines.js';
+import { parseBulkLines, toBulkItems } from '../lib/url-lines.js';
+import { parseJsonFlag } from '../lib/parse-flags.js';
 export function makeBulkCommand(getGlobal) {
     const cmd = new Command('bulk').description('Bulk screenshot operations');
     const screenshotsCmd = new Command('screenshots').description('Bulk screenshot sub-resources');
@@ -23,14 +24,31 @@ export function makeBulkCommand(getGlobal) {
     cmd
         .command('create')
         .description('Create a bulk screenshots job')
-        .requiredOption('--file <path>', 'Path to newline-delimited file of URLs (plain URL or {"url":"..."} per line)')
+        .requiredOption('--file <path>', 'Path to a newline-delimited file. Each line is a plain URL, or a JSON object carrying "url" plus per-item config. A line whose only key is "url" behaves exactly as before (sent as a bare URL string); any line with additional keys switches the payload to the per-item shape.')
         .requiredOption('--webhook-url <url>', 'HTTPS webhook URL notified when the job completes')
+        .option('--webhook-secret <secret>', 'HMAC secret used to sign the completion webhook (omitted → unsigned)')
+        .option('--defaults <json>', 'Defaults applied to every entry, as a JSON object (omitted → none). Unknown keys are rejected by /v1/bulk (422) and ignored by scrape bulk / fetch bulk; fetch bulk additionally rejects browser-only keys (cookies, wait_until, wait_for_selector, delay_ms) with a 400.', (v) => parseJsonFlag('--defaults', v, 'object'))
+        .option('--metadata <json>', `Arbitrary metadata echoed on the job envelope, as a JSON object, e.g. '{"run":"7"}' (omitted → none)`, (v) => parseJsonFlag('--metadata', v, 'object'))
+        // Deliberately NO --custom: /v1/bulk is `.strict()` at the top level with no `custom`
+        // property (validators/bulk.ts:135), so the flag would 422 every call (#2596 drift D2).
         .action(async (opts) => {
         const g = getGlobal();
         const client = buildClient(g);
         try {
-            const urls = parseUrlLines(opts.file);
-            const result = await client.bulk.create({ urls, webhook_url: opts.webhookUrl });
+            const lines = parseBulkLines(opts.file);
+            // `urls` XOR `items` (validators/bulk.ts:136-155) — send exactly one. A file of only
+            // url-only lines keeps the pre-#2596 `{ urls, webhook_url }` body, key order included,
+            // so existing callers are byte-identical on the wire (E2).
+            const body = lines.every((l) => typeof l === 'string')
+                ? { urls: lines, webhook_url: opts.webhookUrl }
+                : { items: toBulkItems(lines), webhook_url: opts.webhookUrl };
+            if (opts.webhookSecret !== undefined)
+                body['webhook_secret'] = opts.webhookSecret;
+            if (opts.defaults !== undefined)
+                body['defaults'] = opts.defaults;
+            if (opts.metadata !== undefined)
+                body['metadata'] = opts.metadata;
+            const result = await client.bulk.create(body);
             printResult(result, g.json);
         }
         catch (err) {
@@ -51,5 +69,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

@@ -1,8 +1,13 @@
 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 { parseBulkLines } from '../lib/url-lines.js';
+import { parseIntFlag, parseEnum, parseCacheTtl, parseJsonFlag } 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'];
+/** The `markdown_links` / `markdown_images` render-mode enum (shared with `scrape create`). */
+const MARKDOWN_RENDER_MODES = ['inline', 'references', 'none', 'text'];
 /**
  * Validate `--format` locally, before any HTTP request is issued.
  *
@@ -25,14 +30,31 @@ export function makeFetchCommand(getGlobal) {
     bulkCmd
         .command('create')
         .description('Create a bulk fetch job')
-        .requiredOption('--file <path>', 'Path to newline-delimited file of URLs (plain URL or {"url":"..."} per line)')
+        .requiredOption('--file <path>', 'Path to a newline-delimited file. Each line is a plain URL, or a JSON object carrying "url" plus per-item config. A line whose only key is "url" behaves exactly as before (sent as a bare URL string); any line with additional keys switches the payload to the per-item shape.')
         .requiredOption('--webhook-url <url>', 'HTTPS webhook URL notified when the job completes')
+        .option('--webhook-secret <secret>', 'HMAC secret used to sign the completion webhook (omitted → unsigned)')
+        .option('--defaults <json>', 'Defaults applied to every entry, as a JSON object (omitted → none). Unknown keys are rejected by /v1/bulk (422) and ignored by scrape bulk / fetch bulk; fetch bulk additionally rejects browser-only keys (cookies, wait_until, wait_for_selector, delay_ms) with a 400.', (v) => parseJsonFlag('--defaults', v, 'object'))
+        .option('--metadata <json>', `Arbitrary metadata echoed on the job envelope, as a JSON object, e.g. '{"run":"7"}' (omitted → none)`, (v) => parseJsonFlag('--metadata', v, 'object'))
+        // Deliberately NO --custom: /v1/fetch/bulk has no top-level `custom` property
+        // (validators/fetch-bulk.ts:52-62), so the flag would be silently stripped (#2596 drift D2).
+        // FetchBulkBodySchema itself stays non-strict (issue #2648 only makes the per-item
+        // FetchBulkItemOverrideSchema reject unknown keys), so this top-level behavior is unchanged.
         .action(async (opts) => {
         const g = getGlobal();
         const client = buildClient(g);
         try {
-            const urls = parseUrlLines(opts.file);
-            const result = await client.fetch.bulk.create({ urls, webhook_url: opts.webhookUrl });
+            // /v1/fetch/bulk has NO `items` property — its `urls` is a
+            // `string | FetchBulkItemOverride` union (validators/fetch-bulk.ts:57), so both line
+            // shapes ride there directly and no promotion step is needed (#2596 drift D3).
+            const urls = parseBulkLines(opts.file);
+            const body = { urls, webhook_url: opts.webhookUrl };
+            if (opts.webhookSecret !== undefined)
+                body['webhook_secret'] = opts.webhookSecret;
+            if (opts.defaults !== undefined)
+                body['defaults'] = opts.defaults;
+            if (opts.metadata !== undefined)
+                body['metadata'] = opts.metadata;
+            const result = await client.fetch.bulk.create(body);
             printResult(result, g.json);
         }
         catch (err) {
@@ -59,15 +81,67 @@ 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))
+        // The markdown surface below is POST-only: FetchGetOpts excludes it, so adding any of it to
+        // `get` 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('--markdown-query <q>', 'BM25 query string for relevance-ranked markdown filtering (omitted → disabled)')
+        .option('--markdown-links <mode>', `Link rendering: ${MARKDOWN_RENDER_MODES.join(', ')} (omitted → server default)`, (v) => parseEnum('--markdown-links', MARKDOWN_RENDER_MODES, v))
+        .option('--markdown-images <mode>', `Image retention: ${MARKDOWN_RENDER_MODES.join(', ')} (omitted → server default)`, (v) => parseEnum('--markdown-images', MARKDOWN_RENDER_MODES, v))
+        .option('--with-links-summary', 'Append a Links footer to the markdown output (omitted → off)')
+        .option('--with-images-summary', 'Append an Images footer to the markdown output (omitted → off)')
+        .option('--markdown-compact', 'Collapse excessive whitespace in the markdown output (omitted → off)')
+        .option('--markdown-filter-images', 'Filter low-signal images from the markdown output (omitted → off)')
+        .option('--markdown-include-media', 'Return rich link/image objects and a tables array (omitted → off)')
+        .option('--markdown-include-warnings', 'Include markdown-pipeline and tag-filter warnings (omitted → off)')
+        .option('--markdown-include-stats', 'Include a top-level stats object (chars, tokens, blocks) (omitted → off)')
+        .option('--custom <json>', `User payload echoed on the envelope as a JSON object, e.g. '{"job":"1"}' (omitted → none)`, (v) => parseJsonFlag('--custom', v, 'object'))
+        .option('-o, --output <file>', 'Write the fetched body bytes to the given file path')
         .action(async (opts) => {
         const g = getGlobal();
         const client = buildClient(g);
+        // Omit-when-absent body, in the `body: Record<string, unknown>` form every other command
+        // file uses (scrape.ts:230-268 is the exemplar). The five pre-existing fields keep the
+        // exact same wire output they had as inline spreads; a boolean is written ONLY on
+        // `=== true`, so it never serializes `false` (#2480 E1).
+        const body = { url: opts.url };
+        if (opts.format !== undefined)
+            body['format'] = opts.format;
+        if (opts.country !== undefined)
+            body['country'] = opts.country;
+        if (opts.timeoutMs !== undefined)
+            body['timeout_ms'] = opts.timeoutMs;
+        if (opts.cacheTtl !== undefined)
+            body['cache_ttl'] = opts.cacheTtl;
+        if (opts.markdownMode !== undefined)
+            body['markdown_mode'] = opts.markdownMode;
+        if (opts.markdownQuery !== undefined)
+            body['markdown_query'] = opts.markdownQuery;
+        if (opts.markdownLinks !== undefined)
+            body['markdown_links'] = opts.markdownLinks;
+        if (opts.markdownImages !== undefined)
+            body['markdown_images'] = opts.markdownImages;
+        if (opts.withLinksSummary === true)
+            body['with_links_summary'] = true;
+        if (opts.withImagesSummary === true)
+            body['with_images_summary'] = true;
+        if (opts.markdownCompact === true)
+            body['markdown_compact'] = true;
+        if (opts.markdownFilterImages === true)
+            body['markdown_filter_images'] = true;
+        if (opts.markdownIncludeMedia === true)
+            body['markdown_include_media'] = true;
+        if (opts.markdownIncludeWarnings === true)
+            body['markdown_include_warnings'] = true;
+        if (opts.markdownIncludeStats === true)
+            body['markdown_include_stats'] = true;
+        if (opts.custom !== undefined)
+            body['custom'] = opts.custom;
         try {
-            const result = await client.fetch.create({
-                url: opts.url,
-                ...(opts.format !== undefined ? { format: opts.format } : {}),
-            });
-            emitFetchResult(result, g.json);
+            const result = await client.fetch.create(body);
+            emitFetchResult(result, g.json, { file: opts.output });
         }
         catch (err) {
             handleError(err);
@@ -78,6 +152,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 +163,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);

package/dist/commands/monitors.js

@@ -1,20 +1,43 @@
 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. */
+import { parseEnum, parseIntFlag, parseNumberFlag, parseJsonFlag } from '../lib/parse-flags.js';
+/** The `listMonitors` `status` query enum (5-value list FILTER). */
 const MONITOR_STATUSES = ['active', 'processing', 'paused', 'cancelled', 'suspended'];
+/**
+ * The `MonitorUpdateRequest.status` enum — DISTINCT from {@link MONITOR_STATUSES}. Only `active`
+ * (resume) and `paused` (pause) are valid update targets (openapi.yaml MonitorUpdateRequest.status);
+ * the other three list-filter states are server-managed lifecycle states, not settable via PATCH.
+ */
+const MONITOR_UPDATE_STATUSES = ['active', 'paused'];
+/** The `notify_on` enum shared by MonitorCreateRequest / MonitorUpdateRequest. */
+const NOTIFY_ONS = ['change', 'every'];
+/** The create-only `type` enum (PATCH rejects `type` with 422 — immutable, issue #1984). */
+const MONITOR_TYPES = ['screenshot', 'scrape'];
 export function makeMonitorsCommand(getGlobal) {
     const cmd = new Command('monitors').description('Page-change monitor operations');
     const capturesCmd = new Command('captures').description('Monitor capture sub-resources');
     capturesCmd
         .command('list <id>')
         .description('List captures for a monitor')
-        .action(async (id) => {
+        .option('--limit <n>', 'Maximum number of captures to return', (v) => parseIntFlag('--limit', v))
+        .option('--cursor <cursor>', 'Pagination cursor from a previous page')
+        .action(async (id, opts) => {
         const g = getGlobal();
         const client = buildClient(g);
+        // Same omit-when-absent rule as `monitors list` (#2480): build the params object with
+        // ONLY the flags the caller passed, and call captures.list with a single argument (never
+        // captures.list(id, {}) / captures.list(id, undefined)) when no query flag is passed, so
+        // the inverse-case request-shape assertion stays byte-identical to today (#2594 DoD-4).
+        const params = {};
+        if (opts.limit !== undefined)
+            params.limit = opts.limit;
+        if (opts.cursor !== undefined)
+            params.cursor = opts.cursor;
         try {
-            const result = await client.monitors.captures.list(id);
+            const result = Object.keys(params).length > 0
+                ? await client.monitors.captures.list(id, params)
+                : await client.monitors.captures.list(id);
             printResult(result, g.json);
         }
         catch (err) {
@@ -29,21 +52,45 @@ export function makeMonitorsCommand(getGlobal) {
         .requiredOption('--interval-type <type>', 'Check interval: hourly, daily, weekly, or cron')
         .requiredOption('--webhook-url <url>', 'HTTPS webhook URL notified on change')
         .option('--cron <expr>', 'Cron expression (required when --interval-type is cron, e.g. "0 * * * *")')
+        // `--type` is CREATE-ONLY (a monitor's type is immutable per #1984); the PATCH builder below
+        // deliberately omits it.
+        .option('--type <type>', `Monitor type: ${MONITOR_TYPES.join(', ')} (omitted → server default screenshot)`, (v) => parseEnum('--type', MONITOR_TYPES, v))
+        .option('--change-threshold <pct>', 'Change percentage that triggers a notification (float; omitted → server default 5)', (v) => parseNumberFlag('--change-threshold', v))
+        .option('--notify-on <event>', `When to notify: ${NOTIFY_ONS.join(', ')} (omitted → server default change)`, (v) => parseEnum('--notify-on', NOTIFY_ONS, v))
+        .option('--webhook-secret <secret>', 'HMAC secret for webhook signature verification')
+        .option('--webhook-headers <json>', `Extra webhook headers as a JSON object, e.g. '{"X-Sig":"abc"}' (omitted → none)`, (v) => parseJsonFlag('--webhook-headers', v, 'object'))
+        .option('--options <json>', `Screenshot-monitor options as a JSON object (omitted → server defaults)`, (v) => parseJsonFlag('--options', v, 'object'))
+        .option('--scrape-options <json>', `Scrape-monitor options as a JSON object (type=scrape only; omitted → server defaults)`, (v) => parseJsonFlag('--scrape-options', v, 'object'))
+        .option('--metadata <json>', `Arbitrary metadata echoed on the monitor envelope, as a JSON object, e.g. '{"run":"7"}' (omitted → none)`, (v) => parseJsonFlag('--metadata', v, 'object'))
         .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).
+        // Omit-when-absent body (same rule as scrape.ts): each key is written ONLY when its flag is
+        // present, so a bare create never materializes a server default (#2480 E1). Typed via an
+        // assertion at the call site — the wire body is pinned by 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;
+        if (opts.type !== undefined)
+            body['type'] = opts.type;
+        if (opts.changeThreshold !== undefined)
+            body['change_threshold'] = opts.changeThreshold;
+        if (opts.notifyOn !== undefined)
+            body['notify_on'] = opts.notifyOn;
+        if (opts.webhookSecret !== undefined)
+            body['webhook_secret'] = opts.webhookSecret;
+        if (opts.webhookHeaders !== undefined)
+            body['webhook_headers'] = opts.webhookHeaders;
+        if (opts.options !== undefined)
+            body['options'] = opts.options;
+        if (opts.scrapeOptions !== undefined)
+            body['scrape_options'] = opts.scrapeOptions;
+        if (opts.metadata !== undefined)
+            body['metadata'] = opts.metadata;
         try {
             const result = await client.monitors.create(body);
             printResult(result, g.json);
@@ -58,6 +105,9 @@ export function makeMonitorsCommand(getGlobal) {
         .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))
+        // `status` is the SDK's spec-derived `MonitorStatus` union, not a bare string (#2547) —
+        // `parseEnum` above already returns exactly that union, so this is a type-only narrowing
+        // with no runtime change.
         .action(async (opts) => {
         const g = getGlobal();
         const client = buildClient(g);
@@ -97,20 +147,51 @@ export function makeMonitorsCommand(getGlobal) {
     });
     cmd
         .command('update <id>')
-        .description('Update a monitor')
+        .description('Update a monitor (including pause/resume via --status)')
+        .option('--url <url>', 'New URL to monitor (omitted → unchanged)')
         .option('--interval-type <type>', 'New check interval: hourly, daily, weekly, or cron')
         .option('--cron <expr>', 'New cron expression (when interval-type is cron, e.g. "0 * * * *")')
         .option('--webhook-url <url>', 'New HTTPS webhook URL')
+        // `--status` is the 2-value MonitorUpdateRequest.status enum — NOT the 5-value list filter.
+        // Deliberately NO `--type`: PATCH /v1/monitors/{id} rejects `type` with 422 (immutable, #1984).
+        .option('--status <status>', `Pause or resume the monitor: ${MONITOR_UPDATE_STATUSES.join(', ')}`, (v) => parseEnum('--status', MONITOR_UPDATE_STATUSES, v))
+        .option('--change-threshold <pct>', 'New change percentage that triggers a notification (float)', (v) => parseNumberFlag('--change-threshold', v))
+        .option('--notify-on <event>', `When to notify: ${NOTIFY_ONS.join(', ')}`, (v) => parseEnum('--notify-on', NOTIFY_ONS, v))
+        .option('--webhook-secret <secret>', 'New HMAC secret for webhook signature verification')
+        .option('--webhook-headers <json>', `New webhook headers as a JSON object, e.g. '{"X-Sig":"abc"}'`, (v) => parseJsonFlag('--webhook-headers', v, 'object'))
+        .option('--options <json>', `New screenshot-monitor options as a JSON object`, (v) => parseJsonFlag('--options', v, 'object'))
+        .option('--scrape-options <json>', `New scrape-monitor options as a JSON object`, (v) => parseJsonFlag('--scrape-options', v, 'object'))
+        .option('--metadata <json>', `New metadata as a JSON object, e.g. '{"run":"7"}' (omitted → unchanged)`, (v) => parseJsonFlag('--metadata', v, 'object'))
         .action(async (id, opts) => {
         const g = getGlobal();
         const client = buildClient(g);
         const body = {};
+        // `url` IS settable on PATCH (openapi.yaml MonitorUpdateRequest) — unlike `type`, which
+        // stays immutable and deliberately has no flag (#1984).
+        if (opts.url !== undefined)
+            body['url'] = opts.url;
         if (opts.intervalType !== undefined)
             body['interval_type'] = opts.intervalType;
         if (opts.cron !== undefined)
             body['cron_expression'] = opts.cron;
         if (opts.webhookUrl !== undefined)
             body['webhook_url'] = opts.webhookUrl;
+        if (opts.status !== undefined)
+            body['status'] = opts.status;
+        if (opts.changeThreshold !== undefined)
+            body['change_threshold'] = opts.changeThreshold;
+        if (opts.notifyOn !== undefined)
+            body['notify_on'] = opts.notifyOn;
+        if (opts.webhookSecret !== undefined)
+            body['webhook_secret'] = opts.webhookSecret;
+        if (opts.webhookHeaders !== undefined)
+            body['webhook_headers'] = opts.webhookHeaders;
+        if (opts.options !== undefined)
+            body['options'] = opts.options;
+        if (opts.scrapeOptions !== undefined)
+            body['scrape_options'] = opts.scrapeOptions;
+        if (opts.metadata !== undefined)
+            body['metadata'] = opts.metadata;
         try {
             const result = await client.monitors.update(id, body);
             printResult(result, g.json);