ubuyfirst 0.1.0

package/dist/program-YTm6g9Ut.js

@@ -0,0 +1,2522 @@
+#!/usr/bin/env node
+import { Command, CommanderError } from "commander";
+import { chmod, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import envPaths from "env-paths";
+import { styleText } from "node:util";
+import { createInterface } from "node:readline/promises";
+import { text } from "node:stream/consumers";
+//#region package.json
+var version = "0.1.0";
+//#endregion
+//#region src/errors.ts
+/**
+* The IO gate (Castle Rule). Returns the payload for a well-formed envelope and
+* `null` for anything else — an HTML 404 page from a wrong `--base-url`, an
+* un-enveloped body, a bare string. The caller turns `null` into exit 1 rather
+* than absorbing it into an error code (spec 301: "no status fallback").
+*/
+function readErrorEnvelope(value) {
+	if (typeof value !== "object" || value === null) return null;
+	if (!("error" in value)) return null;
+	const error = value.error;
+	if (typeof error !== "object" || error === null) return null;
+	if (!("code" in error) || !("retriable" in error) || !("message" in error)) return null;
+	const { code, retriable, message } = error;
+	if (typeof code !== "string") return null;
+	if (typeof retriable !== "boolean") return null;
+	if (typeof message !== "string") return null;
+	return {
+		code,
+		retriable,
+		message
+	};
+}
+/**
+* A failure the SERVER reported in its own envelope.
+*
+* `envelope` is the parsed body exactly as received, kept because `--json` must
+* emit it verbatim — re-serializing `payload` would silently drop any field the
+* server added and this build does not know about.
+*/
+var ApiCallError = class extends Error {
+	payload;
+	envelope;
+	constructor(payload, envelope) {
+		super(payload.message);
+		this.name = "ApiCallError";
+		this.payload = payload;
+		this.envelope = envelope;
+	}
+};
+/**
+* A failure the CLI decided locally, carrying the exit code it means: a usage
+* error (2), no resolvable API key (4), or a response that is not an envelope
+* at all (1). Callers pass the constant from `exit-codes.ts`.
+*/
+var CliError = class extends Error {
+	exitCode;
+	constructor(exitCode, message) {
+		super(message);
+		this.name = "CliError";
+		this.exitCode = exitCode;
+	}
+};
+const EXIT_BY_ERROR_CODE = {
+	VALIDATION: 3,
+	HTTP_401: 4,
+	ACCESS_DENIED: 5,
+	HTTP_403: 5,
+	AMBIGUOUS: 6,
+	CAP_EXCEEDED: 7,
+	HTTP_429: 8,
+	WRITE_FAILED: 9,
+	HTTP_5XX: 10
+};
+/**
+* Codes for a failure the CLI decided ITSELF, for the `--json` document it emits
+* when there is no server envelope to echo (spec 301 → CLI → Output,
+* acceptance 5: `--json` on ANY command emits exactly one parseable document).
+*
+* Every value is namespaced `cli.`, and that prefix is the whole design. The
+* server's error vocabulary is frozen and public; minting `USAGE` alongside it
+* would put a value in that vocabulary no server ever sends. A consumer tells a
+* client-side refusal from a server one by the prefix alone, and
+* `exitCodeForErrorCode` above stays a table over the server's codes only.
+*
+* `runCommand` emits this automatically — a command module never builds one.
+*/
+const CLI_ERROR_CODE = {
+	/** Bad, missing or mutually-exclusive flags. */
+	usage: "cli.usage",
+	/** No API key resolvable from either source. */
+	noKey: "cli.no_key",
+	/** Anything else the CLI decided: a body that is no envelope, a dead host. */
+	unexpected: "cli.unexpected"
+};
+/**
+* The local code for an exit this CLI chose.
+*
+* Derived from the exit code rather than carried on each `CliError`, so the
+* dozen existing throw sites keep working and there is one place where a new
+* local exit picks up a name.
+*/
+function cliErrorCodeForExit(exitCode) {
+	if (exitCode === 2) return CLI_ERROR_CODE.usage;
+	if (exitCode === 4) return CLI_ERROR_CODE.noKey;
+	return CLI_ERROR_CODE.unexpected;
+}
+/**
+* Looks a key up in a table WITHOUT inheriting Object.prototype.
+*
+* `table[code]` alone answers a FUNCTION for `toString`, `constructor`,
+* `valueOf` and `hasOwnProperty` — every one of them a string a server is free
+* to send — and `?? fallback` never fires on a function. The value then reaches
+* `process.exitCode`, which throws `ERR_INVALID_ARG_TYPE` from inside
+* `runCommand`'s own catch block and escapes as an unhandled rejection instead
+* of exiting. `Object.hasOwn` is what makes these tables closed.
+*/
+function ownValue(table, key) {
+	return Object.hasOwn(table, key) ? table[key] ?? null : null;
+}
+/**
+* Takes the code a live server actually sent, which is why the parameter is
+* `string`: a server one deploy ahead of the committed types can name a code
+* this build has no row for. That is exit 1 — unexpected — not a guess.
+*/
+function exitCodeForErrorCode(code) {
+	return ownValue(EXIT_BY_ERROR_CODE, code) ?? 1;
+}
+/**
+* The three aspects this exit code is derived from, TOTAL over the response's
+* own keys: an aspect added or removed fails typecheck here rather than being
+* read as an outcome, or quietly not read at all.
+*/
+const IS_ASPECT = {
+	schedule: true,
+	interval: true,
+	filterRules: true
+};
+/**
+* Which outcomes mean nothing is outstanding. TOTAL over the generated enum, so
+* a fifth outcome value fails typecheck instead of defaulting to "fine".
+*
+* Stated as SETTLED rather than as PARTIAL so the default runs the safe way: an
+* outcome missing from this table is not settled, and a server one deploy ahead
+* naming a fifth value exits 11 rather than reporting a write it never
+* confirmed. `skipped` IS settled — it means the caller never asked for that
+* aspect.
+*/
+const SETTLED_BY_ASPECT_OUTCOME = {
+	updated: true,
+	skipped: true,
+	failed: false,
+	not_attempted: false
+};
+/**
+* The one action whose 200 can still mean failure:
+* `update-notification-channel-settings` writes three aspects against three
+* tables with no transaction across them and returns a per-aspect outcome map.
+* A client that reads that 200 as success reports writes that never occurred.
+*
+* The blocklist per-entry outcomes are deliberately NOT routed here:
+* `already_present` and `not_found` are documented normal successes — the
+* requested state holds — so they exit 0.
+*/
+function exitCodeForChannelSettings(result) {
+	return Object.keys(IS_ASPECT).every((aspect) => {
+		const outcome = Reflect.get(result, aspect);
+		if (typeof outcome !== "string") return false;
+		return ownValue(SETTLED_BY_ASPECT_OUTCOME, outcome) ?? false;
+	}) ? 0 : 11;
+}
+//#endregion
+//#region src/config.ts
+/**
+* The CLI's config file — its location, its two fields, and the modes it is
+* created with (spec 301 → CLI → Auth and configuration).
+*
+* This module is the SINGLE owner of that file. The `config` command group
+* renders and prompts; it never re-implements the path, the parse or the modes,
+* so there is one place where a permission mistake could be made and one place
+* to audit.
+*/
+const CONFIG_FILE_NAME = "config.json";
+/**
+* `suffix: ''` drops env-paths' default `-nodejs`: the directory belongs to a
+* user-facing binary called `ubuyfirst`, and the runtime it happens to be
+* written in is not part of that name.
+*/
+function defaultConfigDir() {
+	return envPaths("ubuyfirst", { suffix: "" }).config;
+}
+function configFilePath(dir = defaultConfigDir()) {
+	return join(dir, CONFIG_FILE_NAME);
+}
+function malformed(path, detail) {
+	return new CliError(1, `${path} is not a usable ubuyfirst config file: ${detail}`);
+}
+/** The `code` off a Node system error, as `unknown` until proven a string. */
+function errorCode(thrown) {
+	if (typeof thrown !== "object" || thrown === null) return null;
+	const code = Reflect.get(thrown, "code");
+	return typeof code === "string" ? code : null;
+}
+/** Blank is not a value — a botched `set-key` must not become an empty Bearer. */
+function readStringField(source, field, path) {
+	if (!(field in source)) return null;
+	const value = Reflect.get(source, field);
+	if (value === null) return null;
+	if (typeof value !== "string") throw malformed(path, `"${field}" is not a string.`);
+	const trimmed = value.trim();
+	return trimmed === "" ? null : trimmed;
+}
+/**
+* Reads the config file. An ABSENT file is an empty config, not a failure — the
+* CLI is usable with `UBUYFIRST_API_KEY` alone and never requires a write.
+*
+* A file that EXISTS but cannot be read is a failure, and deliberately a fatal
+* one for every command rather than only for `config show`. Two reasons, and the
+* second is the load-bearing one:
+*   - swallowing the error makes `config show` report "no key" about a file that
+*     holds one, sending the user to set a key they already set;
+*   - the file also carries `baseUrl`. Continuing would silently fall back to
+*     the default host, so a walk configured against a self-hosted target would
+*     send its key somewhere the user did not choose. Refusing names the path
+*     and the OS error; guessing does not.
+*
+* So the env var alone serves a MISSING config file, not a broken one. Unknown
+* FIELDS are still ignored on purpose, so a file written by a newer CLI does not
+* brick an older one.
+*/
+async function readConfig(dir = defaultConfigDir()) {
+	const path = configFilePath(dir);
+	let raw;
+	try {
+		raw = await readFile(path, "utf8");
+	} catch (thrown) {
+		const code = errorCode(thrown);
+		if (code === "ENOENT") return {
+			apiKey: null,
+			baseUrl: null
+		};
+		throw malformed(path, `it could not be read (${code ?? "unknown error"}).`);
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		throw malformed(path, "it is not valid JSON.");
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw malformed(path, "its top level is not a JSON object.");
+	return {
+		apiKey: readStringField(parsed, "apiKey", path),
+		baseUrl: readStringField(parsed, "baseUrl", path)
+	};
+}
+const CONFIG_DIR_MODE = 448;
+const CONFIG_FILE_MODE = 384;
+/**
+* Whether the config file is already there — the one question that decides which of the
+* two write paths below applies.
+*
+* A `stat` that fails for any reason OTHER than "no such file" is re-thrown rather than
+* read as absence: answering "absent" to an EACCES would take the creation path, whose
+* `mode` a pre-existing file ignores, and the tightening would be skipped on exactly the
+* file whose permissions could not be inspected.
+*/
+async function configFileExists(path) {
+	try {
+		await stat(path);
+		return true;
+	} catch (thrown) {
+		if (errorCode(thrown) === "ENOENT") return false;
+		throw thrown;
+	}
+}
+/**
+* Narrows a config file that already exists to `0600`.
+*
+* ENOENT is the ONE code that degrades rather than aborting: the file was there a
+* moment ago and is not now — a concurrent `config clear`, a temp-directory reaper — and
+* the write that follows then CREATES it `0600`, which is the state this call was
+* reaching for. Refusing would abort a `set-key` that was about to succeed, naming a path
+* that no longer exists.
+*
+* Every other code still refuses. An EPERM says the file IS there and could not be
+* narrowed, so continuing would write the key into it under whatever mode it already had.
+*/
+async function tighten(path) {
+	try {
+		await chmod(path, CONFIG_FILE_MODE);
+	} catch (thrown) {
+		if (errorCode(thrown) !== "ENOENT") throw thrown;
+	}
+}
+/**
+* Writes the config file, creating the directory `0700` and the file `0600` IN
+* THE SAME CALL that creates each. A file this function CREATES is never
+* chmod'd afterwards: a create-then-chmod leaves a window in which the key is
+* world-readable.
+*
+* AN ALREADY-EXISTING FILE IS THE OTHER HALF, and `mode` cannot serve it: the
+* flag applies only at creation, so a config left `0644` by a shell redirect or
+* by a build of this CLI from before the modes existed keeps `0644` through
+* every `set-key`, with the plaintext key readable by every other account on the
+* host. It is chmod'd BEFORE the new contents are written, never after — the
+* file is narrowed while it still holds the OLD document, so there is no moment
+* at which the key is present under the looser mode. The two paths are exclusive:
+* a created file takes no chmod at all, and only a pre-existing one takes one.
+*
+* Two honest limits. `mode` is masked by the process umask, so a hostile umask
+* can only make these TIGHTER, never looser. And on Windows both modes are
+* advisory — Node maps a POSIX mode onto the read-only attribute there; it is
+* not an ACL and grants no protection. `--help` says so rather than implying a
+* guarantee the platform does not make.
+*
+* Null fields are omitted rather than stored as JSON nulls, so `config clear`
+* leaves `{}` instead of a document that still names the key it dropped.
+*/
+async function writeConfig(config, dir = defaultConfigDir()) {
+	const document = {};
+	if (config.apiKey !== null) document["apiKey"] = config.apiKey;
+	if (config.baseUrl !== null) document["baseUrl"] = config.baseUrl;
+	const path = configFilePath(dir);
+	await mkdir(dir, {
+		recursive: true,
+		mode: CONFIG_DIR_MODE
+	});
+	if (await configFileExists(path)) await tighten(path);
+	await writeFile(path, `${JSON.stringify(document, null, 2)}\n`, { mode: CONFIG_FILE_MODE });
+}
+/**
+* What `config show` is allowed to know. The key is reduced to a boolean HERE,
+* so "never print the key" is a property of the type rather than something each
+* renderer has to remember (spec 301: not masked, absent).
+*/
+function summarizeConfig(config, path, effectiveBaseUrl) {
+	return {
+		path,
+		keyIsSet: config.apiKey !== null,
+		baseUrl: effectiveBaseUrl
+	};
+}
+//#endregion
+//#region src/auth.ts
+const API_KEY_ENV_VAR = "UBUYFIRST_API_KEY";
+/** Blank is unset. An empty `Bearer ` would be a 401 the CLI could have refused locally. */
+function present(value) {
+	const trimmed = value?.trim() ?? "";
+	return trimmed === "" ? null : trimmed;
+}
+/**
+* C0 controls plus DEL. CR and LF are the ones that matter: Node's fetch refuses
+* an Authorization value containing them by throwing `Headers.append: "Bearer
+* <THE WHOLE KEY>" is an invalid header value.` — and `runCommand` prints a
+* thrown error's message, so a key pasted with a line break in it would land in
+* the user's terminal and in whatever captured that output.
+*/
+const CONTROL_CHARACTERS = /[\u0000-\u001F\u007F]/;
+/**
+* Refuses a key that cannot become a header, naming WHERE it came from and
+* never WHAT it was.
+*
+* Checked here because this is where a key ENTERS the CLI, and because the
+* refusal has to happen before any request exists (acceptance 10). That covers
+* both real sources — the env var and the config file — and so every key
+* `resolveApiClient` produces. It is not a guarantee about `ApiClient` itself:
+* that type takes any `apiKey: string`, and a caller assembling one by hand
+* bypasses this. `resolveApiClient` is the only sanctioned way to build one.
+*/
+function usableKey(key, source) {
+	if (CONTROL_CHARACTERS.test(key)) throw new CliError(4, `The API key from ${source} contains a control character and cannot be sent as an Authorization header. Re-copy it as a single line. Its value is deliberately not shown.`);
+	return key;
+}
+/**
+* Two sources, one order: `UBUYFIRST_API_KEY`, then the config file.
+*
+* There is deliberately NO `--api-key` flag, which is why argv is not an input
+* here — a key passed on the command line lands in the shell history and in the
+* process table.
+*
+* The refusal names both sources and the config path, and nothing else. It
+* never echoes a value it did find.
+*/
+function resolveApiKey(input) {
+	const fromEnv = present(input.env[API_KEY_ENV_VAR]);
+	if (fromEnv !== null) return usableKey(fromEnv, API_KEY_ENV_VAR);
+	const fromConfig = present(input.config.apiKey);
+	if (fromConfig !== null) return usableKey(fromConfig, input.configPath);
+	throw new CliError(4, `No API key. Set ${API_KEY_ENV_VAR}, or store one with "ubuyfirst config set-key" (${input.configPath}).`);
+}
+/** `--base-url` > `UBUYFIRST_API_URL` > config `baseUrl` > the documented default. */
+function resolveBaseUrl(input) {
+	return present(input.flag) ?? present(input.env["UBUYFIRST_API_URL"]) ?? present(input.config.baseUrl) ?? "https://app.ubuyfirst.com";
+}
+/**
+* The composition every command calls. Resolution happens BEFORE any request
+* exists, so a missing key exits 4 with no HTTP call made (acceptance 10) — the
+* fetch it was handed is never touched.
+*/
+async function resolveApiClient(options = {}) {
+	const env = options.env ?? process.env;
+	const configDir = options.configDir ?? defaultConfigDir();
+	const config = await readConfig(configDir);
+	return {
+		fetch: options.fetch ?? globalThis.fetch,
+		apiKey: resolveApiKey({
+			env,
+			config,
+			configPath: configFilePath(configDir)
+		}),
+		baseUrl: resolveBaseUrl({
+			flag: options.baseUrlFlag ?? null,
+			env,
+			config
+		})
+	};
+}
+//#endregion
+//#region src/call-action.ts
+/**
+* The CLI's whole transport (spec 301 → CLI → Transport).
+*
+* One helper, not seventeen generated wrappers: it owns the URL, the two
+* headers, the envelope decode and the typed answer, so every command module is
+* argument mapping and rendering only.
+*
+* It is also the ONE typed seam. Request and response types are read off the
+* committed generated `paths` map; nothing else in `cli/` touches generated
+* types.
+*/
+const PUBLIC_API_PREFIX = "/api/public/v1";
+/**
+* The deadline for ONE action call, covering the response body as well as the request.
+*
+* Node's own defaults are not this, and the difference is the reason the constant exists.
+* Undici gives `fetch` a 300s `headersTimeout` and a 300s `bodyTimeout`, so a dead peer
+* does eventually fail — but each bounds an IDLE period separately, and a peer trickling
+* one byte at a time resets both forever. `AbortSignal` bounds the TOTAL, and it is
+* created before the fetch so it still governs `response.json()`.
+*
+* Two minutes, not a tighter number. This has to sit above the slowest action the API
+* serves — a 1,000-row import, executed inside one database transaction — because a
+* deadline that fires on work about to succeed turns a slow import into a call whose
+* answer never arrived, which is the one outcome this API's own documentation tells a
+* client it cannot safely retry. It is a fixed constant rather than a `--timeout` flag:
+* the override would have to be threaded from the program's global options through
+* `resolveApiClient` and every command's context, which is a lot of surface for a number
+* nobody has yet needed to change.
+*/
+const REQUEST_TIMEOUT_MS = 12e4;
+async function parseJsonBody(response) {
+	try {
+		return {
+			ok: true,
+			value: await response.json()
+		};
+	} catch {
+		return { ok: false };
+	}
+}
+/**
+* Deliberately names the URL and the status and NOTHING else. The API key is
+* never part of anything the CLI prints.
+*/
+function notThisApi(url, status) {
+	return new CliError(1, `${url} answered HTTP ${status} with a body that is not this API's JSON envelope. Check --base-url.`);
+}
+/**
+* The one refusal `REQUEST_TIMEOUT_MS` produces, worded the same wherever the deadline
+* fires — and it can fire in two places that fail very differently.
+*
+* Before the headers, `fetch` itself rejects and the raw `TimeoutError` says only "The
+* operation was aborted due to timeout", naming neither the target nor the deadline.
+* DURING THE BODY it is worse, and it is the case the deadline was added for: a trickling
+* peer's stream errors inside `parseJsonBody`, whose catch cannot tell that from an HTML
+* 404 page, so the answer was `notThisApi` — "Check --base-url" about a base URL that was
+* correct. One message for one condition, so neither phase sends the user somewhere else.
+*
+* It names the retry hazard rather than inviting a retry: an abandoned request is
+* indistinguishable from one that never ran, which for a write is the one case this API's
+* own documentation says not to blind-retry.
+*/
+function timedOut(url) {
+	return new CliError(1, `${url} did not answer within ${REQUEST_TIMEOUT_MS / 1e3} seconds, so the request was abandoned. It may still have been applied — if it was a write, read the account back before sending it again.`);
+}
+/**
+* Sends one action call and returns its 200 body.
+*
+* Failure modes, kept distinct on purpose (spec 301: "ONE envelope, one table,
+* no status fallback"):
+*   - the server's own error envelope becomes `ApiCallError`, and the exit code
+*     comes from its `code` alone;
+*   - anything else — an HTML 404 page from a wrong `--base-url`, an
+*     un-enveloped JSON body, a non-object 200 — becomes `CliError` at exit 1.
+*     Absorbing those into an error code is exactly what the removed status
+*     fallback used to do.
+*/
+async function callAction(client, path, body) {
+	const url = `${client.baseUrl.replace(/\/+$/, "")}${PUBLIC_API_PREFIX}/${path}`;
+	const signal = AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+	let response;
+	try {
+		response = await client.fetch(url, {
+			method: "POST",
+			headers: {
+				Authorization: `Bearer ${client.apiKey}`,
+				"Content-Type": "application/json"
+			},
+			body: JSON.stringify(body),
+			signal
+		});
+	} catch (thrown) {
+		if (signal.aborted) throw timedOut(url);
+		throw thrown;
+	}
+	const parsed = await parseJsonBody(response);
+	if (!parsed.ok) throw signal.aborted ? timedOut(url) : notThisApi(url, response.status);
+	const payload = readErrorEnvelope(parsed.value);
+	if (payload !== null) throw new ApiCallError(payload, parsed.value);
+	if (!response.ok) throw notThisApi(url, response.status);
+	if (typeof parsed.value !== "object" || parsed.value === null || Array.isArray(parsed.value)) throw notThisApi(url, response.status);
+	return parsed.value;
+}
+//#endregion
+//#region src/input.ts
+/**
+* `--input <json | @file | ->`, the general body escape hatch
+* (spec 301 → CLI → Argument rules).
+*
+* Four command groups offered the flag and four implemented the same three
+* steps — resolve the source, parse it, refuse anything that is not a JSON
+* object — with four different wordings for the same three refusals. AGENTS.md
+* says extract at three copies; this is that extraction.
+*
+* What is shared is the MECHANISM only. Where the parsed object then goes is
+* deliberately NOT here, because the commands genuinely disagree about it:
+* `searches update` wraps it as `{ id, changes }`, `blocklist add` reads
+* `entries` out of it while `type` comes from the flag, and `notifications
+* settings` spreads it with `id` LAST so the positional argument always wins.
+* Folding those into one shape would change what each command sends.
+*/
+/** `-` is stdin, `@path` is a file, anything else is the literal itself. */
+async function readSource(raw, readStdin) {
+	if (raw === "-") return readStdin();
+	if (!raw.startsWith("@")) return raw;
+	const path = raw.slice(1);
+	try {
+		return await readFile(path, "utf8");
+	} catch (thrown) {
+		throw new CliError(2, `Cannot read --input file ${path}: ${thrown instanceof Error ? thrown.message : String(thrown)}`);
+	}
+}
+/**
+* Reads `--input` and checks the ONE thing the CLI checks about it: that it is a
+* JSON object. Nothing here inspects a field name or a value.
+*
+* The assertion on the last line is over a PROVEN non-null, non-array object —
+* the request-side twin of the one `call-action.ts` makes on a 200 body, and now
+* the only one the CLI performs on an `--input` document.
+*/
+async function readInputObject(request) {
+	const text = await readSource(request.raw, request.readStdin);
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch {
+		throw new CliError(2, "--input is not valid JSON.");
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new CliError(2, `--input must be a JSON object, not an array or a scalar.${request.expects === void 0 ? "" : ` ${request.expects}`}`);
+	return parsed;
+}
+//#endregion
+//#region src/paging.ts
+/**
+* The `--all` walker (spec 301 → CLI → Paging).
+*
+* Six reads are cursor-paginated. Default is ONE page; `--limit` and `--cursor`
+* pass through unchanged. `--all` is the only thing in this module.
+*/
+/**
+* `--all` and `--cursor` together are a usage error: `--all` starts from the
+* beginning by definition, so the two state different intentions and merging
+* them would silently honour one.
+*/
+function assertPagingFlags(flags) {
+	if (flags.all && flags.cursor !== null && flags.cursor !== void 0) throw new CliError(2, "Use --all or --cursor, not both. --all starts from the first page.");
+}
+/**
+* Walks every page and returns ONE synthesized document: the LAST page's
+* envelope with the row array concatenated across pages, `hasMore: false` and
+* `nextCursor: null`.
+*
+* That synthesized document is the single deliberate exception to "`--json`
+* emits the raw envelope" — and because the result is still a page of the same
+* shape, it needs no special case downstream: `runCommand` emits it verbatim
+* under `--json`, the human renderer reads its rows, and `continuationLine`
+* correctly falls silent on `hasMore: false`.
+*
+* `fetchPage` receives ONLY the cursor, which is what forces the caller to
+* repeat every other input field itself. A cursor carries none of them: for
+* `blocklist list` that means `type` AND `scope`, and the three lists number
+* their rows independently, so a cursor reused across types is not refused — it
+* resumes at a meaningless position.
+*
+* Two server states RAISE rather than end the walk: `hasMore: true` with no
+* cursor, and a page that hands back the very cursor it was given. Both mean
+* the walk cannot complete — the first has no position to resume from, the
+* second makes no progress and would re-fetch one page until the heap is gone —
+* and both used to be survivable by returning what had been collected so far.
+* That is the worse answer: `--all` exists because a partial answer is
+* indistinguishable from a complete one, and `searches export` implies `--all`
+* precisely because a truncated export is a corrupt backup.
+*
+* NON-PROGRESS is the test, deliberately, and not "a cursor seen before". The
+* server pages with Prisma `cursor: { id }, skip: 1`, which locates the cursor
+* row in the order that holds AT READ TIME — and folders order by the MUTABLE
+* `sortOrder`. So another client moving a row mid-walk can legitimately bring an
+* earlier cursor round again on a walk that still terminates, and rejecting any
+* repeat would abort it. Only the server returning the cursor it was just handed
+* proves the walk is not advancing.
+*
+* `rowsKey` is a plain `string`, deliberately. Tying it to `keyof Page` LOOKS
+* stronger and is a trap: an arrow with an unannotated `cursor` is
+* context-sensitive, so TypeScript resolves `rowsKey`'s constraint in an earlier
+* inference round, while `Page` is still the bare `PageEnvelope` — and then
+* refuses `'entries'` on a call that is entirely correct. The runtime guard
+* below is what actually holds, and it holds against the case a type never
+* could: a live server whose shape differs from the committed document.
+*
+* SEVERAL KEYS may be named, because one paged answer can carry more than one
+* per-page array. `export_item_filters` returns `filters` AND `skipped` — the
+* export's machine-readable admission that a row was too large or too deep to
+* carry — and `skipped` accumulates page by page exactly as the rows do.
+* Concatenating only the rows would keep the LAST page's `skipped` and discard
+* every earlier one, which is the same silent truncation this walker exists to
+* prevent, in the one field whose whole job is to report it.
+*
+* A key NOT named keeps its LAST-PAGE value, and that is load-bearing for
+* `customFieldDefinitions`: it is whole-account and repeats verbatim on every
+* page, so concatenating it would emit each definition once per page walked.
+* Per-page arrays are named; whole-account ones are not.
+*/
+async function walkAllPages(fetchPage, rowsKey) {
+	const keys = typeof rowsKey === "string" ? [rowsKey] : rowsKey;
+	const collected = new Map(keys.map((key) => [key, []]));
+	let cursor = null;
+	let page;
+	for (;;) {
+		page = await fetchPage(cursor);
+		for (const key of keys) {
+			const pageRows = Reflect.get(page, key);
+			if (!Array.isArray(pageRows)) throw new CliError(1, `A page of results carried no "${key}" array. The server answered a shape this build does not know.`);
+			const rowValues = pageRows;
+			collected.get(key)?.push(...rowValues);
+		}
+		if (!page.hasMore) break;
+		if (page.nextCursor === null) throw new CliError(1, `The server reported more results but sent no cursor to resume from, so "--all" cannot complete. Re-run without --all to page manually.`);
+		if (page.nextCursor === cursor) throw new CliError(1, `The server returned the same paging cursor it was given, so "--all" would fetch the same page forever. Re-run without --all to page manually.`);
+		cursor = page.nextCursor;
+	}
+	return Object.assign({}, page, {
+		hasMore: false,
+		nextCursor: null
+	}, Object.fromEntries(collected));
+}
+//#endregion
+//#region src/render.ts
+/**
+* Output and exit discipline (spec 301 → CLI → Output, Exit codes).
+*
+* Every command runs through `runCommand`, so envelope handling, the exit-code
+* derivation and the two output modes exist once. A command module supplies the
+* call and its column set and nothing else.
+*/
+/**
+* The production wiring.
+*
+* `process.exitCode = n` and RETURN — never `process.exit()` after writing.
+* `process.exit()` tears the process down before a piped stdout has drained,
+* and the large `--json` payload is exactly the case that loses data
+* (acceptance 7).
+*/
+function processOutput(json) {
+	return {
+		stdout: { write: (chunk) => void process.stdout.write(chunk) },
+		stderr: { write: (chunk) => void process.stderr.write(chunk) },
+		json,
+		setExitCode: (code) => {
+			process.exitCode = code;
+		}
+	};
+}
+/**
+* The line human mode prints whenever another page remains. Without it a
+* truncated page reads as the whole list — the failure every paged endpoint's
+* own documentation warns about — so it names BOTH ways forward.
+*
+* `hasMore: true` with no cursor yields nothing: there is no position to resume
+* from, and inviting a caller to re-run with an absent cursor is worse advice
+* than silence.
+*/
+function continuationLine(data) {
+	if (typeof data !== "object" || data === null) return null;
+	if (!("hasMore" in data) || !("nextCursor" in data)) return null;
+	const { hasMore, nextCursor } = data;
+	if (hasMore !== true) return null;
+	if (typeof nextCursor !== "string") return null;
+	return `More results remain. Re-run with --all for every page, or --cursor ${nextCursor} for the next one.`;
+}
+/**
+* A fixed column set, one row per record. Emits NOTHING for an empty result:
+* a lone header row reads as a table whose rows failed to render, where no
+* output plainly means no records.
+*/
+function renderTable(headers, rows, line) {
+	if (rows.length === 0) return;
+	const widths = headers.map((header, column) => rows.reduce((widest, row) => Math.max(widest, (row[column] ?? "").length), header.length));
+	const format = (cells) => cells.map((cell, column) => column === cells.length - 1 ? cell : cell.padEnd(widths[column] ?? 0)).join("  ").trimEnd();
+	line(format(headers));
+	for (const row of rows) line(format(row));
+}
+/**
+* Node's own `styleText` — no chalk, no picocolors. It honors `NO_COLOR` and
+* strips color on a non-TTY by itself, so the CLI adds no detection of its own.
+* Bound to stderr because that is the stream this text goes to; `--json` output
+* never passes through here, so it is never colored.
+*/
+function errorPrefix() {
+	return styleText("red", "error:", { stream: process.stderr });
+}
+/**
+* Runs one command and owns everything that happens to its answer.
+*
+* `--json` emits exactly one newline-terminated document on stdout: the action's
+* `data` body on success, the server's error envelope VERBATIM on failure, with
+* stderr empty either way (acceptance 5).
+*
+* A LOCALLY-decided failure — a usage error, no resolvable key, a response that
+* is no envelope — has no server envelope to echo. Under `--json` it emits an
+* equivalent document carrying a `cli.`-namespaced code, because acceptance 5
+* says ANY command under `--json` writes exactly one parseable document and
+* empty stdout breaks that for every consumer. The namespace is what keeps the
+* server's frozen vocabulary untouched: see `CLI_ERROR_CODE`.
+*
+* Without `--json` the same failure stays prose on stderr, and the exit code is
+* unaffected in both modes — the spec's table still governs.
+*/
+async function runCommand(options) {
+	const { out } = options;
+	const line = (text) => out.stdout.write(`${text}\n`);
+	try {
+		const data = await options.run();
+		if (out.json) out.stdout.write(`${JSON.stringify(data)}\n`);
+		else {
+			options.renderHuman(data, line);
+			const more = continuationLine(data);
+			if (more !== null) line(more);
+		}
+		out.setExitCode(options.exitCodeFor?.(data) ?? 0);
+	} catch (thrown) {
+		if (thrown instanceof ApiCallError) {
+			if (out.json) out.stdout.write(`${JSON.stringify(thrown.envelope)}\n`);
+			else out.stderr.write(`${errorPrefix()} ${thrown.payload.message}\n`);
+			out.setExitCode(exitCodeForErrorCode(thrown.payload.code));
+			return;
+		}
+		const message = thrown instanceof Error ? thrown.message : String(thrown);
+		const exitCode = thrown instanceof CliError ? thrown.exitCode : 1;
+		if (out.json) {
+			const document = { error: {
+				code: cliErrorCodeForExit(exitCode),
+				retriable: false,
+				message
+			} };
+			out.stdout.write(`${JSON.stringify(document)}\n`);
+		} else out.stderr.write(`${errorPrefix()} ${message}\n`);
+		out.setExitCode(exitCode);
+	}
+}
+//#endregion
+//#region src/commands/blocklist.ts
+/**
+* `blocklist list | add | remove` (spec 301 → CLI → Command surface).
+*
+* Argument mapping and rendering over `callAction` — no HTTP, no envelope
+* handling and no exit-code logic of its own.
+*
+* Two decisions this module exists to hold:
+*
+*   - **`list` pages.** `list-blocklist` is cursor-paginated and a long
+*     blocklist IS truncated. The recorded incident behind this spec was an
+*     unpaginated read of a ~10,000-entry list, so `--all` walks to completion
+*     through `walkAllPages` and `--json` emits the whole walk as ONE document.
+*   - **The CLI owns per-type entry construction.** MCP needs an object root,
+*     so one `entries` array serves all three lists and the generated type
+*     leaves its ITEM shape open. The server stays the only validator of what
+*     goes in it.
+*/
+/**
+* TOTAL over the type union the generated document publishes: a fourth list
+* added server-side fails `npm run typecheck` here rather than being reachable
+* by no command at all.
+*/
+const IS_BLOCKLIST_TYPE = {
+	sellers: true,
+	countries: true,
+	items: true
+};
+const BLOCKLIST_TYPES = Object.keys(IS_BLOCKLIST_TYPE).join(" | ");
+function isBlocklistType(value) {
+	return Object.hasOwn(IS_BLOCKLIST_TYPE, value);
+}
+/**
+* `--type` is required on all three subcommands: these are three separate lists
+* with three different row shapes, one call reaches exactly one of them, and the
+* server refuses a body without it.
+*/
+function parseType(raw) {
+	if (raw === void 0) throw new CliError(2, `--type is required (${BLOCKLIST_TYPES}). The three blocklists are separate and one call reaches exactly one of them.`);
+	if (!isBlocklistType(raw)) throw new CliError(2, `--type "${raw}" is not a blocklist. Use one of: ${BLOCKLIST_TYPES}.`);
+	return raw;
+}
+/** The 1–200 range is the server's to enforce; this only refuses a non-number. */
+function parseLimit$2(raw) {
+	if (raw === void 0) return void 0;
+	if (!/^\d+$/.test(raw)) throw new CliError(2, `--limit takes a whole number of entries, not "${raw}".`);
+	return Number(raw);
+}
+function addEntriesFromKeys(type, keys, reason) {
+	switch (type) {
+		case "sellers": return keys.map((sellerName) => ({
+			sellerName,
+			reason
+		}));
+		case "items": return keys.map((ebayItemId) => ({ ebayItemId }));
+		case "countries": throw new CliError(2, "blocklist add --type countries takes --input, not positional arguments: each entry needs countryId, countryCode and countryName, all three, because the columns are NOT NULL and nothing is looked up server-side.");
+	}
+}
+/**
+* A country id, as a NUMBER — that is what `remove` takes for this list, and the
+* only entry shape on either verb that is not a string.
+*/
+function parseCountryId(raw) {
+	if (!/^\d+$/.test(raw)) throw new CliError(2, `"${raw}" is not a country id. blocklist remove --type countries takes the numeric ids that "blocklist list --type countries" prints under ID.`);
+	const id = Number(raw);
+	if (!Number.isSafeInteger(id)) throw new CliError(2, `"${raw}" is too large to send as a JSON number.`);
+	return id;
+}
+/** BARE keys for all three types: strings for sellers and items, numbers for countries. */
+function removeKeysFromArguments(type, keys) {
+	return type === "countries" ? keys.map(parseCountryId) : [...keys];
+}
+/**
+* What the object is expected to carry, for the shared parser's refusal. It is
+* guidance only — `entriesFromInput` below is the check, and `--type` stays on
+* the command line either way.
+*/
+const INPUT_EXPECTS$1 = "The object carries the entries, e.g. {\"entries\":[...]}.";
+function entriesFromInput(input) {
+	const entries = Reflect.get(input, "entries");
+	if (!Array.isArray(entries)) throw new CliError(2, "--input carries no \"entries\" array. The object holds the entries, e.g. {\"entries\":[...]}; --type stays on the command line.");
+	return entries;
+}
+/**
+* `--type` and a `type` inside `--input` are two stated intentions. Honouring
+* one silently would write to a list the command line does not name.
+*/
+function assertInputTypeAgrees(input, type) {
+	const declared = Reflect.get(input, "type");
+	if (declared !== void 0 && declared !== type) throw new CliError(2, `--type ${type} and the "type" inside --input name different blocklists. Send one of them.`);
+}
+/**
+* `--input` and the field arguments of the same command are MUTUALLY EXCLUSIVE.
+* Merging them would make the body actually sent unreadable from the command
+* line, so supplying both is a usage error decided before any HTTP call.
+*/
+async function resolveEntries(args) {
+	if (args.input !== void 0) {
+		if (args.keys.length > 0 || args.hasFieldFlags) throw new CliError(2, "--input and the entry arguments of the same command are mutually exclusive. Send one.");
+		const input = await readInputObject({
+			raw: args.input,
+			readStdin: args.readStdin,
+			expects: INPUT_EXPECTS$1
+		});
+		assertInputTypeAgrees(input, args.type);
+		return {
+			entries: entriesFromInput(input),
+			extra: input
+		};
+	}
+	if (args.keys.length === 0) throw new CliError(2, "Name at least one entry, or pass --input.");
+	return {
+		entries: args.fromKeys(args.type, args.keys),
+		extra: {}
+	};
+}
+function renderList(data, line) {
+	switch (data.type) {
+		case "sellers":
+			renderTable(["SELLER", "REASON"], data.entries.map((entry) => [entry.sellerName, entry.reason ?? ""]), line);
+			return;
+		case "countries":
+			renderTable([
+				"ID",
+				"CODE",
+				"NAME"
+			], data.entries.map((entry) => [
+				String(entry.countryId),
+				entry.countryCode,
+				entry.countryName
+			]), line);
+			return;
+		case "items":
+			renderTable([
+				"ITEM ID",
+				"TITLE",
+				"IMAGE URL"
+			], data.entries.map((entry) => [
+				entry.ebayItemId,
+				entry.title ?? "",
+				entry.imageUrl ?? ""
+			]), line);
+			return;
+	}
+}
+/**
+* The per-entry rows of a write. `already_present` and `not_found` are
+* documented normal successes — the requested state holds — so they are rendered
+* like any other outcome and exit 0. Only the envelope decides otherwise.
+*/
+function renderOutcomes(results, summary, line) {
+	renderTable(["KEY", "OUTCOME"], results.map((result) => [result.key, result.outcome]), line);
+	line(summary);
+}
+/** `--input -`. Read whole, because the body is one JSON document. */
+async function readAllStdin$3() {
+	process.stdin.setEncoding("utf8");
+	let text = "";
+	for await (const chunk of process.stdin) text += String(chunk);
+	return text;
+}
+function resolveDeps$2(overrides) {
+	return {
+		resolveClient: overrides.resolveClient ?? ((baseUrlFlag) => resolveApiClient({ baseUrlFlag })),
+		createOutput: overrides.createOutput ?? processOutput,
+		readStdin: overrides.readStdin ?? readAllStdin$3
+	};
+}
+const TYPE_FLAG_DESCRIPTION = "which blocklist: sellers | countries | items (required)";
+const INPUT_FLAG_DESCRIPTION = "JSON object carrying the entries: a literal, @file, or - for stdin. Mutually exclusive with the entry arguments";
+function buildListCommand(deps) {
+	return new Command("list").description("List blocked sellers, countries or items").option("--type <type>", TYPE_FLAG_DESCRIPTION).option("--limit <count>", "entries per page (1-200, server default 200)").option("--cursor <cursor>", "resume from a previous answer’s nextCursor").option("--all", "walk every page and emit one complete result").action(async (_options, command) => {
+		const options = command.optsWithGlobals();
+		await runCommand({
+			out: deps.createOutput(options.json ?? false),
+			run: async () => {
+				const type = parseType(options.type);
+				const limit = parseLimit$2(options.limit);
+				const all = options.all ?? false;
+				assertPagingFlags({
+					all,
+					cursor: options.cursor
+				});
+				const client = await deps.resolveClient(options.baseUrl ?? null);
+				if (all) return await walkAllPages((cursor) => callAction(client, "list-blocklist", {
+					type,
+					limit,
+					cursor
+				}), "entries");
+				return await callAction(client, "list-blocklist", {
+					type,
+					limit,
+					cursor: options.cursor
+				});
+			},
+			renderHuman: renderList
+		});
+	});
+}
+function buildAddCommand(deps) {
+	return new Command("add").description("Block sellers, countries or items").argument("[keys...]", "seller names, or eBay listing ids. Countries take --input instead").option("--type <type>", TYPE_FLAG_DESCRIPTION).option("--reason <text>", "applies to every seller entry in the call").option("--input <source>", INPUT_FLAG_DESCRIPTION).action(async (keys, _options, command) => {
+		const options = command.optsWithGlobals();
+		await runCommand({
+			out: deps.createOutput(options.json ?? false),
+			run: async () => {
+				const type = parseType(options.type);
+				const reason = options.reason;
+				if (reason !== void 0 && type !== "sellers") throw new CliError(2, "--reason applies only to --type sellers; country and item entries carry no reason field.");
+				const { entries, extra } = await resolveEntries({
+					type,
+					keys,
+					input: options.input,
+					hasFieldFlags: reason !== void 0,
+					readStdin: deps.readStdin,
+					fromKeys: (entryType, entryKeys) => addEntriesFromKeys(entryType, entryKeys, reason)
+				});
+				return await callAction(await deps.resolveClient(options.baseUrl ?? null), "add-blocklist-entries", {
+					...extra,
+					type,
+					entries
+				});
+			},
+			renderHuman: (data, line) => renderOutcomes(data.results, `${data.addedCount} added.`, line)
+		});
+	});
+}
+function buildRemoveCommand(deps) {
+	return new Command("remove").description("Unblock sellers, countries or items").argument("[keys...]", "the stored keys: seller names, country ids, or eBay listing ids").option("--type <type>", TYPE_FLAG_DESCRIPTION).option("--input <source>", INPUT_FLAG_DESCRIPTION).action(async (keys, _options, command) => {
+		const options = command.optsWithGlobals();
+		await runCommand({
+			out: deps.createOutput(options.json ?? false),
+			run: async () => {
+				const type = parseType(options.type);
+				const { entries, extra } = await resolveEntries({
+					type,
+					keys,
+					input: options.input,
+					hasFieldFlags: false,
+					readStdin: deps.readStdin,
+					fromKeys: removeKeysFromArguments
+				});
+				return await callAction(await deps.resolveClient(options.baseUrl ?? null), "remove-blocklist-entries", {
+					...extra,
+					type,
+					entries
+				});
+			},
+			renderHuman: (data, line) => renderOutcomes(data.results, `${data.removedCount} removed.`, line)
+		});
+	});
+}
+/**
+* `scope` is deliberately not a flag: it defaults to `personal` server-side and
+* the CLI supplies nothing, so the server's default is the only one. A team list
+* is reachable on the two write verbs by putting `"scope":"team"` in `--input`.
+*/
+function buildBlocklistCommand(overrides = {}) {
+	const deps = resolveDeps$2(overrides);
+	return new Command("blocklist").description("Manage the blocked sellers, countries and items of the key holder").addCommand(buildListCommand(deps)).addCommand(buildAddCommand(deps)).addCommand(buildRemoveCommand(deps));
+}
+//#endregion
+//#region src/commands/config.ts
+/**
+* The `config` command group — `set-key`, `show`, `clear`
+* (spec 301 → CLI → Auth and configuration).
+*
+* This module is stdin, precedence reporting and rendering ONLY. The config
+* file's path, its parse and the `0700`/`0600` modes belong to `../config.ts`,
+* which is their single owner; a second implementation of a permission-sensitive
+* write is how two of them drift apart.
+*/
+const KEY_SOURCE_LABEL = {
+	env: API_KEY_ENV_VAR,
+	config: "config file",
+	none: "none"
+};
+const SET_KEY_HELP = `
+The key is read from stdin — never from an argument or a flag, because argv
+lands in the shell history and in the process table. There is no --api-key.
+
+  printf %s "$MY_KEY" | ubuyfirst config set-key
+
+The config directory is created 0700 and the file 0600, in the same call that
+creates each. On Windows both modes are advisory: Node maps a POSIX mode onto
+the read-only attribute, which is not an ACL and grants no protection there.`;
+/**
+* Which source wins, WITHOUT resolving the key itself — this module never holds
+* the value it must not print.
+*
+* The order mirrors `resolveApiKey`: env var, then the config file, blank
+* meaning unset in both. It is reported at all because an env var silently
+* overriding a stored key is otherwise invisible: `show` would say a key is set,
+* the user would re-check the file, and the call would still carry the other one.
+*/
+function keySourceOf(env, config) {
+	if ((env["UBUYFIRST_API_KEY"] ?? "").trim() !== "") return "env";
+	return config.apiKey === null ? "none" : "config";
+}
+function viewOf(config, dir, env, baseUrlFlag) {
+	const summary = summarizeConfig(config, configFilePath(dir), resolveBaseUrl({
+		flag: baseUrlFlag,
+		env,
+		config
+	}));
+	return {
+		path: summary.path,
+		keyIsSet: summary.keyIsSet,
+		keySource: keySourceOf(env, config),
+		baseUrl: summary.baseUrl
+	};
+}
+function renderView(view, line) {
+	line(`path: ${view.path}`);
+	line(`key: ${view.keyIsSet ? "set" : "not set"}`);
+	line(`key source: ${KEY_SOURCE_LABEL[view.keySource]}`);
+	line(`base url: ${view.baseUrl}`);
+}
+/**
+* Reads the whole of stdin as the key.
+*
+* The value is trimmed and never echoed — not in the refusal, not in a
+* confirmation. It is deliberately NOT re-validated for control characters
+* here: `auth.ts` owns that rule at the point a key becomes an Authorization
+* header, and a second copy of it in this module is a rule that can drift.
+*/
+async function readKeyFromStdin(stdin, stderr) {
+	if (stdin.isTTY ?? false) stderr.write("Paste the API key, then press Enter followed by Ctrl-D (Ctrl-Z on Windows).\n");
+	const decoder = new TextDecoder();
+	let text = "";
+	for await (const chunk of stdin) text += typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true });
+	text += decoder.decode();
+	const key = text.trim();
+	if (key === "") throw new CliError(2, "No API key on stdin. Pipe one in, for example: printf %s \"$MY_KEY\" | ubuyfirst config set-key");
+	return key;
+}
+function buildConfigCommand(deps = {}) {
+	const makeOutput = deps.output ?? processOutput;
+	const context = (command) => {
+		const globals = command.optsWithGlobals();
+		return {
+			out: makeOutput(globals.json ?? false),
+			dir: deps.configDir ?? defaultConfigDir(),
+			env: deps.env ?? process.env,
+			baseUrlFlag: globals.baseUrl ?? null
+		};
+	};
+	const group = new Command("config").description("Manage the CLI configuration file");
+	const setKey = group.command("set-key");
+	setKey.description("Store the API key, read from stdin").addHelpText("after", SET_KEY_HELP).action(async () => {
+		const { out, dir, env, baseUrlFlag } = context(setKey);
+		await runCommand({
+			out,
+			run: async () => {
+				const existing = await readConfig(dir);
+				const stored = {
+					apiKey: await readKeyFromStdin(deps.stdin ?? process.stdin, out.stderr),
+					baseUrl: existing.baseUrl
+				};
+				await writeConfig(stored, dir);
+				return viewOf(stored, dir, env, baseUrlFlag);
+			},
+			renderHuman: renderView
+		});
+	});
+	const show = group.command("show");
+	show.description("Print the config path, whether a key is stored, and the effective base URL").action(async () => {
+		const { out, dir, env, baseUrlFlag } = context(show);
+		await runCommand({
+			out,
+			run: async () => viewOf(await readConfig(dir), dir, env, baseUrlFlag),
+			renderHuman: renderView
+		});
+	});
+	const clear = group.command("clear");
+	clear.description("Remove the stored API key and base URL").action(async () => {
+		const { out, dir, env, baseUrlFlag } = context(clear);
+		await runCommand({
+			out,
+			run: async () => {
+				const cleared = {
+					apiKey: null,
+					baseUrl: null
+				};
+				await writeConfig(cleared, dir);
+				return viewOf(cleared, dir, env, baseUrlFlag);
+			},
+			renderHuman: renderView
+		});
+	});
+	return group;
+}
+//#endregion
+//#region src/bulk.ts
+/**
+* Bulk export/import mechanism, shared by `searches` and `filters`
+* (spec 301 → Bulk export/import, CLI → Command surface).
+*
+* The two groups run the SAME four steps — walk every page, project a document
+* into a strict body, guard a destructive flag, chunk and aggregate — and differ
+* only in which action they call and what a row is called. AGENTS.md says
+* extract at three copies; writing this twice would be two copies of a
+* destructive-flag guard, which is the last thing that should exist twice.
+*
+* What is shared is the MECHANISM only. The action paths, the row key and the
+* columns stay in the command module that owns them.
+*/
+/**
+* The most rows ONE import call carries.
+*
+* DERIVED, not chosen: the generated OpenAPI document publishes
+* `maxItems: 1000` on `import-saved-searches.searches` AND on
+* `import-item-filters.filters`, which is `SEARCH_IMPORT_ROWS_MAX` /
+* `FILTER_IMPORT_ROWS_MAX` server-side, each pinned there against the row
+* conversion path's own cap (`jsonImportBodySchema`,
+* `filterJsonImportBodySchema`).
+*
+* It is DECLARED here rather than imported because `cli/` is a standalone
+* package with no path alias to the app (spec 301 → CLI → Packaging), and a
+* `maxItems` keyword does not survive into the TypeScript the generator emits —
+* so there is nothing in `cli/` to read it off at compile time. That makes this
+* the one number in the CLI that can silently drift from the server's. It is a
+* MIRROR, and if the two ever disagree the symptom is a `VALIDATION` refusal on
+* the first oversized chunk, not silent data loss.
+*
+* ONE constant for both verbs because the server declares one number for both.
+* Splitting it would invent a difference the API does not have.
+*/
+const BULK_IMPORT_ROWS_MAX = 1e3;
+/**
+* The real terminal check: ALL THREE streams, because any one of them redirected
+* means there is nobody who can be asked. `isTTY` is `boolean | undefined` on a
+* stream Node never opened, and an absent value means NOT a terminal.
+*
+* STDERR IS IN THE SET BECAUSE THAT IS WHERE THE QUESTION IS PRINTED.
+* `confirmOnTerminal` writes the prompt to `process.stderr` and reads the answer
+* from `process.stdin`, so `... --replace-all 2>/dev/null` on a terminal used to
+* pass this check, print an INVISIBLE question and then block on stdin forever.
+*
+* STDOUT STAYS IN THE SET even though nothing is prompted through it. It is not
+* the prompt's stream, it is the last refusal in `assertReplaceAllAllowed`: a
+* piped stdout means the caller is a script, and a destructive default must be
+* refused there rather than prompted. Dropping it would start prompting on
+* `ubuyfirst ... | less`, which loosens the guard this function feeds.
+*/
+function processIsInteractive() {
+	return (process.stdin.isTTY ?? false) && (process.stdout.isTTY ?? false) && (process.stderr.isTTY ?? false);
+}
+/**
+* The real prompt. Anything but an explicit `y`/`yes` is a refusal.
+*
+* Only ever called with stdin UNREAD: `assertReplaceAllAllowed` refuses a
+* destructive call whose body came from stdin before reaching here, because
+* asking a stream already at EOF produces a question that is never answered
+* rather than a refusal.
+*/
+async function confirmOnTerminal(question) {
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stderr
+	});
+	try {
+		const answer = await rl.question(`${question} [y/N] `);
+		return /^y(es)?$/i.test(answer.trim());
+	} finally {
+		rl.close();
+	}
+}
+/** Splits rows into batches of at most `max`, in order, with no row in two batches. */
+function chunkRows(rows, max) {
+	const batches = [];
+	for (let start = 0; start < rows.length; start += max) batches.push(rows.slice(start, start + max));
+	return batches;
+}
+/**
+* Pulls the row array out of an `--input` document and refuses the two shapes
+* that cannot become a request.
+*
+* The document is whatever the user handed in — commonly a page `export` wrote,
+* envelope and all. Only the rows are read; see `projectImportBody` in the
+* command modules for why nothing else may be forwarded.
+*/
+function readRows(document, rowsKey, what) {
+	const rows = document[rowsKey];
+	if (!Array.isArray(rows)) throw new CliError(2, `--input must carry a "${rowsKey}" array. An export document written by "${what} export" already does.`);
+	if (rows.length === 0) throw new CliError(2, `There are no ${what} to import — "${rowsKey}" is empty.`);
+	return rows;
+}
+/**
+* How many rows an `--input` document admits are MISSING from it.
+*
+* An export page carries `skipped[]` — the rows it could not serialize. The document is
+* untrusted, so anything that is not an array counts as ZERO: a missing or malformed
+* `skipped` must not be read as a claim that rows are absent.
+*/
+function documentSkippedCount(document) {
+	const skipped = document["skipped"];
+	return Array.isArray(skipped) ? skipped.length : 0;
+}
+/**
+* The whole guard on the one flag that DELETES DATA.
+*
+* Six refusals, in the order that makes each reachable:
+*
+*   1. `--replace-all` over the per-call cap is refused OUTRIGHT, before any
+*      acknowledgement can excuse it. Chunking is incompatible with it: the
+*      second chunk deletes the first chunk's work, the action cannot detect
+*      that because it holds no session across calls, and the CLI is the only
+*      place the whole file is visible (spec 301, acceptance 13).
+*   2. A document that REPORTS ITS OWN SHORTFALL is refused OUTRIGHT too. An
+*      export writes `skipped[]` for the rows it could not carry, so restoring
+*      such a file with `--replace-all` deletes rows the file itself names and
+*      then cannot put them back. `--yes` acknowledges the deletion the caller
+*      ASKED for; it cannot acknowledge one nobody has been told about, so this
+*      sits above it.
+*   3. `--yes` is the acknowledgement, and it works in every mode.
+*   4. `--json` means a machine is reading. Prompting would corrupt the single
+*      document the mode promises, so an unacknowledged destructive call is
+*      refused rather than run.
+*   5. A body read from STDIN has already spent the stream a prompt would read
+*      the answer from. `ubuyfirst searches import - --replace-all` typed at a
+*      terminal is still `isTTY` on both streams, so the terminal check alone
+*      says "ask" — and the question is then put to a stream at EOF, which
+*      answers nothing and leaves the process waiting instead of refusing.
+*   6. A non-terminal is the same situation without the flag: nobody can answer,
+*      so proceeding would let a destructive default fire because stdout
+*      happened to be piped.
+*
+* Only then is there a prompt, and declining it is the same refusal as never
+* acknowledging — exit 2, decided locally, no HTTP call. Exit 2 rather than 0
+* because "you did not confirm" and "you refused to confirm" are one outcome:
+* the CLI was asked to do something it did not do.
+*/
+async function assertReplaceAllAllowed(request) {
+	if (!request.replaceAll) return;
+	if (request.chunkCount > 1) throw new CliError(2, `--replace-all cannot be used with more than ${String(BULK_IMPORT_ROWS_MAX)} rows: the file is sent in ${String(request.chunkCount)} chunks and each one would delete the previous chunk's work. Import without --replace-all, or split the file yourself.`);
+	if (request.documentSkippedCount > 0) throw new CliError(2, `--replace-all cannot restore this document: it reports that ${String(request.documentSkippedCount)} of your ${request.entity} could NOT be exported and are missing from it. Restoring it would delete them permanently. Import without --replace-all, or export again once those rows are exportable.`);
+	const cost = `--replace-all DELETES every one of your existing ${request.entity} before importing this file.`;
+	if (request.yes) return;
+	if (request.json || request.bodyFromStdin || !request.deps.isInteractive()) throw new CliError(2, `${cost} Re-run with --yes to confirm it.`);
+	if (!await request.deps.confirm(cost)) throw new CliError(2, `Aborted. Nothing was deleted and nothing was imported.`);
+}
+/** Sums two nullable counts, staying null only when NEITHER side reported one. */
+function addNullable(left, right) {
+	if (left === null) return right;
+	if (right === null) return left;
+	return left + right;
+}
+function chunkFrames(rowsPerChunk) {
+	const frames = [];
+	let offset = 0;
+	for (const size of rowsPerChunk) {
+		frames.push({
+			offset,
+			firstRow: offset + 1,
+			lastRow: offset + size
+		});
+		offset += size;
+	}
+	return frames;
+}
+/**
+* Shifts one row number from its CHUNK's frame into the FILE's.
+*
+* `row: 0` is left alone. The import services use it as the BATCH-level
+* sentinel — "Import would create 40 new folders, exceeding the limit" is about
+* the request, not about a line — while per-row numbers are 1-based. Shifting
+* the sentinel turns a whole-file complaint into a pointer at row 1000, which is
+* a real row, and one belonging to the PREVIOUS chunk.
+*/
+function offsetRow(row, offset) {
+	return row === 0 ? 0 : row + offset;
+}
+/**
+* Merges one chunk's diagnostics into the running total, moving every row number
+* into the file's frame.
+*
+* The server numbers rows within the BATCH it received, so chunk 2's "row 3" is
+* the file's row 1003. Concatenating the arrays without the offset produces a
+* report whose row numbers all point into the first thousand lines — the caller
+* then looks at the wrong row, or at a row that is fine.
+*
+* WARNINGS are prose, and they carry their own row number inside the sentence
+* ("Row 1: Unknown custom field ..."). Rewriting a number out of prose is
+* guesswork, so the frame is stated AROUND the sentence instead and only when
+* there is more than one frame to tell apart — a single-chunk import returns the
+* server's warnings byte-identical.
+*
+* The arrays are NOT re-capped. Each response is already truncated to the
+* server's own diagnostic cap while its `*Count` reports the true total, and
+* that relationship is preserved: counts sum to the truth, arrays hold what
+* arrived.
+*/
+function mergeDiagnostics(total, chunk, frame, labelFrame) {
+	for (const row of chunk.skipped) total.skipped.push({
+		...row,
+		row: offsetRow(row.row, frame.offset)
+	});
+	for (const row of chunk.errors) total.errors.push({
+		...row,
+		row: offsetRow(row.row, frame.offset)
+	});
+	for (const warning of chunk.warnings) total.warnings.push(labelFrame ? `rows ${String(frame.firstRow)}-${String(frame.lastRow)}: ${warning}` : warning);
+	total.skippedCount += chunk.skippedCount;
+	total.errorCount += chunk.errorCount;
+	total.warningCount += chunk.warningCount;
+}
+function emptyDiagnostics() {
+	return {
+		skipped: [],
+		skippedCount: 0,
+		errors: [],
+		errorCount: 0,
+		warnings: [],
+		warningCount: 0
+	};
+}
+/**
+* Folds every chunk's answer into ONE document OF THE SERVER'S OWN SHAPE.
+*
+* Deliberately not a new "chunk report" type. For a single chunk the fold is the
+* identity, so the overwhelmingly common case still emits the server's body
+* verbatim and a consumer parses one shape whether the file was chunked or not.
+* Inventing a wrapper would make every caller branch on a detail the CLI chose.
+*
+* A chunk answering a DIFFERENT mode than the first is a server inconsistency —
+* `preview` is one flag sent identically on every chunk — and it is exit 1
+* rather than a silent pick.
+*/
+function foldResults(results, frames) {
+	const first = results[0];
+	if (first === void 0) throw new Error("unreachable: no chunk ran");
+	const labelFrame = results.length > 1;
+	const diagnostics = emptyDiagnostics();
+	results.forEach((result, index) => {
+		const frame = frames[index];
+		if (frame === void 0) throw new Error("unreachable: a chunk answered with no frame");
+		if (result.mode !== first.mode) throw new CliError(1, `Chunk ${String(index + 1)} answered "${result.mode}" where chunk 1 answered "${first.mode}". The server changed mode mid-import.`);
+		mergeDiagnostics(diagnostics, result, frame, labelFrame);
+	});
+	if (first.mode === "preview") {
+		const previews = results;
+		if (previews.length > 1) {
+			diagnostics.warnings.unshift(`This preview validated ${String(previews.length)} chunks INDEPENDENTLY, each against the same unchanged account. Conflicts that SPAN chunks — one row key (an alias, a filter name) appearing in two different chunks, or any whole-file total — are NOT detected here, so a valid preview does not prove the whole file imports.`);
+			diagnostics.warningCount += 1;
+		}
+		return {
+			mode: "preview",
+			valid: previews.every((result) => result.valid),
+			toCreate: previews.reduce((sum, result) => sum + result.toCreate, 0),
+			toUpdate: previews.reduce((sum, result) => sum + result.toUpdate, 0),
+			existingCount: first.existingCount,
+			...diagnostics
+		};
+	}
+	const executed = results;
+	const messages = executed.map((result) => result.message).filter((message) => message !== null);
+	return {
+		mode: "executed",
+		success: executed.every((result) => result.success),
+		created: executed.reduce((sum, result) => sum + result.created, 0),
+		updated: executed.reduce((sum, result) => sum + result.updated, 0),
+		foldersCreated: executed.reduce((sum, result) => addNullable(sum, result.foldersCreated), null),
+		message: messages.length === 0 ? null : messages.join("; "),
+		...diagnostics
+	};
+}
+/**
+* Runs the chunks in order and tells the truth about where it stopped.
+*
+* THERE IS NO TRANSACTION ACROSS CHUNKS. Chunk 1 is committed the moment it
+* answers 200, so a failure on chunk 3 of 7 leaves the account with the first
+* two chunks applied. The two outcomes are therefore genuinely different and are
+* reported differently:
+*
+*   - NOTHING succeeded yet → the failure is rethrown UNCHANGED, so `--json`
+*     emits the server's own envelope verbatim and the exit code is the one its
+*     `code` maps to. There is no partial state to describe, and flattening a
+*     `CAP_EXCEEDED` into a generic partial would cost a script the one field it
+*     branches on.
+*   - SOMETHING succeeded → the answer is a partial import, which the server's
+*     own shape can already say: `success: false` with a `message` naming the
+*     chunk that failed and the reason it gave. Echoing only the error envelope
+*     there would tell the caller nothing was written, which is false.
+*
+* A PREVIEW is exempt from the second case: it writes nothing, so a failed
+* preview chunk leaves no partial state and the failure passes straight through.
+*/
+async function runChunkedImport(request) {
+	const batches = chunkRows(request.rows, BULK_IMPORT_ROWS_MAX);
+	const frames = chunkFrames(batches.map((batch) => batch.length));
+	const results = [];
+	for (const [index, batch] of batches.entries()) try {
+		results.push(await request.sendChunk(batch));
+	} catch (thrown) {
+		if (results.filter((result) => result.mode === "executed").length === 0) throw thrown;
+		const reason = thrown instanceof Error ? thrown.message : String(thrown);
+		const folded = foldResults(results, frames);
+		if (folded.mode !== "executed") throw thrown;
+		const unattempted = batches.length - (index + 1);
+		return {
+			...folded,
+			success: false,
+			message: `Chunk ${String(index + 1)} of ${String(batches.length)} failed: ${reason}. Earlier chunks left ${String(folded.created)} created and ${String(folded.updated)} updated in place — there is no rollback. Whether chunk ${String(index + 1)} itself wrote anything is unknown.${unattempted === 0 ? "" : ` The remaining ${String(unattempted)} chunk(s) were never sent.`}`
+		};
+	}
+	return foldResults(results, frames);
+}
+/**
+* The success exit code for an import.
+*
+* Exit 11 is "a 200 whose body reports work that did not happen" (spec 301 →
+* Exit codes), and an import that could not apply a row is exactly that: a
+* restore script reading exit 0 would report a backup fully applied when rows
+* were rejected.
+*
+* `skippedCount` ALONE does not reach 11. A skipped row is the import path's
+* documented normal outcome for a row that needed no change, the same reading
+* the spec gives the blocklist's `already_present` / `not_found` — the requested
+* state holds. It is still printed prominently; it just is not a failure.
+*/
+function exitCodeForImport(result) {
+	if (result.errorCount > 0) return 11;
+	if (result.mode === "preview") return result.valid ? 0 : 11;
+	return result.success ? 0 : 11;
+}
+/**
+* The import's human answer, with the diagnostics ABOVE the summary.
+*
+* Order is the point. A caller who reads the first line and stops must see that
+* something was rejected, so the counts that mean "incomplete" print first and
+* the totals print last.
+*/
+function renderImportResult(result, line) {
+	if (result.errorCount > 0) {
+		line(`${String(result.errorCount)} row(s) were REJECTED and did not import:`);
+		for (const row of result.errors) line(`  row ${String(row.row)}  ${row.field}: ${row.reason}`);
+		if (result.errors.length < result.errorCount) line(`  ... and ${String(result.errorCount - result.errors.length)} more not listed.`);
+	}
+	if (result.skippedCount > 0) {
+		line(`${String(result.skippedCount)} row(s) were skipped:`);
+		for (const row of result.skipped) line(`  row ${String(row.row)}  ${row.reason}`);
+		if (result.skipped.length < result.skippedCount) line(`  ... and ${String(result.skippedCount - result.skipped.length)} more not listed.`);
+	}
+	if (result.warningCount > 0) {
+		for (const warning of result.warnings) line(`warning: ${warning}`);
+		if (result.warnings.length < result.warningCount) line(`warning: ... and ${String(result.warningCount - result.warnings.length)} more.`);
+	}
+	if (result.mode === "preview") {
+		line(`Preview: ${String(result.toCreate)} to create, ${String(result.toUpdate)} to update, ${String(result.existingCount)} already in the account. Nothing was written.`);
+		if (!result.valid) line("This file cannot be imported as it stands.");
+		return;
+	}
+	line(`Imported: ${String(result.created)} created, ${String(result.updated)} updated${result.foldersCreated === null ? "" : `, ${String(result.foldersCreated)} folder(s) created`}.`);
+	if (result.message !== null) line(result.message);
+	if (!result.success) line("The import did NOT complete successfully.");
+}
+/**
+* The export's own admission that the document is short.
+*
+* Printed as a WARNING BLOCK before anything else, never as a trailing note: the
+* caller of an export is writing a backup, and a row missing from it is not
+* discovered until a restore that silently comes back incomplete. This is the
+* one caller that would otherwise ignore `skipped[]`.
+*/
+function renderExportSkipped(skipped, entity, line) {
+	if (skipped.length === 0) return;
+	line(`WARNING: ${String(skipped.length)} ${entity} could NOT be exported and are MISSING from this document:`);
+	for (const row of skipped) line(`  ${row.publicId ?? "(no id)"}  ${row.name}  — too ${row.reason === "depth" ? "deeply nested" : "large"}`);
+	line("This backup will NOT restore them. Simplify them and export again.");
+}
+/**
+* Exit 11 when the export left rows behind.
+*
+* A partial backup that exits 0 is the failure mode that matters here: every
+* wrapper script treats 0 as "the backup is good", and the omission surfaces at
+* restore time instead. Exit 11 is the spec's own "a 200 whose body reports work
+* that did not happen" and needs no new code — the spec's note that ONE action
+* produces it dates from before these verbs had a CLI command.
+*/
+function exitCodeForExport(skipped) {
+	return skipped.length > 0 ? 11 : 0;
+}
+//#endregion
+//#region src/commands/filters.ts
+/**
+* The `filters` command group (spec 301 → Bulk export/import).
+*
+* Export and import ONLY. Item filters are not a first-class concept in wave 1:
+* the API has no `list_item_filters`, no CRUD and no filter-folder action, so
+* there is nothing else for this group to expose and a third subcommand here
+* would be a command with no endpoint behind it.
+*
+* WHY THE GROUP EXISTS AT ALL, since spec 301's command surface says the two
+* filter verbs ship with no wave-1 CLI command: a saved-search row references
+* its filter folders by PATH, so restoring an account imports item filters
+* FIRST — and a CLI that could export and import searches but not filters cannot
+* perform the restore its own export document implies. That is a scope decision
+* above this module; the contradiction with the spec's "20 commands over 21
+* actions" is reported rather than resolved here.
+*
+* Argument mapping and rendering ONLY, like every other group — the transport,
+* the exit discipline, the page walk and the bulk mechanism all live in the
+* shared core.
+*/
+async function readAllStdin$2() {
+	const chunks = [];
+	process.stdin.setEncoding("utf8");
+	for await (const chunk of process.stdin) chunks.push(String(chunk));
+	return chunks.join("");
+}
+function resolveDeps$1(deps) {
+	return {
+		resolveClient: deps.resolveClient ?? resolveApiClient,
+		createOutput: deps.createOutput ?? processOutput,
+		readStdin: deps.readStdin ?? readAllStdin$2,
+		isInteractive: deps.isInteractive ?? processIsInteractive,
+		confirm: deps.confirm ?? confirmOnTerminal
+	};
+}
+/**
+* `export` IMPLIES `--all`, on the same reasoning as `searches export`: a
+* partial export is a corrupt backup, so neither `--limit` nor `--cursor` is
+* offered.
+*
+* BOTH per-page arrays are named in the walk. `filters` carries the rows;
+* `skipped` carries the rows the export could NOT carry — too large or too
+* deeply nested for the response scanner — and it accumulates page by page
+* exactly as the rows do. Walking only `filters` would keep the last page's
+* `skipped` and silently discard every earlier one, which is the same truncation
+* the field exists to report.
+*/
+function exportCommand$1(deps) {
+	return new Command("export").description("Write every item filter as a backup document — always walks every page").action(async function runExport() {
+		const options = this.optsWithGlobals();
+		await runCommand({
+			out: deps.createOutput(options.json ?? false),
+			run: async () => {
+				const client = await deps.resolveClient({ baseUrlFlag: options.baseUrl ?? null });
+				return walkAllPages((cursor) => callAction(client, "export-item-filters", { cursor: cursor ?? void 0 }), ["filters", "skipped"]);
+			},
+			renderHuman: (data, line) => {
+				renderExportSkipped(data.skipped, "item filter(s)", line);
+				line(`Exported ${String(data.filters.length)} item filter(s).`);
+				renderTable([
+					"ID",
+					"NAME",
+					"FOLDER",
+					"ACTION"
+				], data.filters.map((row) => [
+					row.Id ?? "",
+					row.Name,
+					row["Folder Path"] ?? "",
+					row.Action
+				]), line);
+			},
+			exitCodeFor: (data) => exitCodeForExport(data.skipped)
+		});
+	});
+}
+/**
+* The one seam where a document the CLI did not type-check becomes a typed
+* request — narrow and named, because spec 301 makes the server the only schema
+* validator and `--input` is by definition a document this build has not
+* inspected.
+*/
+function asImportRows$1(rows) {
+	return rows;
+}
+/**
+* The BODY, assembled field by field — never spread from the caller's document.
+*
+* Same write-retargeting rule as `searches import`, and the same worst case: a
+* `"replaceAll": true` in the file would DELETE every item filter on an import
+* the command line never flagged as destructive.
+*
+* There is deliberately NO `customFieldDefinitions` here. That field belongs to
+* the saved-search import; this body is `.strict()`, so copying it across would
+* refuse the whole call rather than be ignored — as would `skipped`, which an
+* export page carries.
+*
+* OMITTING `skipped` FROM THE BODY IS NOT DISMISSING IT. It has no meaning to
+* the write — it names rows the file does NOT hold — but it is the document's
+* own admission that it is incomplete, and that is a decision the CALLER's
+* flags turn on: `assertReplaceAllAllowed` reads it through
+* `documentSkippedCount` and refuses `--replace-all` over a short document,
+* which would delete the very rows the field names. Not sent, and not ignored.
+*/
+function importBody$1(rows, options) {
+	return {
+		filters: asImportRows$1(rows),
+		preview: options.preview ?? false,
+		replaceAll: options.replaceAll ?? false,
+		targetFolderId: options.targetFolder ?? null
+	};
+}
+/** `-` stays stdin; anything else is a path, which `--input` spells `@path`. */
+function fileSource$1(file) {
+	return file === "-" ? "-" : `@${file}`;
+}
+function importCommand$1(deps) {
+	return new Command("import").description("Restore item filters from a backup document").argument("[file]", "Path to the export document, or \"-\" for stdin").option("--input <json|@file|->", "The document as JSON, instead of the positional").option("--preview", "Validate and report without writing anything").option("--replace-all", "DELETE every existing item filter first — destructive").option("--target-folder <id>", "File every imported filter into this folder").option("--yes", "Acknowledge --replace-all without an interactive prompt").action(async function runImport(file) {
+		const options = this.optsWithGlobals();
+		const json = options.json ?? false;
+		await runCommand({
+			out: deps.createOutput(json),
+			run: async () => {
+				if (file !== void 0 && options.input !== void 0) throw new CliError(2, "Use the file argument or --input, not both. They are two ways to supply one body.");
+				const raw = options.input ?? (file === void 0 ? void 0 : fileSource$1(file));
+				if (raw === void 0) throw new CliError(2, "filters import needs a file argument, or --input carrying the export document.");
+				const document = await readInputObject({
+					raw,
+					readStdin: deps.readStdin,
+					expects: "It should carry the \"filters\" array an export document holds."
+				});
+				const rows = readRows(document, "filters", "item filters");
+				await assertReplaceAllAllowed({
+					replaceAll: options.replaceAll ?? false,
+					yes: options.yes ?? false,
+					json,
+					bodyFromStdin: raw === "-",
+					chunkCount: chunkRows(rows, BULK_IMPORT_ROWS_MAX).length,
+					documentSkippedCount: documentSkippedCount(document),
+					entity: "item filters",
+					deps
+				});
+				const client = await deps.resolveClient({ baseUrlFlag: options.baseUrl ?? null });
+				return runChunkedImport({
+					rows,
+					sendChunk: (batch) => callAction(client, "import-item-filters", importBody$1(batch, options))
+				});
+			},
+			renderHuman: renderImportResult,
+			exitCodeFor: exitCodeForImport
+		});
+	});
+}
+function buildFiltersCommand(deps = {}) {
+	const resolved = resolveDeps$1(deps);
+	return new Command("filters").description("Export and import item filters").addCommand(exportCommand$1(resolved)).addCommand(importCommand$1(resolved));
+}
+//#endregion
+//#region src/commands/folders.ts
+/**
+* The `folders` command group (spec 301 → CLI → Command surface).
+*
+* `list`, `create`, `rename`, `delete`, `move` over `list-folders`,
+* `create-folder`, `update-folder`, `delete-folder` and `move-search-to-folder`.
+*
+* Argument mapping and rendering ONLY. The transport, the envelope, the exit
+* codes, the two output modes and the `--all` walk all live in the shared core,
+* so nothing here re-implements them.
+*
+* Global options are read with `optsWithGlobals()`. Commander's `.opts()`
+* returns LOCAL options only, so a subcommand reading `--json` through it gets
+* `undefined` and silently writes human text into a pipe with a zero exit code.
+* `__tests__/global-options.test.ts` refuses a `.opts()` call in this file; it
+* strips comments before scanning, so naming the accessor here is free.
+*/
+const FOLDER_COLUMNS = [
+	"ID",
+	"NAME",
+	"PARENT",
+	"SORT"
+];
+/** What a null id renders as: no parent (top level), or no folder (unfiled). */
+const NONE = "-";
+const INPUT_DESCRIPTION = "Send this JSON object as the whole request body: a literal, @file, or - for stdin";
+function usage(message) {
+	return new CliError(2, message);
+}
+function folderRow(folder) {
+	return [
+		folder.id,
+		folder.name,
+		folder.parentId ?? NONE,
+		String(folder.sortOrder)
+	];
+}
+function requiredArgument(value, what) {
+	if (value === void 0) throw usage(`${what} is required. Pass it, or pass --input with the whole request body.`);
+	return value;
+}
+/**
+* Rejects a `--limit` that is not a whole number and stops there. The RANGE is
+* the server's (1–200): it is the only schema validator, and duplicating its
+* bounds here would go stale the day they move.
+*/
+function parseLimit$1(raw) {
+	if (raw === void 0) return void 0;
+	if (!/^\d+$/.test(raw)) throw usage(`--limit must be a whole number, not "${raw}".`);
+	return Number(raw);
+}
+/**
+* `--input` IS the request body, so it never merges with the command's own
+* arguments (spec 301 → CLI → Argument rules). Supplying both is a usage error
+* rather than a merge, because a merged body cannot be read back off the command
+* line — the caller would be guessing which half won.
+*
+* Positional arguments are checked alongside the flags, which is why every
+* argument in this group is declared optional: `--input` and the arguments are
+* alternative ways to say the same thing, and the requirement is enforced here
+* so a missing one is exit 2 with a message rather than commander's own error.
+*/
+function assertInputAlone(input, named) {
+	if (input === void 0) return;
+	const supplied = Object.keys(named).filter((name) => named[name] !== void 0);
+	if (supplied.length === 0) return;
+	throw usage(`--input carries the whole request body, so it cannot be combined with ${supplied.join(" or ")}. Use one or the other.`);
+}
+/**
+* `--input` IS the whole request body for this group — unlike `searches update`,
+* which wraps it, and `notifications settings`, which spreads it under a
+* positional id. `assertInputAlone` above is what keeps that unambiguous: the
+* flag and the command's own arguments are never merged, so there is nothing for
+* a body to silently override.
+*/
+function inputBody(raw, readStdin) {
+	return readInputObject({
+		raw,
+		readStdin
+	});
+}
+async function createBody(name, options, readStdin) {
+	assertInputAlone(options.input, {
+		"a name argument": name,
+		"--parent": options.parent
+	});
+	if (options.input !== void 0) return inputBody(options.input, readStdin);
+	return {
+		name: requiredArgument(name, "A folder name"),
+		parentId: options.parent ?? null
+	};
+}
+async function renameBody(id, name, options, readStdin) {
+	assertInputAlone(options.input, {
+		"an id argument": id,
+		"a name argument": name
+	});
+	if (options.input !== void 0) return inputBody(options.input, readStdin);
+	return {
+		id: requiredArgument(id, "A folder id"),
+		name: requiredArgument(name, "A new folder name")
+	};
+}
+/**
+* `--to <id>` XOR `--unfile`, exactly one, decided locally before any HTTP call
+* (acceptance 8).
+*
+* `targetFolderId` is nullable with NO default, so there is no body the CLI can
+* send for "neither flag" that is not a guess about which the caller meant —
+* and `--unfile` sends an explicit `null` rather than omitting the field.
+*/
+async function moveBody(searchId, options, readStdin) {
+	assertInputAlone(options.input, {
+		"a searchId argument": searchId,
+		"--to": options.to,
+		"--unfile": options.unfile
+	});
+	if (options.input !== void 0) return inputBody(options.input, readStdin);
+	const unfile = options.unfile ?? false;
+	if (options.to !== void 0 && unfile) throw usage("Use --to <id> or --unfile, not both. A search is filed under one folder, or none.");
+	if (options.to === void 0 && !unfile) throw usage("A move needs --to <id> or --unfile. There is no default target folder, so the CLI will not choose one for you.");
+	return {
+		searchId: requiredArgument(searchId, "A saved-search id"),
+		targetFolderId: options.to ?? null
+	};
+}
+function buildFoldersCommand(deps = {}) {
+	const output = deps.output ?? processOutput;
+	const readStdin = deps.readStdin ?? (() => text(process.stdin));
+	const client = (globals) => resolveApiClient({
+		baseUrlFlag: globals.baseUrl ?? null,
+		env: deps.env,
+		fetch: deps.fetch,
+		configDir: deps.configDir
+	});
+	const folders = new Command("folders").description("Manage saved-search folders");
+	folders.command("list").description("List folders. A PARENT of - means the folder is top level.").option("--limit <n>", "Folders per page (the server allows 1-200 and defaults to 200)").option("--cursor <cursor>", "Resume from a previous answer's nextCursor").option("--all", "Walk every page and emit one combined result").action(async (_options, command) => {
+		const options = command.optsWithGlobals();
+		await runCommand({
+			out: output(options.json ?? false),
+			run: async () => {
+				const all = options.all ?? false;
+				assertPagingFlags({
+					all,
+					cursor: options.cursor
+				});
+				const limit = parseLimit$1(options.limit);
+				const api = await client(options);
+				if (all) return walkAllPages((cursor) => callAction(api, "list-folders", {
+					limit,
+					cursor: cursor ?? void 0
+				}), "folders");
+				return callAction(api, "list-folders", {
+					limit,
+					cursor: options.cursor
+				});
+			},
+			renderHuman: (data, line) => renderTable(FOLDER_COLUMNS, data.folders.map(folderRow), line)
+		});
+	});
+	folders.command("create").description("Create a folder").argument("[name]", "Folder name. Omit it only when passing --input.").option("--parent <id>", "Nest inside this folder id (default: top level)").option("--input <json|@file|->", INPUT_DESCRIPTION).action(async (name, _options, command) => {
+		const options = command.optsWithGlobals();
+		await runCommand({
+			out: output(options.json ?? false),
+			run: async () => {
+				const body = await createBody(name, options, readStdin);
+				return callAction(await client(options), "create-folder", body);
+			},
+			renderHuman: (data, line) => renderTable(FOLDER_COLUMNS, [folderRow(data.folder)], line)
+		});
+	});
+	folders.command("rename").description("Rename a folder. Rename only — re-parenting and reordering are not exposed.").argument("[id]", "Folder id, from folders list. Omit it only when passing --input.").argument("[name]", "The new name").option("--input <json|@file|->", INPUT_DESCRIPTION).action(async (id, name, _options, command) => {
+		const options = command.optsWithGlobals();
+		await runCommand({
+			out: output(options.json ?? false),
+			run: async () => {
+				const body = await renameBody(id, name, options, readStdin);
+				return callAction(await client(options), "update-folder", body);
+			},
+			renderHuman: (data, line) => renderTable(["ID", "NAME"], [[data.id, data.name]], line)
+		});
+	});
+	folders.command("delete").description("Delete a folder. The saved searches inside it survive, unfiled, and child folders are flattened to the top level.").argument("<id>", "Folder id, from folders list").action(async (id, _options, command) => {
+		const options = command.optsWithGlobals();
+		await runCommand({
+			out: output(options.json ?? false),
+			run: async () => callAction(await client(options), "delete-folder", { id }),
+			renderHuman: (data, line) => renderTable(["ID"], [[data.id]], line)
+		});
+	});
+	folders.command("move").description("File a saved search under a folder, or under none").argument("[searchId]", "Saved-search id, from searches list. Omit it only with --input.").option("--to <id>", "Target folder id, from folders list").option("--unfile", "File the search under no folder — sends an explicit null").option("--input <json|@file|->", INPUT_DESCRIPTION).action(async (searchId, _options, command) => {
+		const options = command.optsWithGlobals();
+		await runCommand({
+			out: output(options.json ?? false),
+			run: async () => {
+				const body = await moveBody(searchId, options, readStdin);
+				return callAction(await client(options), "move-search-to-folder", body);
+			},
+			renderHuman: (data, line) => renderTable(["SEARCH", "FOLDER"], [[data.id, data.folderId ?? NONE]], line)
+		});
+	});
+	return folders;
+}
+//#endregion
+//#region src/commands/notifications.ts
+/**
+* The `notifications` command group (spec 301 → CLI → Command surface, wave 1).
+*
+* Three subcommands over FOUR actions: `settings` reads by default and writes
+* when `--input` is present, so `--input` IS the read/write switch. There is no
+* fourth subcommand — notification CREDENTIAL management is a stated non-goal,
+* and no endpoint exposes it.
+*
+* Like every command module this is argument mapping and rendering only. The
+* transport, the error envelope, the exit-code table and the `--all` walk all
+* live in the shared core; nothing here re-implements any of them.
+*/
+/** 0=Sunday through 6=Saturday, as the endpoint documents `activeDays`. */
+const DAY_NAMES = [
+	"Sun",
+	"Mon",
+	"Tue",
+	"Wed",
+	"Thu",
+	"Fri",
+	"Sat"
+];
+/**
+* NULL IS NOT "OFF". `schedule`, `interval` and `template` are null exactly when
+* the channel has never been CONFIRMED — the three rows are created together on
+* first confirmation — so null means "not configured yet", never "unrestricted"
+* or "unlimited". Rendering it as "off" or "none" inverts the meaning.
+*/
+const NOT_CONFIGURED = "not configured (this channel has never been confirmed)";
+const CHANNEL_COLUMNS = [
+	"ID",
+	"TYPE",
+	"STATUS",
+	"ENABLED",
+	"CONFIRMED",
+	"FAILURES",
+	"LAST SENT"
+];
+function yesNo(value) {
+	return value ? "yes" : "no";
+}
+/**
+* `isEnabled` and `status` are INDEPENDENT and both are shown: the first is the
+* account holder's own switch, the second is delivery health they do not set, so
+* an enabled channel can still be failing. `confirmedAt` is shown for the same
+* reason — an unconfirmed channel delivers nothing whatever `isEnabled` says.
+* Everything else the row carries is one `--json` away.
+*/
+function channelRow(channel) {
+	return [
+		channel.id,
+		channel.platformType,
+		channel.status,
+		yesNo(channel.isEnabled),
+		channel.confirmedAt ?? "never",
+		String(channel.consecutiveFailures),
+		channel.lastSentAt ?? "never"
+	];
+}
+/**
+* Refuses a `--limit` that is not a whole number, locally.
+*
+* The API's own 1–200 range is deliberately NOT re-declared here — the server is
+* the validator of it. What this catches is different: `Number('twenty')` is
+* `NaN`, `JSON.stringify({ limit: NaN })` is `{"limit":null}`, and the user then
+* reads a VALIDATION message about a null they never typed.
+*/
+function parseLimit(raw) {
+	if (raw === void 0) return void 0;
+	if (!/^\d+$/.test(raw)) throw new CliError(2, `--limit must be a whole number, not "${raw}".`);
+	return Number(raw);
+}
+/**
+* `--on` XOR `--off`. `enabled` is REQUIRED with no default and it is a SET, not
+* a flip, so the CLI cannot pick one: neither flag and both flags are the same
+* failure — the caller has not said which state they want.
+*/
+function requiredSwitch(options) {
+	const on = options.on ?? false;
+	if (on === (options.off ?? false)) throw new CliError(2, "Use --on or --off, exactly one. \"enabled\" is a SET, not a flip, and the API declares no default.");
+	return on;
+}
+/** Whole-stream read, so `--input -` works on Windows too (no `/dev/stdin`). */
+function readAllStdin$1() {
+	return text(process.stdin);
+}
+/**
+* What the object is expected to carry, for the shared parser's refusal. Spec
+* 301 puts the whole schema with the server, so this is guidance and never a
+* check — nothing here enumerates the fields.
+*/
+const INPUT_EXPECTS = "The object carries the aspects to write; the server validates their contents.";
+function describeSchedule(schedule) {
+	if (schedule === null) return NOT_CONFIGURED;
+	if (schedule.scheduleType === "ALWAYS") return "ALWAYS";
+	const days = schedule.activeDays.map((day) => DAY_NAMES[day] ?? String(day));
+	const window = `${schedule.startTime ?? "unset"}-${schedule.endTime ?? "unset"}`;
+	return `CUSTOM  ${days.length === 0 ? "no days" : days.join(",")}  ${window}`;
+}
+function describeInterval(interval) {
+	if (interval === null) return NOT_CONFIGURED;
+	return `${interval.interval}  last batch ${interval.lastBatchAt ?? "never"}`;
+}
+function describeTemplate(template) {
+	if (template === null) return NOT_CONFIGURED;
+	const images = template.includeImages ? "with images" : "without images";
+	return `${template.selectedFields.length} fields, ${images}`;
+}
+function renderSettings(settings, line) {
+	renderTable(["FIELD", "VALUE"], [
+		["ID", settings.id],
+		["SCHEDULE", describeSchedule(settings.schedule)],
+		["INTERVAL", describeInterval(settings.interval)],
+		["TEMPLATE", `${describeTemplate(settings.template)}  (read-only)`]
+	], line);
+	line("");
+	if (settings.filterRules.length === 0) {
+		line("Filter rules: none attached.");
+		return;
+	}
+	renderTable([
+		"FILTER ID",
+		"ACTION",
+		"NAME"
+	], settings.filterRules.map((rule) => [
+		rule.filterId,
+		rule.action,
+		rule.filterName ?? "(unnamed)"
+	]), line);
+}
+/**
+* The 200 body is a PER-ASPECT OUTCOME MAP, not a success flag, so the render
+* shows all three outcomes verbatim and `exitCodeForChannelSettings` turns an
+* unapplied one into exit 11.
+*/
+function renderAspectOutcomes(result, line) {
+	renderTable(["ASPECT", "OUTCOME"], [
+		["schedule", result.schedule],
+		["interval", result.interval],
+		["filterRules", result.filterRules]
+	], line);
+}
+function buildNotificationsCommand(deps = {}) {
+	const resolveClient = deps.resolveClient ?? ((baseUrlFlag) => resolveApiClient({ baseUrlFlag }));
+	const createOutput = deps.createOutput ?? processOutput;
+	const readStdin = deps.readStdin ?? readAllStdin$1;
+	const group = new Command("notifications").description("List notification channels, switch them on or off, and read or write their delivery settings");
+	group.command("list").description("List the delivery channels this key owns").option("--limit <n>", "Channels per page (the API allows 1-200, default 200)").option("--cursor <cursor>", "Resume from a previous answer’s nextCursor").option("--all", "Walk every page and emit one combined result").action(async (_options, command) => {
+		const options = command.optsWithGlobals();
+		await runCommand({
+			out: createOutput(options.json ?? false),
+			run: async () => {
+				const all = options.all ?? false;
+				const cursor = options.cursor ?? null;
+				assertPagingFlags({
+					all,
+					cursor
+				});
+				const limit = parseLimit(options.limit);
+				const client = await resolveClient(options.baseUrl ?? null);
+				const fetchPage = (pageCursor) => callAction(client, "list-notification-channels", {
+					limit,
+					cursor: pageCursor ?? void 0
+				});
+				return all ? walkAllPages(fetchPage, "channels") : fetchPage(cursor);
+			},
+			renderHuman: (page, line) => renderTable(CHANNEL_COLUMNS, page.channels.map(channelRow), line)
+		});
+	});
+	group.command("toggle").description("Turn one channel on or off").argument("<id>", "Channel id, from \"notifications list\"").option("--on", "Deliver on this channel").option("--off", "Stop delivering on this channel").action(async (id, _options, command) => {
+		const options = command.optsWithGlobals();
+		await runCommand({
+			out: createOutput(options.json ?? false),
+			run: async () => {
+				const enabled = requiredSwitch(options);
+				return callAction(await resolveClient(options.baseUrl ?? null), "toggle-notification-channel", {
+					id,
+					enabled
+				});
+			},
+			renderHuman: (result, line) => renderTable(["ID", "ENABLED"], [[result.id, yesNo(result.isEnabled)]], line)
+		});
+	});
+	group.command("settings").description("Read one channel’s delivery settings, or write them with --input").argument("<id>", "Channel id, from \"notifications list\"").option("--input <json|@file|->", "Aspects to WRITE, as a JSON object: schedule, interval, filterRules. At least one is required, each REPLACES that aspect wholesale, and \"template\" is not writable. Without this flag the command reads instead.").action(async (id, _options, command) => {
+		const options = command.optsWithGlobals();
+		const out = createOutput(options.json ?? false);
+		const input = options.input;
+		if (input === void 0) {
+			await runCommand({
+				out,
+				run: async () => {
+					return callAction(await resolveClient(options.baseUrl ?? null), "get-notification-channel-settings", { id });
+				},
+				renderHuman: renderSettings
+			});
+			return;
+		}
+		await runCommand({
+			out,
+			run: async () => {
+				const aspects = await readInputObject({
+					raw: input,
+					readStdin,
+					expects: INPUT_EXPECTS
+				});
+				return callAction(await resolveClient(options.baseUrl ?? null), "update-notification-channel-settings", {
+					...aspects,
+					id
+				});
+			},
+			renderHuman: renderAspectOutcomes,
+			exitCodeFor: exitCodeForChannelSettings
+		});
+	});
+	return group;
+}
+//#endregion
+//#region src/commands/searches.ts
+/**
+* The `searches` command group (spec 301 → CLI → Command surface).
+*
+* `list`, `create`, `update`, `pause`, `resume`, `delete`, `export`, `import`.
+*
+* Argument mapping and rendering ONLY. The transport (`callAction`), the
+* envelope and exit discipline (`runCommand`), the `--all` walk
+* (`walkAllPages`) and the bulk mechanism (`bulk.ts`) all live in the shared
+* core; nothing in this file speaks HTTP, formats an error or sets an exit code
+* of its own.
+*/
+async function readAllStdin() {
+	const chunks = [];
+	process.stdin.setEncoding("utf8");
+	for await (const chunk of process.stdin) chunks.push(String(chunk));
+	return chunks.join("");
+}
+function resolveDeps(deps) {
+	return {
+		resolveClient: deps.resolveClient ?? resolveApiClient,
+		createOutput: deps.createOutput ?? processOutput,
+		readStdin: deps.readStdin ?? readAllStdin,
+		isInteractive: deps.isInteractive ?? processIsInteractive,
+		confirm: deps.confirm ?? confirmOnTerminal
+	};
+}
+const SEARCH_COLUMNS = [
+	"ID",
+	"NAME",
+	"KEYWORDS",
+	"SITE",
+	"ENABLED"
+];
+function searchCells(search) {
+	return [
+		search.id,
+		search.name,
+		search.keywords,
+		search.site,
+		search.isEnabled ? "yes" : "no"
+	];
+}
+function decimalFlag(raw, flag) {
+	if (raw === void 0) return void 0;
+	const value = Number(raw);
+	if (raw.trim() === "" || !Number.isFinite(value)) throw new CliError(2, `${flag} must be a number.`);
+	return value;
+}
+function wholeNumberFlag(raw, flag) {
+	const value = decimalFlag(raw, flag);
+	if (value !== void 0 && !Number.isInteger(value)) throw new CliError(2, `${flag} must be a whole number.`);
+	return value;
+}
+function asCreateBody(fields) {
+	return fields;
+}
+function asUpdateChanges(fields) {
+	return fields;
+}
+/**
+* Commander's option KEY beside the flag a user actually typed. The refusal
+* below names the flag, not the key: `priceMin` is not something anyone can drop
+* from a command line.
+*/
+const CREATE_FIELD_FLAGS = [
+	["name", "--name"],
+	["keywords", "--keywords"],
+	["site", "--site"],
+	["priceMin", "--price-min"],
+	["priceMax", "--price-max"],
+	["condition", "--condition"]
+];
+/**
+* `--input` and the same command's field flags are mutually exclusive —
+* supplying both is a usage error, never a merge, because a merged body is
+* unreadable from the command line.
+*
+* The check runs BEFORE the branch, deliberately: putting it inside the
+* field-flag branch is unreachable the moment `--input` is present, which is the
+* only case it exists to catch.
+*/
+async function resolveCreateFields(options, readStdin) {
+	const supplied = CREATE_FIELD_FLAGS.filter(([key]) => Reflect.get(options, key) !== void 0).map(([, flag]) => flag);
+	if (options.input !== void 0) {
+		if (supplied.length > 0) throw new CliError(2, `Use --input or the field flags, not both. Drop --input, or drop: ${supplied.join(", ")}.`);
+		return readInputObject({
+			raw: options.input,
+			readStdin
+		});
+	}
+	return buildCreateFields(options);
+}
+function buildCreateFields(options) {
+	if (options.name === void 0 || options.keywords === void 0) throw new CliError(2, "searches create needs --name and --keywords, or an --input body carrying them.");
+	return {
+		name: options.name,
+		keywords: options.keywords,
+		site: options.site,
+		priceMin: decimalFlag(options.priceMin, "--price-min"),
+		priceMax: decimalFlag(options.priceMax, "--price-max"),
+		conditions: options.condition
+	};
+}
+function listCommand(deps) {
+	return new Command("list").description("List saved searches").option("--query <text>", "Filter by name or keywords").option("--limit <count>", "Rows per page (1-50, default 20)").option("--cursor <cursor>", "Resume from a previous page").option("--all", "Walk every page and emit one result").action(async function runList() {
+		const options = this.optsWithGlobals();
+		await runCommand({
+			out: deps.createOutput(options.json ?? false),
+			run: async () => {
+				const all = options.all ?? false;
+				assertPagingFlags({
+					all,
+					cursor: options.cursor
+				});
+				const limit = wholeNumberFlag(options.limit, "--limit");
+				const client = await deps.resolveClient({ baseUrlFlag: options.baseUrl ?? null });
+				const page = (cursor) => callAction(client, "list-saved-searches", {
+					query: options.query,
+					limit,
+					cursor: cursor ?? void 0
+				});
+				return all ? walkAllPages(page, "savedSearches") : page(options.cursor);
+			},
+			renderHuman: (data, line) => {
+				renderTable(SEARCH_COLUMNS, data.savedSearches.map(searchCells), line);
+			}
+		});
+	});
+}
+function createCommand(deps) {
+	return new Command("create").description("Create a saved search").option("--input <json|@file|->", "The whole request body as JSON").option("--name <name>", "Saved search name").option("--keywords <keywords>", "eBay keyword query").option("--site <site>", "eBay site, e.g. EBAY_US").option("--price-min <amount>", "Minimum price").option("--price-max <amount>", "Maximum price").option("--condition <condition...>", "Item condition; repeat for several").action(async function runCreate() {
+		const options = this.optsWithGlobals();
+		await runCommand({
+			out: deps.createOutput(options.json ?? false),
+			run: async () => {
+				const fields = await resolveCreateFields(options, deps.readStdin);
+				return callAction(await deps.resolveClient({ baseUrlFlag: options.baseUrl ?? null }), "create-saved-search", asCreateBody(fields));
+			},
+			renderHuman: (data, line) => {
+				renderTable(SEARCH_COLUMNS, [searchCells(data.savedSearch)], line);
+			}
+		});
+	});
+}
+function updateCommand(deps) {
+	return new Command("update").description("Apply a partial change set to one saved search").argument("<id>", "Saved search id, from \"searches list\"").option("--input <json|@file|->", "The CHANGES object as JSON — the CLI wraps it").action(async function runUpdate(id) {
+		const options = this.optsWithGlobals();
+		await runCommand({
+			out: deps.createOutput(options.json ?? false),
+			run: async () => {
+				const input = options.input;
+				if (input === void 0) throw new CliError(2, "searches update needs --input carrying the fields to change.");
+				const changes = asUpdateChanges(await readInputObject({
+					raw: input,
+					readStdin: deps.readStdin
+				}));
+				return callAction(await deps.resolveClient({ baseUrlFlag: options.baseUrl ?? null }), "update-saved-search", {
+					id,
+					changes
+				});
+			},
+			renderHuman: (data, line) => {
+				renderTable(SEARCH_COLUMNS, [searchCells(data.savedSearch)], line);
+			}
+		});
+	});
+}
+/**
+* `pause` and `resume` are one action with `enabled` flipped, and it is a SET,
+* not a toggle: the command name is what states which the caller meant.
+*/
+function enabledCommand(deps, name, enabled) {
+	return new Command(name).description(enabled ? "Resume a saved search" : "Pause a saved search").argument("<id>", "Saved search id, from \"searches list\"").action(async function runEnabled(id) {
+		const options = this.optsWithGlobals();
+		await runCommand({
+			out: deps.createOutput(options.json ?? false),
+			run: async () => {
+				return callAction(await deps.resolveClient({ baseUrlFlag: options.baseUrl ?? null }), "pause-or-resume-saved-search", {
+					id,
+					enabled
+				});
+			},
+			renderHuman: (data, line) => {
+				renderTable(["ID", "ENABLED"], [[data.id, data.isEnabled ? "yes" : "no"]], line);
+			}
+		});
+	});
+}
+function deleteCommand(deps) {
+	return new Command("delete").description("Delete a saved search — there is no undelete").argument("<id>", "Saved search id, from \"searches list\"").action(async function runDelete(id) {
+		const options = this.optsWithGlobals();
+		await runCommand({
+			out: deps.createOutput(options.json ?? false),
+			run: async () => {
+				return callAction(await deps.resolveClient({ baseUrlFlag: options.baseUrl ?? null }), "delete-saved-search", { id });
+			},
+			renderHuman: (data, line) => {
+				line(`Deleted saved search ${data.id}`);
+			}
+		});
+	});
+}
+/**
+* `export` IMPLIES `--all` and offers neither `--limit` nor `--cursor`.
+*
+* A partial export is a corrupt backup, so this is the one read that walks every
+* page by default rather than on request (spec 301 → Paging). Offering the two
+* paging flags would let a caller write a one-page file that looks exactly like
+* a whole-account one.
+*
+* `customFieldDefinitions` is NOT concatenated across pages: it is whole-account
+* and repeats verbatim on every page, so the walker keeps the last page's copy.
+* The rows are the only per-page array this export carries.
+*/
+function exportCommand(deps) {
+	return new Command("export").description("Write every saved search as a backup document — always walks every page").action(async function runExport() {
+		const options = this.optsWithGlobals();
+		await runCommand({
+			out: deps.createOutput(options.json ?? false),
+			run: async () => {
+				const client = await deps.resolveClient({ baseUrlFlag: options.baseUrl ?? null });
+				return walkAllPages((cursor) => callAction(client, "export-saved-searches", { cursor: cursor ?? void 0 }), "searches");
+			},
+			renderHuman: (data, line) => {
+				line(`Exported ${String(data.searches.length)} saved search(es).`);
+				renderTable([
+					"ALIAS",
+					"FOLDER",
+					"SITE"
+				], data.searches.map((row) => [
+					row["eBay Search Alias"],
+					row["Folder Path"] ?? "",
+					row.Site ?? ""
+				]), line);
+			}
+		});
+	});
+}
+/**
+* The third seam where a body the CLI did not type-check becomes a typed
+* request, alongside `asCreateBody` and `asUpdateChanges` above — narrow, named
+* and greppable rather than one general helper.
+*
+* It exists because spec 301 makes the server the only schema validator and
+* `--input` is by definition a document this build has not inspected.
+*/
+function asImportRows(rows) {
+	return rows;
+}
+function asDefinitions(value) {
+	return Array.isArray(value) ? value : [];
+}
+function importBody(rows, document, options) {
+	return {
+		searches: asImportRows(rows),
+		customFieldDefinitions: asDefinitions(document["customFieldDefinitions"]),
+		preview: options.preview ?? false,
+		replaceAll: options.replaceAll ?? false,
+		targetFolderId: options.targetFolder ?? null
+	};
+}
+function importCommand(deps) {
+	return new Command("import").description("Restore saved searches from a backup document").argument("[file]", "Path to the export document, or \"-\" for stdin").option("--input <json|@file|->", "The document as JSON, instead of the positional").option("--preview", "Validate and report without writing anything").option("--replace-all", "DELETE every existing saved search first — destructive").option("--target-folder <id>", "File every imported search into this folder").option("--yes", "Acknowledge --replace-all without an interactive prompt").action(async function runImport(file) {
+		const options = this.optsWithGlobals();
+		const json = options.json ?? false;
+		await runCommand({
+			out: deps.createOutput(json),
+			run: async () => {
+				if (file !== void 0 && options.input !== void 0) throw new CliError(2, "Use the file argument or --input, not both. They are two ways to supply one body.");
+				const raw = options.input ?? (file === void 0 ? void 0 : fileSource(file));
+				if (raw === void 0) throw new CliError(2, "searches import needs a file argument, or --input carrying the export document.");
+				const document = await readInputObject({
+					raw,
+					readStdin: deps.readStdin,
+					expects: "It should carry the \"searches\" array an export document holds."
+				});
+				const rows = readRows(document, "searches", "saved searches");
+				await assertReplaceAllAllowed({
+					replaceAll: options.replaceAll ?? false,
+					yes: options.yes ?? false,
+					json,
+					bodyFromStdin: raw === "-",
+					chunkCount: chunkRows(rows, BULK_IMPORT_ROWS_MAX).length,
+					documentSkippedCount: documentSkippedCount(document),
+					entity: "saved searches",
+					deps
+				});
+				const client = await deps.resolveClient({ baseUrlFlag: options.baseUrl ?? null });
+				return runChunkedImport({
+					rows,
+					sendChunk: (batch) => callAction(client, "import-saved-searches", importBody(batch, document, options))
+				});
+			},
+			renderHuman: renderImportResult,
+			exitCodeFor: exitCodeForImport
+		});
+	});
+}
+/** `-` stays stdin; anything else is a path, which `--input` spells `@path`. */
+function fileSource(file) {
+	return file === "-" ? "-" : `@${file}`;
+}
+function buildSearchesCommand(deps = {}) {
+	const resolved = resolveDeps(deps);
+	return new Command("searches").description("Manage saved searches").addCommand(listCommand(resolved)).addCommand(createCommand(resolved)).addCommand(updateCommand(resolved)).addCommand(enabledCommand(resolved, "pause", false)).addCommand(enabledCommand(resolved, "resume", true)).addCommand(deleteCommand(resolved)).addCommand(exportCommand(resolved)).addCommand(importCommand(resolved));
+}
+//#endregion
+//#region src/program.ts
+/**
+* The program tree, and the one place commander's OWN parse failures are turned
+* into an exit code (spec 301 → CLI → Exit codes).
+*
+* Split out of `cli.ts` so it can be driven by a test: `cli.ts` is the bin
+* entry and runs on import, which is exactly what a test cannot do. `cli.ts`
+* keeps the Node floor check and nothing else.
+*/
+function buildProgram() {
+	const program = new Command();
+	program.name("ubuyfirst").description("Command-line interface for the uBuyFirst public API").version(version).option("--json", "Emit machine-readable JSON output").option("--base-url <url>", "Override the API base URL");
+	program.addCommand(buildSearchesCommand());
+	program.addCommand(buildFoldersCommand());
+	program.addCommand(buildBlocklistCommand());
+	program.addCommand(buildNotificationsCommand());
+	program.addCommand(buildFiltersCommand());
+	program.addCommand(buildConfigCommand());
+	return program;
+}
+/**
+* Makes commander THROW its parse failures instead of exiting, and routes the
+* text it writes about them to `sink`.
+*
+* Both settings are per-command and are NOT inherited by a command joined with
+* `addCommand` (verified against commander 15), so both are applied down the
+* whole tree — otherwise every subcommand, which is every command in the
+* surface, keeps exiting on its own.
+*
+* `writeErr` alone: `writeOut` stays commander's, so `--help` and `--version`
+* still print to stdout.
+*/
+function captureParseFailures(command, sink) {
+	command.exitOverride();
+	command.configureOutput({ writeErr: sink });
+	for (const child of command.commands) captureParseFailures(child, sink);
+}
+async function runProgram(argv, createOutput = processOutput) {
+	const program = buildProgram();
+	let buffered = "";
+	captureParseFailures(program, (text) => {
+		buffered += text;
+	});
+	try {
+		await program.parseAsync([...argv], { from: "user" });
+		return;
+	} catch (thrown) {
+		if (!(thrown instanceof CommanderError)) throw thrown;
+		const out = createOutput(program.opts().json ?? false);
+		if (thrown.exitCode === 0) {
+			out.setExitCode(0);
+			return;
+		}
+		const written = buffered === "" ? `error: ${thrown.message}\n` : buffered;
+		if (out.json) {
+			const trimmed = written.trimEnd();
+			const message = trimmed.startsWith("error: ") ? trimmed.slice(7) : trimmed;
+			await runCommand({
+				out,
+				run: () => Promise.reject(new CliError(2, message)),
+				renderHuman: () => void 0
+			});
+			return;
+		}
+		out.stderr.write(written);
+		out.setExitCode(2);
+	}
+}
+//#endregion
+export { runProgram };