ubuyfirst 0.1.0 → 0.2.0

package/README.md

@@ -1,8 +1,8 @@
 # ubuyfirst
 
 Command-line interface for the [uBuyFirst public API](https://app.ubuyfirst.com/api/docs) —
-manage your saved searches, folders, blocklists and notification channels from a terminal or a
-script, and back them up to a file.
+manage your saved searches, item filters, folders, blocklists and notification channels from a
+terminal or a script, and back them up to a file.
 
 Requires Node.js 22.12 or newer.
 
@@ -22,7 +22,7 @@ immediately invalidates the old one.
 Store it — the CLI reads the key from stdin so it never lands in your shell history:
 
 ```bash
-ubuyfirst config set-key      # paste the key, then press Enter
+ubuyfirst config set-key      # paste the key, then Enter and Ctrl-D (Ctrl-Z on Windows)
 ubuyfirst config show         # config path, whether a key is stored, effective base URL
 ```
 
@@ -32,23 +32,26 @@ precedence over the stored key. `ubuyfirst config clear` removes what is stored.
 ## Commands
 
 ```
-searches       list, create, update, pause, resume, delete, export, import
-folders        list, create, rename, delete, move
-blocklist      list, add, remove          (sellers, countries, items)
-notifications  list, toggle, settings
-filters        export, import
-config         set-key, show, clear
+searches        list, create, update, pause, resume, delete, export, import
+folders         list, create, rename, delete, move
+blocklist       list, add, remove
+notifications   list, toggle, settings
+filters         list, get, create, update, delete, move, export, import
+filter-folders  list, create, rename, reorder, move, delete, attach, detach, attachments
+config          set-key, show, clear
 ```
 
-Run `ubuyfirst <group> --help` for the flags of any group.
+Run `ubuyfirst <group> --help` for the flags of any group. `blocklist` works on three separate
+lists — sellers, countries and items — chosen with `--type`.
 
 ```bash
 ubuyfirst searches list --limit 20
 ubuyfirst searches create --name "Leica M6" --keywords "leica m6" --price-max 2500
 ubuyfirst searches pause abc123
 ubuyfirst blocklist add --type sellers badseller99 anotherseller
-ubuyfirst searches export > backup.json
+ubuyfirst --json searches export > backup.json
 ubuyfirst searches import backup.json --preview
+ubuyfirst --json filters export > filters.json
 ```
 
 Bulk imports accept `--preview` to report what *would* change without writing anything.
@@ -56,12 +59,17 @@ Bulk imports accept `--preview` to report what *would* change without writing an
 ## Scripting
 
 `--json` makes any command — including a failure — emit exactly one parseable JSON document
-on stdout:
+on stdout. It works before or after the group name. `--help` and `--version` are the two
+exceptions: they always print plain text.
 
 ```bash
-ubuyfirst --json searches list | jq '.searches[].name'
+ubuyfirst --json searches list | jq '.savedSearches[].name'
 ```
 
+Without it commands print human-readable text — for the exports, a table — so a backup
+written as `ubuyfirst searches export > backup.json` is not a document `searches import`
+can read.
+
 Exit codes are stable, so a script can branch on the failure without parsing text:
 
 | Code | Meaning | Code | Meaning |
@@ -72,6 +80,7 @@ Exit codes are stable, so a script can branch on the failure without parsing tex
 | 3 | validation error | 9 | write failed |
 | 4 | missing or invalid API key | 10 | server error — retriable |
 | 5 | access denied | 11 | partly applied; see the output |
+| | | 12 | request body too large — send fewer rows |
 
 Codes 8 and 10 are the retriable ones. Client-side refusals also carry a `cli.`-prefixed error
 code in `--json` output (`cli.usage`, `cli.no_key`, `cli.unexpected`) so you can tell them from

package/dist/cli.js

@@ -56,7 +56,7 @@ if (!floorCheck.ok) {
 	process.stderr.write(`${floorCheck.message}\n`);
 	process.exitCode = 1;
 } else {
-	const { runProgram } = await import("./program-YTm6g9Ut.js");
+	const { runProgram } = await import("./program-BFXGjkBy.js");
 	await runProgram(process.argv.slice(2));
 }
 //#endregion

package/dist/{program-YTm6g9Ut.js → program-BFXGjkBy.js}

@@ -7,7 +7,7 @@ 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";
+var version = "0.2.0";
 //#endregion
 //#region src/errors.ts
 /**
@@ -71,7 +71,8 @@ const EXIT_BY_ERROR_CODE = {
 	CAP_EXCEEDED: 7,
 	HTTP_429: 8,
 	WRITE_FAILED: 9,
-	HTTP_5XX: 10
+	HTTP_5XX: 10,
+	PAYLOAD_TOO_LARGE: 12
 };
 /**
 * Codes for a failure the CLI decided ITSELF, for the `--json` document it emits
@@ -540,15 +541,16 @@ async function callAction(client, path, body) {
 * settings` spreads it with `id` LAST so the positional argument always wins.
 * Folding those into one shape would change what each command sends.
 */
+const DEFAULT_FLAG = "--input";
 /** `-` is stdin, `@path` is a file, anything else is the literal itself. */
-async function readSource(raw, readStdin) {
+async function readSource(raw, readStdin, flag) {
 	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)}`);
+		throw new CliError(2, `Cannot read ${flag} file ${path}: ${thrown instanceof Error ? thrown.message : String(thrown)}`);
 	}
 }
 /**
@@ -560,14 +562,15 @@ async function readSource(raw, readStdin) {
 * the only one the CLI performs on an `--input` document.
 */
 async function readInputObject(request) {
-	const text = await readSource(request.raw, request.readStdin);
+	const flag = request.flag ?? DEFAULT_FLAG;
+	const text = await readSource(request.raw, request.readStdin, flag);
 	let parsed;
 	try {
 		parsed = JSON.parse(text);
 	} catch {
-		throw new CliError(2, "--input is not valid JSON.");
+		throw new CliError(2, `${flag} 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}`}`);
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new CliError(2, `${flag} must be a JSON object, not an array or a scalar.${request.expects === void 0 ? "" : ` ${request.expects}`}`);
 	return parsed;
 }
 //#endregion
@@ -795,7 +798,7 @@ async function runCommand(options) {
 *   - **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.
+*     goes in it — including whether a country code is one it knows.
 */
 /**
 * TOTAL over the type union the generated document publishes: a fourth list
@@ -822,7 +825,7 @@ function parseType(raw) {
 	return raw;
 }
 /** The 1–200 range is the server's to enforce; this only refuses a non-number. */
-function parseLimit$2(raw) {
+function parseLimit$4(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);
@@ -834,22 +837,12 @@ function addEntriesFromKeys(type, keys, reason) {
 			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.");
+		case "countries": return keys.map((countryCode) => ({ countryCode }));
 	}
 }
-/**
-* 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];
+/** BARE string keys for all three types: seller names, ISO country codes, listing ids. */
+function removeKeysFromArguments(_type, keys) {
+	return [...keys];
 }
 /**
 * What the object is expected to carry, for the shared parser's refusal. It is
@@ -901,15 +894,7 @@ function renderList(data, line) {
 			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);
+			renderTable(["CODE", "NAME"], data.entries.map((entry) => [entry.countryCode, entry.countryName]), line);
 			return;
 		case "items":
 			renderTable([
@@ -940,7 +925,7 @@ async function readAllStdin$3() {
 	for await (const chunk of process.stdin) text += String(chunk);
 	return text;
 }
-function resolveDeps$2(overrides) {
+function resolveDeps$3(overrides) {
 	return {
 		resolveClient: overrides.resolveClient ?? ((baseUrlFlag) => resolveApiClient({ baseUrlFlag })),
 		createOutput: overrides.createOutput ?? processOutput,
@@ -956,7 +941,7 @@ function buildListCommand(deps) {
 			out: deps.createOutput(options.json ?? false),
 			run: async () => {
 				const type = parseType(options.type);
-				const limit = parseLimit$2(options.limit);
+				const limit = parseLimit$4(options.limit);
 				const all = options.all ?? false;
 				assertPagingFlags({
 					all,
@@ -979,7 +964,7 @@ function buildListCommand(deps) {
 	});
 }
 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) => {
+	return new Command("add").description("Block sellers, countries or items").argument("[keys...]", "seller names, two-letter ISO country codes, or eBay listing ids").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),
@@ -1006,7 +991,7 @@ function buildAddCommand(deps) {
 	});
 }
 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) => {
+	return new Command("remove").description("Unblock sellers, countries or items").argument("[keys...]", "the stored keys: seller names, ISO country codes, 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),
@@ -1036,7 +1021,7 @@ function buildRemoveCommand(deps) {
 * is reachable on the two write verbs by putting `"scope":"team"` in `--input`.
 */
 function buildBlocklistCommand(overrides = {}) {
-	const deps = resolveDeps$2(overrides);
+	const deps = resolveDeps$3(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
@@ -1171,6 +1156,315 @@ function buildConfigCommand(deps = {}) {
 	return group;
 }
 //#endregion
+//#region src/commands/filter-folders.ts
+/**
+* The `filter-folders` command group (spec 302).
+*
+* `list`, `create`, `rename`, `move`, `reorder` and `delete` over the FILTER
+* folder tree, plus `attachments`, `attach` and `detach` over the links between
+* a folder and the saved searches that run it.
+*
+* THIS IS NOT THE `folders` GROUP. Two separate trees with two separate id
+* namespaces: an id from `folders list` is refused here exactly like a folder
+* belonging to someone else, and the reverse. Nothing carries an id between
+* them, and the flag names deliberately do not invite it.
+*
+* ONE VERB, ONE THING. `create` and `move` and `rename` each refuse the fields
+* that belong to another — `sortOrder` is `reorder`'s alone, `parentId` is
+* `move`'s — and every one of those bodies is closed server-side, so a flag for
+* a field its action rejects would answer VALIDATION on every run. That is why
+* `rename` and `delete` declare no options at all (D5, D7).
+*
+* FOLDERS ARE PERSONAL ON THIS SURFACE (D3). A team's shared folders are never
+* listed, and an account whose folders all belong to a team reads an EMPTY list
+* rather than a refusal — the server deliberately cannot distinguish that from
+* an account with no folders, so neither may this command.
+*
+* Argument mapping and rendering ONLY, like every other group — the transport,
+* the exit discipline and the page walk all live in the shared core.
+*
+* 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 that accessor in this directory.
+*/
+function resolveDeps$2(deps) {
+	return {
+		resolveClient: deps.resolveClient ?? resolveApiClient,
+		createOutput: deps.createOutput ?? processOutput
+	};
+}
+const FOLDER_COLUMNS$1 = [
+	"ID",
+	"NAME",
+	"PARENT",
+	"SORT"
+];
+/** What a null parent renders as: the folder is at the root, not missing a value. */
+const NONE$2 = "-";
+function usage$2(message) {
+	return new CliError(2, message);
+}
+/**
+* `sortOrder` is the folder's own position among its SIBLINGS in the folder
+* tree. On `attachments` it is still that number and NOT the folder's position
+* among a search's attachments — the attachment's own position is deliberately
+* not emitted, because every attach writes the same value.
+*/
+function folderRow$1(folder) {
+	return [
+		folder.id,
+		folder.name,
+		folder.parentId ?? NONE$2,
+		String(folder.sortOrder)
+	];
+}
+/**
+* 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. The SHAPE is not the server's
+* problem to report — `abc` would travel as a string and come back as a
+* VALIDATION the caller cannot read as their own typo.
+*/
+function parseLimit$3(raw) {
+	if (raw === void 0) return void 0;
+	if (!/^\d+$/.test(raw)) throw usage$2(`--limit must be a whole number, not "${raw}".`);
+	return Number(raw);
+}
+function listCommand$2(deps) {
+	return new Command("list").description("List filter folders. A PARENT of - means the folder is at the root. Personal folders only — a team’s shared folders are never listed, and an account whose folders all belong to a team reads an empty list. They are still there.").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 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 = parseLimit$3(options.limit);
+				const client = await deps.resolveClient({ baseUrlFlag: options.baseUrl ?? null });
+				if (all) return walkAllPages((cursor) => callAction(client, "list-filter-folders", {
+					limit,
+					cursor: cursor ?? void 0
+				}), "folders");
+				return callAction(client, "list-filter-folders", {
+					limit,
+					cursor: options.cursor
+				});
+			},
+			renderHuman: (data, line) => renderTable(FOLDER_COLUMNS$1, data.folders.map(folderRow$1), line)
+		});
+	});
+}
+function createCommand$2(deps) {
+	return new Command("create").description("Create a filter folder. It starts EMPTY — \"filters move\" files filters into it.").argument("<name>", "Folder name").option("--parent <id>", "Nest inside this folder id, from \"filter-folders list\" (default: root)").action(async function runCreate(name) {
+		const options = this.optsWithGlobals();
+		await runCommand({
+			out: deps.createOutput(options.json ?? false),
+			run: async () => {
+				return callAction(await deps.resolveClient({ baseUrlFlag: options.baseUrl ?? null }), "create-filter-folder", {
+					name,
+					parentId: options.parent ?? null
+				});
+			},
+			renderHuman: (data, line) => renderTable(FOLDER_COLUMNS$1, [folderRow$1(data.folder)], line)
+		});
+	});
+}
+/**
+* NO OPTIONS AT ALL, and that is the contract rather than an omission.
+* `parentId` and `sortOrder` are not fields of `update-filter-folder`'s body and
+* the body is closed, so a flag for either would answer VALIDATION on every run
+* — while looking like a rename that also moved the folder. Reparenting is
+* `move`; ordering is `reorder`.
+*/
+function renameCommand(deps) {
+	return new Command("rename").description("Rename a filter folder. Rename ONLY — nothing inside it changes, and re-parenting is \"move\".").argument("<id>", "Folder id, from \"filter-folders list\"").argument("<name>", "The new name").action(async function runRename(id, name) {
+		const options = this.optsWithGlobals();
+		await runCommand({
+			out: deps.createOutput(options.json ?? false),
+			run: async () => {
+				return callAction(await deps.resolveClient({ baseUrlFlag: options.baseUrl ?? null }), "update-filter-folder", {
+					id,
+					name
+				});
+			},
+			renderHuman: (data, line) => renderTable(["ID", "NAME"], [[data.id, data.name]], line)
+		});
+	});
+}
+/**
+* `--parent <id>` XOR `--root`, exactly one, decided locally before any HTTP
+* call. `parentId` is nullable rather than optional precisely so that "move it
+* to the top level" is something the caller SAID — an omitted key would be a
+* silent move to the root.
+*
+* NO `--index`. The body is closed and carries none, so the folder KEEPS the
+* position number it already had and where it lands among its new siblings is
+* not chosen here. Follow the move with `reorder` when the position matters.
+*/
+function moveCommand$1(deps) {
+	return new Command("move").description("Move a filter folder under a different parent, or to the root. The whole subtree travels with it and nothing is deleted.").argument("<id>", "Folder id, from \"filter-folders list\"").option("--parent <id>", "New parent folder id, from \"filter-folders list\"").option("--root", "Move it to the top level — sends an explicit null").action(async function runMove(id) {
+		const options = this.optsWithGlobals();
+		await runCommand({
+			out: deps.createOutput(options.json ?? false),
+			run: async () => {
+				const root = options.root ?? false;
+				if (options.parent !== void 0 && root) throw usage$2("Use --parent <id> or --root, not both. A folder sits under one parent, or at the top level.");
+				if (options.parent === void 0 && !root) throw usage$2("A move needs --parent <id> or --root. There is no default destination, so the CLI will not choose one for you.");
+				return callAction(await deps.resolveClient({ baseUrlFlag: options.baseUrl ?? null }), "move-filter-folder", {
+					id,
+					parentId: options.parent ?? null
+				});
+			},
+			renderHuman: (data, line) => renderTable(["ID", "PARENT"], [[data.id, data.parentId ?? NONE$2]], line)
+		});
+	});
+}
+/**
+* The only command that writes folder order — `create`, `rename` and `move` all
+* refuse `sortOrder` outright (D5).
+*
+* ITS TWO REFUSALS ARE THE SERVER'S AND REACH THE USER VERBATIM. A duplicated
+* id and a list that is not the parent's complete sibling set need DIFFERENT
+* fixes from the caller, and the service names its own rule in each message, so
+* nothing here collapses them into one wording. `runCommand` prints that
+* message on stderr and emits the envelope unchanged under `--json`.
+*/
+function reorderCommand(deps) {
+	return new Command("reorder").description("Set the order of one parent’s filter folders. Pass the COMPLETE sibling set in its new order — each folder’s position is its place in the list, not a delta. A list that repeats an id, or that is missing a sibling, is refused and NOTHING is written.").argument("<folderId...>", "Every folder id under the parent, in the order they should take").option("--parent <id>", "The parent whose children these are (default: the root set)").action(async function runReorder(folderIds) {
+		const options = this.optsWithGlobals();
+		await runCommand({
+			out: deps.createOutput(options.json ?? false),
+			run: async () => {
+				return callAction(await deps.resolveClient({ baseUrlFlag: options.baseUrl ?? null }), "reorder-filter-folders", {
+					parentId: options.parent ?? null,
+					folderIds
+				});
+			},
+			renderHuman: (data, line) => renderTable([
+				"PARENT",
+				"POSITION",
+				"ID"
+			], data.folderIds.map((id, index) => [
+				data.parentId ?? NONE$2,
+				String(index),
+				id
+			]), line)
+		});
+	});
+}
+/**
+* NO `--delete-contents`, and no `--input` either.
+*
+* `deleteContents` is a real service parameter that destroys every child folder
+* and every filter inside them, and it is NOT a field of this action's body.
+* The body is closed, so sending it is a VALIDATION error — a CLI flag for it
+* would therefore fail on every single run while promising a cascade the API
+* does not offer (D7). Deleting the filters too means calling
+* `filters delete` for each one first.
+*
+* The id is required and there is no body a flag could carry beyond it.
+*/
+function deleteCommand$2(deps) {
+	return new Command("delete").description("Delete a filter folder. Nothing inside is deleted: its item filters become unfiled and keep matching, and any folder nested inside moves up to this folder’s own parent. Your LAST remaining folder cannot be deleted — that one is refused.").argument("<id>", "Folder id, from \"filter-folders 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-filter-folder", { id });
+			},
+			renderHuman: (data, line) => renderTable(["ID"], [[data.id]], line)
+		});
+	});
+}
+function attachmentsCommand(deps) {
+	return new Command("attachments").description("List the filter folders attached to ONE saved search. An empty list means no PERSONAL folders are attached; a team’s are never shown.").argument("<searchId>", "Saved-search id, from \"searches list\"").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 function runAttachments(searchId) {
+		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 = parseLimit$3(options.limit);
+				const client = await deps.resolveClient({ baseUrlFlag: options.baseUrl ?? null });
+				if (all) return walkAllPages((cursor) => callAction(client, "list-search-filter-folders", {
+					searchId,
+					limit,
+					cursor: cursor ?? void 0
+				}), "folders");
+				return callAction(client, "list-search-filter-folders", {
+					searchId,
+					limit,
+					cursor: options.cursor
+				});
+			},
+			renderHuman: (data, line) => renderTable(FOLDER_COLUMNS$1, data.folders.map(folderRow$1), line)
+		});
+	});
+}
+/**
+* BOTH COUNTS ARE RENDERED, because a 200 here does not mean the batch landed.
+* The folder is the subject of the call and an unreachable one refuses it
+* outright; a SEARCH is one of many, so an unreachable one is silently skipped
+* and the call still succeeds — otherwise the batch would answer "does this
+* search id exist and is it yours?" one id at a time (G4). A body whose search
+* ids are all unreachable therefore answers `attached: 0`, and only the counts
+* say so.
+*/
+function attachCommand(deps) {
+	return new Command("attach").description("Attach a filter folder to saved searches, so they run the item filters in it. Read the counts: an unreachable search is SKIPPED, not refused, so the call can succeed having attached nothing.").argument("<folderId>", "Filter folder id, from \"filter-folders list\"").argument("<searchId...>", "One or more saved-search ids, from \"searches list\"").action(async function runAttach(folderId, searchIds) {
+		const options = this.optsWithGlobals();
+		await runCommand({
+			out: deps.createOutput(options.json ?? false),
+			run: async () => {
+				return callAction(await deps.resolveClient({ baseUrlFlag: options.baseUrl ?? null }), "attach-filter-folder-to-searches", {
+					folderId,
+					searchIds
+				});
+			},
+			renderHuman: (data, line) => renderTable([
+				"FOLDER",
+				"ATTACHED",
+				"SKIPPED"
+			], [[
+				data.folderId,
+				String(data.attached),
+				String(data.skipped)
+			]], line)
+		});
+	});
+}
+/**
+* `detached` IS THE COUNT ACTUALLY REMOVED, never the size of the list sent. A
+* pair that was not attached removes nothing and an unreachable id removes
+* nothing, and the number does not separate the two — so `detached: 0` means
+* nothing changed, not that the folder was never attached.
+*/
+function detachCommand(deps) {
+	return new Command("detach").description("Detach a filter folder from saved searches, so they stop running the item filters in it. Nothing is deleted, and DETACHED counts what was actually removed.").argument("<folderId>", "Filter folder id, from \"filter-folders list\"").argument("<searchId...>", "One or more saved-search ids, from \"searches list\"").action(async function runDetach(folderId, searchIds) {
+		const options = this.optsWithGlobals();
+		await runCommand({
+			out: deps.createOutput(options.json ?? false),
+			run: async () => {
+				return callAction(await deps.resolveClient({ baseUrlFlag: options.baseUrl ?? null }), "detach-filter-folder-from-searches", {
+					folderId,
+					searchIds
+				});
+			},
+			renderHuman: (data, line) => renderTable(["FOLDER", "DETACHED"], [[data.folderId, String(data.detached)]], line)
+		});
+	});
+}
+function buildFilterFoldersCommand(deps = {}) {
+	const resolved = resolveDeps$2(deps);
+	return new Command("filter-folders").description("Manage the filter-folder tree and its attachments to saved searches").addCommand(attachCommand(resolved)).addCommand(attachmentsCommand(resolved)).addCommand(createCommand$2(resolved)).addCommand(deleteCommand$2(resolved)).addCommand(detachCommand(resolved)).addCommand(listCommand$2(resolved)).addCommand(moveCommand$1(resolved)).addCommand(renameCommand(resolved)).addCommand(reorderCommand(resolved));
+}
+//#endregion
 //#region src/bulk.ts
 /**
 * Bulk export/import mechanism, shared by `searches` and `filters`
@@ -1430,6 +1724,8 @@ function foldResults(results, frames) {
 			toCreate: previews.reduce((sum, result) => sum + result.toCreate, 0),
 			toUpdate: previews.reduce((sum, result) => sum + result.toUpdate, 0),
 			existingCount: first.existingCount,
+			replaceAll: first.replaceAll,
+			toDelete: first.toDelete,
 			...diagnostics
 		};
 	}
@@ -1528,6 +1824,7 @@ function renderImportResult(result, line) {
 	}
 	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.replaceAll) line(`REPLACE-ALL: ${String(result.toDelete)} existing row(s) would be DELETED first.`);
 		if (!result.valid) line("This file cannot be imported as it stands.");
 		return;
 	}
@@ -1564,20 +1861,30 @@ function exitCodeForExport(skipped) {
 //#endregion
 //#region src/commands/filters.ts
 /**
-* The `filters` command group (spec 301 → Bulk export/import).
+* The `filters` command group.
+*
+* `list`, `get`, `create`, `update`, `delete` and `move` over the item-filter
+* actions, plus `export` and `import` over the two bulk verbs. One subcommand
+* per endpoint the API serves, which is the rule that decides what may be added
+* here: a command ahead of its endpoint would be a command with nothing behind
+* it. The filter-FOLDER actions are a separate tree with a separate id
+* namespace and live in `filter-folders.ts`.
+*
+* WHY THE GROUP EXISTED BEFORE THE CRUD, since spec 301's command surface says
+* the two bulk 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.
 *
-* 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.
+* FILING A FILTER IS ONE CALL, NEVER TWO. `create` and `update` both refuse
+* `folderId` and `sortOrder` server-side, so `move` is the only command that
+* files a filter and it sets parent and position together (D5). There is
+* deliberately no `reorder` command for filters.
 *
-* 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.
+* FILTERS ARE PERSONAL ON THIS SURFACE (spec 302 D3). A team's shared filters are
+* never listed, and an account whose filters all belong to a team reads an EMPTY
+* list rather than a refusal — the server deliberately cannot distinguish that
+* from an account with no filters, so neither may this command.
 *
 * 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
@@ -1598,6 +1905,218 @@ function resolveDeps$1(deps) {
 		confirm: deps.confirm ?? confirmOnTerminal
 	};
 }
+const FILTER_COLUMNS = [
+	"ID",
+	"NAME",
+	"FOLDER",
+	"ACTION",
+	"ENABLED"
+];
+/** What a null folder renders as: the filter is unfiled, not missing a value. */
+const NONE$1 = "-";
+function filterRow(filter) {
+	return [
+		filter.id,
+		filter.name,
+		filter.folderId ?? NONE$1,
+		filter.action,
+		filter.isEnabled ? "yes" : "no"
+	];
+}
+function usage$1(message) {
+	return new CliError(2, message);
+}
+/**
+* The three closed vocabularies the write flags accept, DERIVED from the
+* generated document rather than copied from the server's zod enums.
+*
+* `satisfies` is what binds them: a value the server DROPS stops this
+* compiling, so a flag cannot outlive the contract. The reverse — a value the
+* server ADDS — is not caught here and would make the flag refuse something the
+* API accepts; the refusal below names every accepted value, so a caller learns
+* it in one run rather than from a `VALIDATION` round trip.
+*
+* They are checked at all only because the mistake is visible LOCALLY. The
+* server stays the only schema validator for everything it alone can know —
+* `--tag-color`'s pattern and `--description`'s length are deliberately not
+* checked here.
+*/
+const FILTER_ACTIONS = [
+	"add_tag",
+	"hide",
+	"block_countries",
+	"allow_countries",
+	"notify_include",
+	"notify_exclude"
+];
+const FILTER_SCOPES = ["GLOBAL", "SEARCHES"];
+const FILTER_TYPES = ["general", "country"];
+/**
+* Narrows a flag's raw string to one of a closed set, WITHOUT an assertion:
+* `.find` over a `readonly T[]` answers `T | undefined`, so the return type is
+* established by the search rather than claimed over it.
+*/
+function closedValue(values, raw, flag) {
+	const found = values.find((value) => value === raw);
+	if (found === void 0) throw usage$1(`${flag} must be one of: ${values.join(", ")}. Got "${raw}".`);
+	return found;
+}
+/**
+* The rule tree, read through the SHARED `--input` reader — a literal, `@file`
+* or `-` for stdin — because a rule tree is not something anyone types on a
+* command line. `filters import` reads its document the same way; this is that
+* one mechanism pointed at one field, not a second input path.
+*
+* It carries ONE field, which is why it is `--rules` and not `--input`. A
+* whole-body flag here could set `name` or `action` behind the command line's
+* back; this one cannot say anything the command does not already name.
+*/
+function readRuleTree(raw, readStdin) {
+	return readInputObject({
+		raw,
+		readStdin,
+		flag: "--rules",
+		expects: "It should be the rule GROUP — take one from a \"filters get\" or \"filters export\" answer."
+	});
+}
+/** The optional write fields, mapped once for both `create` and `update`. */
+function optionalWriteFields(options) {
+	return {
+		description: options.description,
+		tagColor: options.tagColor,
+		scope: options.scope === void 0 ? void 0 : closedValue(FILTER_SCOPES, options.scope, "--scope"),
+		filterType: options.filterType === void 0 ? void 0 : closedValue(FILTER_TYPES, options.filterType, "--filter-type")
+	};
+}
+async function createBody$1(name, options, readStdin) {
+	if (options.action === void 0) throw usage$1(`--action is required, one of: ${FILTER_ACTIONS.join(", ")}.`);
+	if (options.rules === void 0) throw usage$1("--rules is required and carries the rule group: a JSON literal, @file, or - for stdin.");
+	return {
+		name,
+		action: closedValue(FILTER_ACTIONS, options.action, "--action"),
+		rules: await readRuleTree(options.rules, readStdin),
+		...optionalWriteFields(options)
+	};
+}
+/**
+* `--enable` XOR `--disable`, and NEITHER is legal — unlike `notifications
+* toggle`, where the field is required. `isEnabled` is one optional field of a
+* partial update, so "not mentioned" is a real answer meaning leave it alone.
+*/
+function enabledSwitch(options) {
+	const enable = options.enable ?? false;
+	const disable = options.disable ?? false;
+	if (enable && disable) throw usage$1("Use --enable or --disable, not both. \"isEnabled\" is a SET, not a flip, so the CLI will not choose one for you.");
+	if (!enable && !disable) return void 0;
+	return enable;
+}
+async function updateBody(filterId, options, readStdin) {
+	const changes = {
+		name: options.name,
+		action: options.action === void 0 ? void 0 : closedValue(FILTER_ACTIONS, options.action, "--action"),
+		rules: options.rules === void 0 ? void 0 : await readRuleTree(options.rules, readStdin),
+		isEnabled: enabledSwitch(options),
+		...optionalWriteFields(options)
+	};
+	if (Object.values(changes).every((value) => value === void 0)) throw usage$1("Name at least one field to change: --name, --action, --rules, --description, --tag-color, --enable, --disable, --scope or --filter-type.");
+	return {
+		filterId,
+		...changes
+	};
+}
+/**
+* The confirmation on the one command that destroys something no other endpoint
+* can rebuild: the rule tree goes with the row, and there is no undelete.
+*
+* Deliberately NOT `folders delete`'s shape, which asks nothing — deleting a
+* SEARCH folder keeps its searches and its children. It is also not
+* `assertReplaceAllAllowed`, whose row-cap and short-document refusals describe
+* a bulk document this command does not have. What is shared is the ORDER:
+* `--yes` acknowledges; `--json` means a machine is reading, so prompting would
+* corrupt the one document that mode promises; a non-terminal has nobody to ask.
+* Declining is the same outcome as never acknowledging — the CLI was asked to do
+* something it did not do.
+*
+* No `bodyFromStdin` case: this command has no `--input`, so nothing has spent
+* the stream a prompt would read the answer from.
+*/
+async function assertDeleteAllowed(request) {
+	if (request.yes) return;
+	const cost = `Deleting filter ${request.filterId} is PERMANENT: its rule tree goes with it, and no endpoint can rebuild it.`;
+	if (request.json || !request.deps.isInteractive()) throw usage$1(`${cost} Re-run with --yes to confirm it.`);
+	if (!await request.deps.confirm(cost)) throw usage$1("Aborted. Nothing was deleted.");
+}
+/**
+* `--index` is OPTIONAL and an absent one is NOT SENT: the action's documented
+* default for a missing index is "last", so the CLI leaves the choice to the
+* server rather than restating its rule as a number. The server CLAMPS a value
+* past the end; a negative one it refuses, and the shape check below refuses
+* it here first.
+*/
+function parseIndex(raw) {
+	if (raw === void 0) return void 0;
+	if (!/^\d+$/.test(raw)) throw usage$1(`--index must be a whole number of 0 or more, not "${raw}".`);
+	return Number(raw);
+}
+/**
+* `--folder <id>` XOR `--unfile`, exactly one, decided locally before any HTTP
+* call — the same split `folders move` makes, and for the same reason:
+* `targetFolderId` is nullable with NO default, so "neither flag" is a guess
+* about which the caller meant. `--unfile` sends an explicit `null`.
+*/
+function moveBody$1(filterId, options) {
+	const unfile = options.unfile ?? false;
+	if (options.folder !== void 0 && unfile) throw usage$1("Use --folder <id> or --unfile, not both. A filter sits in one folder, or in none.");
+	if (options.folder === void 0 && !unfile) throw usage$1("A move needs --folder <id> or --unfile. There is no default target folder, so the CLI will not choose one for you.");
+	return {
+		filterId,
+		targetFolderId: options.folder ?? null,
+		index: parseIndex(options.index)
+	};
+}
+/**
+* Rejects a `--limit` that is not a whole number and stops there — the same
+* split `folders list` makes. The RANGE is the server's (1–200): it is the only
+* schema validator, and a copy of its bounds here would go stale the day they
+* move. The SHAPE is not the server's problem to report: `abc` would travel as a
+* string and come back as a VALIDATION the caller cannot read as their own typo.
+*/
+function parseLimit$2(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);
+}
+/**
+* NO RULE TREE IS LISTED HERE, and that is the endpoint's contract rather than a
+* rendering choice: a summary row carries none of the conditions a filter
+* matches on. `filters export` is where the full definition lives.
+*/
+function listCommand$1(deps) {
+	return new Command("list").description("List item filters. A FOLDER of - means the filter is unfiled. Personal filters only — a team’s shared filters are never listed, and an account whose filters all belong to a team reads an empty list. They are still there.").option("--limit <n>", "Filters 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 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 = parseLimit$2(options.limit);
+				const client = await deps.resolveClient({ baseUrlFlag: options.baseUrl ?? null });
+				if (all) return walkAllPages((cursor) => callAction(client, "list-item-filters", {
+					limit,
+					cursor: cursor ?? void 0
+				}), "filters");
+				return callAction(client, "list-item-filters", {
+					limit,
+					cursor: options.cursor
+				});
+			},
+			renderHuman: (data, line) => renderTable(FILTER_COLUMNS, data.filters.map(filterRow), line)
+		});
+	});
+}
 /**
 * `export` IMPLIES `--all`, on the same reasoning as `searches export`: a
 * partial export is a corrupt backup, so neither `--limit` nor `--cursor` is
@@ -1715,9 +2234,113 @@ function importCommand$1(deps) {
 		});
 	});
 }
+const RULES_DESCRIPTION = "The rule GROUP as JSON: a literal, @file, or - for stdin. Take one from \"filters get\".";
+/**
+* The only command that carries a rule tree back to the caller.
+*
+* The tree is rendered as JSON below the summary row rather than squeezed into
+* a column: it is a recursive structure with no tabular form, and abbreviating
+* it would describe what a filter matches from an answer that no longer says
+* so. `filters list` carries no tree at all, which is why this command exists.
+*/
+function getCommand(deps) {
+	return new Command("get").description("Read ONE item filter, rule tree included").argument("<id>", "Filter id, from \"filters list\"").action(async function runGet(id) {
+		const options = this.optsWithGlobals();
+		await runCommand({
+			out: deps.createOutput(options.json ?? false),
+			run: async () => {
+				return callAction(await deps.resolveClient({ baseUrlFlag: options.baseUrl ?? null }), "get-item-filter", { filterId: id });
+			},
+			renderHuman: (data, line) => {
+				const filter = data.filter;
+				renderTable([
+					...FILTER_COLUMNS,
+					"SCOPE",
+					"TYPE"
+				], [[
+					...filterRow(filter),
+					filter.scope,
+					filter.filterType
+				]], line);
+				if (filter.description !== null) line(`description: ${filter.description}`);
+				if (filter.tagColor !== null) line(`tagColor: ${filter.tagColor}`);
+				line(JSON.stringify(filter.rules ?? null, null, 2) ?? "null");
+			}
+		});
+	});
+}
+function createCommand$1(deps) {
+	return new Command("create").description("Create an item filter. It is appended UNFILED — \"filters move\" files it.").argument("<name>", "Filter name").option("--action <action>", `What the filter does: ${FILTER_ACTIONS.join(", ")}`).option("--rules <json|@file|->", RULES_DESCRIPTION).option("--description <text>", "Free-text note on the filter").option("--tag-color <color>", "Tag colour, for the add_tag action").option("--scope <scope>", `Where it applies: ${FILTER_SCOPES.join(", ")} (default SEARCHES)`).option("--filter-type <type>", `Filter kind: ${FILTER_TYPES.join(", ")} (default general)`).action(async function runCreate(name) {
+		const options = this.optsWithGlobals();
+		await runCommand({
+			out: deps.createOutput(options.json ?? false),
+			run: async () => {
+				const body = await createBody$1(name, options, deps.readStdin);
+				return callAction(await deps.resolveClient({ baseUrlFlag: options.baseUrl ?? null }), "create-item-filter", body);
+			},
+			renderHuman: (data, line) => renderTable(FILTER_COLUMNS, [filterRow(data.filter)], line)
+		});
+	});
+}
+function updateCommand$1(deps) {
+	return new Command("update").description("Change an item filter. A PARTIAL update — only the fields you name are written.").argument("<id>", "Filter id, from \"filters list\"").option("--name <name>", "New filter name").option("--action <action>", `What the filter does: ${FILTER_ACTIONS.join(", ")}`).option("--rules <json|@file|->", `${RULES_DESCRIPTION} REPLACES the whole tree.`).option("--description <text>", "Free-text note. It can be changed but not cleared.").option("--tag-color <color>", "Tag colour. It can be changed but not cleared.").option("--enable", "Turn the filter on").option("--disable", "Turn the filter off").option("--scope <scope>", `Where it applies: ${FILTER_SCOPES.join(", ")}`).option("--filter-type <type>", `Filter kind: ${FILTER_TYPES.join(", ")}`).action(async function runUpdate(id) {
+		const options = this.optsWithGlobals();
+		await runCommand({
+			out: deps.createOutput(options.json ?? false),
+			run: async () => {
+				const body = await updateBody(id, options, deps.readStdin);
+				return callAction(await deps.resolveClient({ baseUrlFlag: options.baseUrl ?? null }), "update-item-filter", body);
+			},
+			renderHuman: (data, line) => renderTable(FILTER_COLUMNS, [filterRow(data.filter)], line)
+		});
+	});
+}
+/**
+* No `--input`, and the id is REQUIRED — the whole body is `{ filterId }`, so a
+* body could only restate or OVERRIDE the filter the command already names.
+* `folders delete` and `searches delete` are the same shape.
+*/
+function deleteCommand$1(deps) {
+	return new Command("delete").description("Delete an item filter. PERMANENT — the rule tree goes with it and no endpoint can rebuild it.").argument("<id>", "Filter id, from \"filters list\"").option("--yes", "Confirm the deletion without an interactive prompt").action(async function runDelete(id) {
+		const options = this.optsWithGlobals();
+		const json = options.json ?? false;
+		await runCommand({
+			out: deps.createOutput(json),
+			run: async () => {
+				await assertDeleteAllowed({
+					filterId: id,
+					yes: options.yes ?? false,
+					json,
+					deps
+				});
+				return callAction(await deps.resolveClient({ baseUrlFlag: options.baseUrl ?? null }), "delete-item-filter", { filterId: id });
+			},
+			renderHuman: (data, line) => renderTable(["ID"], [[data.id]], line)
+		});
+	});
+}
+/**
+* THE ONLY COMMAND THAT FILES A FILTER, and it sets the position in the same
+* call. `create` and `update` both refuse `folderId` and `sortOrder`
+* server-side, so there is one checked mechanism rather than two that can
+* disagree (D5) — and no separate `reorder` command for filters.
+*/
+function moveCommand(deps) {
+	return new Command("move").description("File an item filter under a filter folder, or under none, optionally at a position").argument("<id>", "Filter id, from \"filters list\"").option("--folder <id>", "Target FILTER folder id, from \"filter-folders list\"").option("--unfile", "File the filter under no folder — sends an explicit null").option("--index <n>", "0-based position among the target’s filters; past the end means last. Omitted: last").action(async function runMove(id) {
+		const options = this.optsWithGlobals();
+		await runCommand({
+			out: deps.createOutput(options.json ?? false),
+			run: async () => {
+				const body = moveBody$1(id, options);
+				return callAction(await deps.resolveClient({ baseUrlFlag: options.baseUrl ?? null }), "move-item-filter-to-folder", body);
+			},
+			renderHuman: (data, line) => renderTable(["FILTER", "FOLDER"], [[data.id, data.folderId ?? NONE$1]], line)
+		});
+	});
+}
 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));
+	return new Command("filters").description("Manage item filters: list, read, create, change, delete, file, export and import").addCommand(createCommand$1(resolved)).addCommand(deleteCommand$1(resolved)).addCommand(exportCommand$1(resolved)).addCommand(getCommand(resolved)).addCommand(importCommand$1(resolved)).addCommand(listCommand$1(resolved)).addCommand(moveCommand(resolved)).addCommand(updateCommand$1(resolved));
 }
 //#endregion
 //#region src/commands/folders.ts
@@ -2017,6 +2640,23 @@ function readAllStdin$1() {
 * check — nothing here enumerates the fields.
 */
 const INPUT_EXPECTS = "The object carries the aspects to write; the server validates their contents.";
+const TEMPLATE_DROPPED = "warning: \"template\" is read-only and was dropped from the write; the other aspects were sent.";
+/**
+* The ONE field the CLI removes from `--input`, against the rule that the server
+* is the only validator of it. The read document is the write body — every
+* aspect comes back in the shape the write takes, and the read-only echoes
+* inside them (`lastBatchAt`, `filterName`) are the server's to strip — except
+* `template`, which the server refuses outright as not writable. Dropping it
+* here, with a warning on stderr, is what lets `settings X > doc.json`, edit,
+* `settings X --input @doc.json` work; refusing would make every round trip
+* start with deleting a key by hand. Null if there was nothing to drop.
+*/
+function withoutTemplate(aspects) {
+	if (!Object.hasOwn(aspects, "template")) return null;
+	const writable = { ...aspects };
+	Reflect.deleteProperty(writable, "template");
+	return writable;
+}
 function describeSchedule(schedule) {
 	if (schedule === null) return NOT_CONFIGURED;
 	if (schedule.scheduleType === "ALWAYS") return "ALWAYS";
@@ -2108,7 +2748,7 @@ function buildNotificationsCommand(deps = {}) {
 			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) => {
+	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 — each in the shape the read prints, so an edited read document is a valid input. At least one is required and each REPLACES that aspect wholesale. \"template\" is not writable and is dropped with a warning. 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;
@@ -2125,11 +2765,14 @@ function buildNotificationsCommand(deps = {}) {
 		await runCommand({
 			out,
 			run: async () => {
-				const aspects = await readInputObject({
+				const document = await readInputObject({
 					raw: input,
 					readStdin,
 					expects: INPUT_EXPECTS
 				});
+				const writable = withoutTemplate(document);
+				if (writable !== null) out.stderr.write(`${TEMPLATE_DROPPED}\n`);
+				const aspects = writable ?? document;
 				return callAction(await resolveClient(options.baseUrl ?? null), "update-notification-channel-settings", {
 					...aspects,
 					id
@@ -2273,7 +2916,7 @@ function listCommand(deps) {
 	});
 }
 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() {
+	return new Command("create").description("Create a saved search. It lands in the first root folder, as on the website; use \"folders move\" to file it elsewhere").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),
@@ -2467,6 +3110,7 @@ function buildProgram() {
 	program.addCommand(buildBlocklistCommand());
 	program.addCommand(buildNotificationsCommand());
 	program.addCommand(buildFiltersCommand());
+	program.addCommand(buildFilterFoldersCommand());
 	program.addCommand(buildConfigCommand());
 	return program;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ubuyfirst",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Command-line interface for the uBuyFirst public API",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://app.ubuyfirst.com/api/docs",
@@ -16,6 +16,9 @@
   "files": [
     "dist"
   ],
+  "publishConfig": {
+    "provenance": false
+  },
   "engines": {
     "node": ">=22.12.0"
   },