@tikoci/centrs 0.1.9-next.24 → 0.1.9

package/src/cli/devices.ts

@@ -22,6 +22,7 @@ import {
 	describeCentrs,
 	devicesOutputFormats,
 	editInteractiveOnlyError,
+	encryptCdb,
 	initCdb,
 	listDevices,
 	listGroups,
@@ -45,13 +46,39 @@ import {
 	unknownFlagError,
 } from "./common.ts";
 
-export const devicesCommand: CliCommandMetadata = {
+/**
+ * Flags `init`/`encrypt` honor. They touch only the CDB file, never a record,
+ * so record, selection, and provenance flags would be silently ignored there.
+ */
+const CDB_FILE_FLAGS: Readonly<Record<"init" | "encrypt", readonly string[]>> =
+	{
+		init: ["--cdb-file", "--cdb-password", "--format", "--json", "--encrypt"],
+		encrypt: [
+			"--cdb-file",
+			"--cdb-password",
+			"--format",
+			"--json",
+			"--no-backup",
+		],
+	};
+
+const devicesMetadata: CliCommandMetadata = {
 	name: "devices",
 	usage:
-		"centrs devices <init|list|show|groups|add|edit|set|remove> [args] [flags]",
+		"centrs devices <init|encrypt|list|show|groups|add|edit|set|remove> [args] [flags]",
 	summary:
 		"Inspect and mutate the CDB-backed device registry. `devices` is the only command that writes the CDB.",
 	options: [
+		{
+			flag: "--encrypt",
+			description:
+				"`init` only — require encrypted creation with a non-empty CDB password; refuse an existing open CDB.",
+		},
+		{
+			flag: "--no-backup",
+			description:
+				"`encrypt` only — skip the plaintext pre-conversion snapshot. Without that snapshot, a forgotten password cannot be recovered.",
+		},
 		{
 			flag: "--cdb-file",
 			valueName: "<path>",
@@ -62,7 +89,7 @@ export const devicesCommand: CliCommandMetadata = {
 			flag: "--cdb-password",
 			valueName: "<secret>",
 			description:
-				"Decrypt an encrypted CDB. Falls back to `CENTRS_CDB_PASSWORD`. Also used to re-encrypt on writes.",
+				"CDB password for encrypted reads, writes, explicit encrypted initialization and conversion. Falls back to `CENTRS_CDB_PASSWORD`; a password alone never converts an open CDB.",
 		},
 		{
 			flag: "--via",
@@ -74,7 +101,7 @@ export const devicesCommand: CliCommandMetadata = {
 			flag: "--group",
 			valueName: "<name>",
 			description:
-				"`list` filter / `add`,`edit` first-class group field for the target entry.",
+				"`list` filter / `add`,`set` first-class group field for the target entry.",
 		},
 		{
 			flag: "--where",
@@ -101,13 +128,13 @@ export const devicesCommand: CliCommandMetadata = {
 		{
 			flag: "--explain",
 			description:
-				"`show` only — include the raw `WinBoxCdbRecord` in `data.record`.",
+				"`show` only — include the raw `WinBoxCdbRecord` in `data.record` (its password field reads `<redacted>` unless `--show-password`).",
 		},
 		{
 			flag: "--match",
 			valueName: "<user=…|target=…|record-type>",
 			description:
-				"`show` — disambiguate when `<router>` matches several records: `user=<name>`, `target=<addr>`, or a record-type token.",
+				"`show`,`set`,`remove` — disambiguate when `<router>` matches several records: `user=<name>`, `target=<addr>`, or a record-type token.",
 		},
 		{
 			flag: "--user",
@@ -119,6 +146,16 @@ export const devicesCommand: CliCommandMetadata = {
 			valueName: "<secret>",
 			description: "`add`,`set` — first-class CDB password field.",
 		},
+		{
+			flag: "--password-stdin",
+			description:
+				"`add`,`set` — read the record password from stdin (one trailing newline stripped) so it never rides argv. Conflicts with `--password`.",
+		},
+		{
+			flag: "--show-password",
+			description:
+				"`show`,`add`,`set` — include the record password in cleartext. By default output carries `passwordSet` and withholds the password.",
+		},
 		{
 			flag: "--profile",
 			valueName: "<name>",
@@ -198,8 +235,24 @@ export const devicesCommand: CliCommandMetadata = {
 	],
 };
 
+export const devicesCommand: CliCommandMetadata = {
+	...devicesMetadata,
+	subcommands: (["init", "encrypt"] as const).map((name) => ({
+		name,
+		usage: `centrs devices ${name} [flags]`,
+		summary:
+			name === "init"
+				? "Create an empty CDB at the resolved path; existing readable files are left unchanged."
+				: "Encrypt an existing CDB in place, or verify an already-encrypted file; existing backups remain unchanged.",
+		options: devicesMetadata.options.filter((option) =>
+			CDB_FILE_FLAGS[name].includes(option.flag),
+		),
+	})),
+};
+
 type DevicesSubcommand =
 	| "init"
+	| "encrypt"
 	| "list"
 	| "show"
 	| "groups"
@@ -226,6 +279,8 @@ interface DevicesCliArgs {
 	subcommand?: DevicesSubcommand;
 	cdbFile?: string;
 	cdbPassword?: string;
+	encrypt?: boolean;
+	noBackup?: boolean;
 	group?: string;
 	where?: string[];
 	via?: string;
@@ -234,6 +289,8 @@ interface DevicesCliArgs {
 	match?: string;
 	user?: string;
 	password?: string;
+	passwordStdin?: boolean;
+	showPassword?: boolean;
 	profile?: string;
 	profileNone?: boolean;
 	profileOwn?: boolean;
@@ -257,17 +314,25 @@ interface DevicesCliArgs {
 function parseDevicesCliArgs(args: readonly string[]): DevicesCliArgs {
 	const parsed: DevicesCliArgs = {};
 	const positional: string[] = [];
+	const suppliedFlags: string[] = [];
 
 	for (let index = 0; index < args.length; index += 1) {
 		const arg = args[index];
 		if (arg === undefined) {
 			continue;
 		}
+		if (arg.startsWith("-")) suppliedFlags.push(arg);
 		switch (arg) {
 			case "--help":
 			case "-h":
 				parsed.help = true;
 				break;
+			case "--encrypt":
+				parsed.encrypt = true;
+				break;
+			case "--no-backup":
+				parsed.noBackup = true;
+				break;
 			case "--cdb-file":
 				parsed.cdbFile = expectValue(args, ++index, arg);
 				break;
@@ -306,6 +371,18 @@ function parseDevicesCliArgs(args: readonly string[]): DevicesCliArgs {
 				break;
 			case "--password":
 				parsed.password = expectValue(args, ++index, arg);
+				// `--password --password-stdin` would otherwise store the literal
+				// flag as the password and never read stdin. Treat it as both flags
+				// so the conflict check below refuses it.
+				if (parsed.password === "--password-stdin") {
+					parsed.passwordStdin = true;
+				}
+				break;
+			case "--password-stdin":
+				parsed.passwordStdin = true;
+				break;
+			case "--show-password":
+				parsed.showPassword = true;
 				break;
 			case "--profile":
 				parsed.profile = expectValue(args, ++index, arg);
@@ -377,11 +454,14 @@ function parseDevicesCliArgs(args: readonly string[]): DevicesCliArgs {
 	}
 
 	if (parsed.help) {
+		const sub = positional[0];
+		if (sub === "init" || sub === "encrypt") parsed.subcommand = sub;
 		return parsed;
 	}
 
 	const subcommands: readonly DevicesSubcommand[] = [
 		"init",
+		"encrypt",
 		"list",
 		"show",
 		"groups",
@@ -393,17 +473,23 @@ function parseDevicesCliArgs(args: readonly string[]): DevicesCliArgs {
 	const [rawSub, ...rest] = positional;
 	if (rawSub === undefined) {
 		throw new Error(
-			"`centrs devices` requires a subcommand: init, list, show, groups, add, edit, set, or remove.",
+			"`centrs devices` requires a subcommand: init, encrypt, list, show, groups, add, edit, set, or remove.",
 		);
 	}
 	// Resolve aliases (print/get/rm/delete) to the canonical verb before validating.
 	const sub = SUBCOMMAND_ALIASES[rawSub] ?? (rawSub as DevicesSubcommand);
 	if (!subcommands.includes(sub)) {
 		throw new Error(
-			`Unknown devices subcommand: ${rawSub}. Use init, list, show, groups, add, edit, set, or remove (aliases: print, get, rm, delete).`,
+			`Unknown devices subcommand: ${rawSub}. Use init, encrypt, list, show, groups, add, edit, set, or remove (aliases: print, get, rm, delete).`,
 		);
 	}
 	parsed.subcommand = sub;
+	if (parsed.encrypt && sub !== "init")
+		throw new Error(
+			"--encrypt is supported only by devices init; use devices encrypt for conversion.",
+		);
+	if (parsed.noBackup && sub !== "encrypt")
+		throw new Error("--no-backup is supported only by devices encrypt.");
 
 	// Reject flags that don't apply to the resolved subcommand instead of
 	// silently ignoring the user's input: `--where`/`--near`/`--bbox` select
@@ -446,6 +532,51 @@ function parseDevicesCliArgs(args: readonly string[]): DevicesCliArgs {
 			context: { subcommand: sub, flag: geoFlag },
 		});
 	}
+	if (sub === "init" || sub === "encrypt") {
+		const allowed = CDB_FILE_FLAGS[sub];
+		const ignored = suppliedFlags.find((flag) => !allowed.includes(flag));
+		if (ignored !== undefined) {
+			throw new CentrsError({
+				code: "input/invalid-command",
+				summary: `\`${ignored}\` is not supported by \`centrs devices ${sub}\`.`,
+				remediation: `\`centrs devices ${sub}\` accepts only ${allowed.map((flag) => `\`${flag}\``).join(", ")}. Edit records with \`centrs devices add\`/\`set\`.`,
+				context: { subcommand: sub, flag: ignored },
+			});
+		}
+	}
+
+	if (parsed.passwordStdin && sub !== "add" && sub !== "set") {
+		throw new CentrsError({
+			code: "input/invalid-command",
+			summary: `\`--password-stdin\` is not supported by \`centrs devices ${sub}\`.`,
+			remediation:
+				"`--password-stdin` writes a record password with `centrs devices add`/`set` (e.g. `printf '%s' \"$PW\" | centrs devices set <target> --password-stdin`).",
+			context: { subcommand: sub, flag: "--password-stdin" },
+		});
+	}
+	if (parsed.passwordStdin && parsed.password !== undefined) {
+		throw new CentrsError({
+			code: "usage/conflicting-flags",
+			summary: "`--password` and `--password-stdin` cannot be used together.",
+			remediation:
+				"Pass the record password one way: `--password-stdin` with the value on stdin (keeps it out of argv and `ps`), or `--password <secret>`.",
+			context: { subcommand: sub, flags: ["--password", "--password-stdin"] },
+		});
+	}
+	if (
+		parsed.showPassword === true &&
+		sub !== "show" &&
+		sub !== "add" &&
+		sub !== "set"
+	) {
+		throw new CentrsError({
+			code: "input/invalid-command",
+			summary: `\`--show-password\` is not supported by \`centrs devices ${sub}\`.`,
+			remediation:
+				"`--show-password` reveals the record password in `centrs devices show`, `add` and `set` output. Run `centrs devices show <target> --show-password`.",
+			context: { subcommand: sub, flag: "--show-password" },
+		});
+	}
 
 	if (sub === "show" || sub === "edit" || sub === "remove") {
 		if (rest.length !== 1) {
@@ -511,7 +642,14 @@ function parseKvArg(token: string): CommentKvUpdate {
 	// canonical key a `--lon`/`--lat`/`--altitude` flag would use. A no-op for
 	// every non-geo key.
 	const key = canonicalizeGeoKey(token.slice(0, eq));
-	return { key, value: parseKvValue(token.slice(eq + 1)) };
+	const value = parseKvValue(token.slice(eq + 1));
+	// An empty value removes the token (`devices set <t> via=` deletes the
+	// `via` override) instead of storing a literally-empty value, per
+	// `commands/devices/README.md` (Comment kv-soup). The core upsert/remove
+	// model lives in `applyCommentKv` (`src/resolver/comment-kv.ts`), which
+	// treats `value: null` as removal; the CLI lowers `key=` to that form
+	// here. There is currently no need to store a literally-empty value.
+	return { key, value: value === "" ? null : value };
 }
 
 /**
@@ -599,23 +737,115 @@ function resolveProfile(parsed: DevicesCliArgs): string | undefined {
 	return parsed.profile;
 }
 
+/** Seams for {@link readPasswordStdin}; production reads the real fd 0. */
+export interface PasswordStdinSource {
+	/** Whether stdin is a terminal (defaults to `process.stdin.isTTY`). */
+	isTty?: boolean;
+	/** Read all of stdin as raw bytes (defaults to `Bun.stdin.bytes()`). */
+	read?: () => Promise<Uint8Array>;
+}
+
+// `fatal` rejects malformed UTF-8 instead of substituting U+FFFD; `ignoreBOM`
+// keeps a leading U+FEFF visible so it can be refused rather than dropped.
+const stdinPasswordDecoder = new TextDecoder("utf-8", {
+	fatal: true,
+	ignoreBOM: true,
+});
+
+/**
+ * Read a record password for `devices add`/`set --password-stdin` (#582).
+ *
+ * Exactly one trailing `\n` or `\r\n` is stripped (at the byte level) so
+ * `echo pw | …` works; any other whitespace is part of the password. The rest
+ * must be valid UTF-8 without a leading byte-order mark: the CDB stores record
+ * strings as UTF-8 and drops a leading BOM when it reads them back, so either
+ * would silently store a credential different from the bytes piped in. A TTY stdin is refused rather
+ * than prompted (interactive prompting is #160), and empty input is refused so
+ * clearing a stored password stays the deliberate `--password ""`. The value is
+ * never placed in an error summary, remediation, or context.
+ */
+export async function readPasswordStdin(
+	source: PasswordStdinSource = {},
+): Promise<string> {
+	const isTty = source.isTty ?? process.stdin.isTTY === true;
+	if (isTty) {
+		throw new CentrsError({
+			code: "usage/stdin-is-tty",
+			summary:
+				"`--password-stdin` reads the password from stdin, but stdin is a terminal.",
+			remediation:
+				"Pipe the password in (e.g. `printf '%s' \"$PW\" | centrs devices set <target> --password-stdin`) or redirect it from a file with `< pw.txt`. Interactive prompting is not supported.",
+			context: { flag: "--password-stdin" },
+		});
+	}
+	const raw = await (source.read ?? (() => Bun.stdin.bytes()))();
+	const end = raw.length;
+	const trimmed =
+		end >= 2 && raw[end - 2] === 0x0d && raw[end - 1] === 0x0a
+			? raw.subarray(0, end - 2)
+			: end >= 1 && raw[end - 1] === 0x0a
+				? raw.subarray(0, end - 1)
+				: raw;
+	if (trimmed.length === 0) {
+		throw new CentrsError({
+			code: "input/empty-stdin",
+			summary: "`--password-stdin` received an empty password on stdin.",
+			remediation:
+				'Pipe a non-empty password to stdin. To clear a stored password on purpose, use `centrs devices set <target> --password ""`.',
+			context: { flag: "--password-stdin" },
+		});
+	}
+	const invalid = (reason: string) =>
+		new CentrsError({
+			code: "input/invalid-stdin",
+			summary: `\`--password-stdin\` received ${reason}.`,
+			remediation:
+				"Pipe the password as UTF-8 text with no byte-order mark (e.g. `printf '%s' \"$PW\" | centrs devices set <target> --password-stdin`). Re-save a file written by an editor as UTF-8 without BOM.",
+			context: { flag: "--password-stdin", byteLength: trimmed.length },
+		});
+	let value: string;
+	try {
+		value = stdinPasswordDecoder.decode(trimmed);
+	} catch {
+		throw invalid("bytes that are not valid UTF-8");
+	}
+	if (value.startsWith("\uFEFF")) {
+		throw invalid("a leading byte-order mark (U+FEFF)");
+	}
+	return value;
+}
+
 export async function runDevicesCli(args: readonly string[]): Promise<number> {
 	let parsed: DevicesCliArgs | undefined;
 	let envSnapshot: Record<string, string | undefined> | undefined;
 	try {
 		parsed = parseDevicesCliArgs(args);
 		if (parsed.help) {
-			console.log(renderCommandHelp(describeCentrs(), devicesCommand));
+			const command =
+				devicesCommand.subcommands?.find(
+					(subcommand) => subcommand.name === parsed?.subcommand,
+				) ?? devicesCommand;
+			console.log(renderCommandHelp(describeCentrs(), command));
 			return 0;
 		}
 
 		envSnapshot = Bun.env;
-		if (parsed.subcommand === "init") {
-			const envelope = await initCdb({
+		// Read stdin before touching the CDB so a TTY or empty pipe fails fast
+		// without loading (or decrypting) anything. Only add/set get here with
+		// the flag; the parser refuses it on every other subcommand.
+		const password = parsed.passwordStdin
+			? await readPasswordStdin()
+			: parsed.password;
+		if (parsed.subcommand === "init" || parsed.subcommand === "encrypt") {
+			const options = {
 				cdbFile: parsed.cdbFile,
 				cdbPassword: parsed.cdbPassword,
 				env: envSnapshot,
-			});
+			};
+			const envelope =
+				parsed.subcommand === "init"
+					? await initCdb({ ...options, encrypt: parsed.encrypt })
+					: await encryptCdb({ ...options, skipBackup: parsed.noBackup });
 			console.log(renderDevicesEnvelope(envelope, parsed.format ?? "text"));
 			return 0;
 		}
@@ -647,6 +877,7 @@ export async function runDevicesCli(args: readonly string[]): Promise<number> {
 					match: parsed.match,
 					via: parsed.via,
 					env: envSnapshot,
+					showPassword: parsed.showPassword,
 				});
 				break;
 			case "groups":
@@ -670,7 +901,7 @@ export async function runDevicesCli(args: readonly string[]): Promise<number> {
 					target: parsed.target,
 					recordType,
 					user: parsed.user,
-					password: parsed.password,
+					password,
 					group: parsed.group,
 					profile: resolveProfile(parsed),
 					session: parsed.session,
@@ -681,6 +912,7 @@ export async function runDevicesCli(args: readonly string[]): Promise<number> {
 					],
 					force: parsed.force,
 					strict: parsed.strict,
+					showPassword: parsed.showPassword,
 				});
 				break;
 			}
@@ -701,11 +933,12 @@ export async function runDevicesCli(args: readonly string[]): Promise<number> {
 						...(parsed.kvArgs ?? []).map(parseKvArg),
 					],
 					user: parsed.user,
-					password: parsed.password,
+					password,
 					group: parsed.group,
 					profile: resolveProfile(parsed),
 					session: parsed.session,
 					strict: parsed.strict,
+					showPassword: parsed.showPassword,
 				});
 				break;
 			case "remove":

package/src/cli/execute.ts

@@ -58,11 +58,11 @@ export const executeCommand: CliCommandMetadata = {
 	usage:
 		"centrs execute <target> <command> [flags] | centrs execute <target...> -- <command> [flags] | centrs execute --host <host|url> [--] <command> [flags] | centrs execute --group <name> <command> [flags]",
 	summary:
-		"Run a RouterOS read or write command via native API, REST, or mac-telnet.",
+		"Run a RouterOS read or write command via native API, REST, SSH, or mac-telnet.",
 	options: [
 		{
 			flag: "--via",
-			valueName: "<native-api|rest-api|mac-telnet>",
+			valueName: "<native-api|rest-api|ssh|mac-telnet>",
 			description:
 				"Pin the protocol selector; no silent downgrade when set. A bare MAC target defaults to mac-telnet.",
 		},
@@ -121,6 +121,12 @@ export const executeCommand: CliCommandMetadata = {
 			valueName: "<password>",
 			description: "Decrypt an encrypted WinBox CDB file.",
 		},
+		{
+			flag: "--match",
+			valueName: "<user=name|target=addr|record-type>",
+			description:
+				"Pick one of several CDB records saved for <router> (as `devices show --match`); single target only.",
+		},
 		{
 			flag: "--resolve",
 			valueName: "<none|arp>",
@@ -135,7 +141,7 @@ export const executeCommand: CliCommandMetadata = {
 		{
 			flag: "--validate / --no-validate",
 			description:
-				"Run RouterOS :parse and /console/inspect validation before execution (default true; `--validate=false` also accepted).",
+				"Run offline analysis, then RouterOS :parse, plus `/console/inspect` for structured commands over native API/REST (default true; `--validate=false` disables both stages).",
 		},
 		{
 			flag: "--yes",
@@ -262,6 +268,9 @@ export function parseExecuteCliArgs(args: readonly string[]): ExecuteCliArgs {
 			case "--cdb-password":
 				parsed.cdbPassword = expectValue(args, ++index, arg);
 				break;
+			case "--match":
+				parsed.match = expectValue(args, ++index, arg);
+				break;
 			case "--resolve":
 				parsed.resolve = expectValue(args, ++index, arg);
 				break;

package/src/cli/retrieve.ts

@@ -199,6 +199,12 @@ export const retrieveCommand: CliCommandMetadata = {
 			valueName: "<password>",
 			description: "Decrypt an encrypted WinBox CDB file.",
 		},
+		{
+			flag: "--match",
+			valueName: "<user=name|target=addr|record-type>",
+			description:
+				"Pick one of several CDB records saved for <router> (as `devices show --match`); single target only.",
+		},
 		{
 			flag: "--resolve",
 			valueName: "<none|arp>",
@@ -537,6 +543,9 @@ function parseRetrieveCliArgs(args: readonly string[]): RetrieveCliArgs {
 			case "--cdb-password":
 				request.cdbPassword = expectValue(args, ++index, arg);
 				break;
+			case "--match":
+				request.match = expectValue(args, ++index, arg);
+				break;
 			case "--resolve":
 				request.resolve = expectValue(args, ++index, arg);
 				break;

package/src/cli/settings.ts

@@ -191,6 +191,14 @@ function parseSettingsCliArgs(args: readonly string[]): SettingsCliArgs {
 		result.value = rest[1];
 	}
 
+	// A blank <attr> is the caller's input, so reject it here; after parsing,
+	// an untyped throw is reported as internal/* (#587).
+	if (result.attr !== undefined && result.attr.trim() === "") {
+		throw new Error(
+			`\`centrs settings ${result.subcommand}\` requires a non-empty <attr>.`,
+		);
+	}
+
 	return result;
 }
 
@@ -249,12 +257,26 @@ export async function runSettingsCli(args: readonly string[]): Promise<number> {
 	} catch (error) {
 		const format = parsed?.format ?? inferSettingsFormat(args);
 		const settingsFile = defaultSettingsPath(envSnapshot ?? Bun.env);
-		const centrsError = asCentrsError(error, {
-			code: "input/invalid-command",
-			summary: error instanceof Error ? error.message : String(error),
-			remediation:
-				"Use `centrs settings --help` to inspect the supported subcommands and flags.",
-		});
+		const summary = error instanceof Error ? error.message : String(error);
+		// Only argument parsing reports the caller's input. Once the arguments
+		// parsed, an untyped throw (a core or renderer fault) is a centrs bug,
+		// not something `--help` can fix (#587).
+		const centrsError = asCentrsError(
+			error,
+			parsed === undefined
+				? {
+						code: "input/invalid-command",
+						summary,
+						remediation:
+							"Use `centrs settings --help` to inspect the supported subcommands and flags.",
+					}
+				: {
+						code: "internal/settings-failed",
+						summary,
+						remediation:
+							"This is a centrs bug; re-run with `--json` and report the command and the error.",
+					},
+		);
 		const envelope = buildSettingsErrorEnvelope(
 			parsed?.subcommand ?? "print",
 			settingsFile,

package/src/cli/terminal.ts

@@ -97,6 +97,12 @@ export const terminalCommand: CliCommandMetadata = {
 			valueName: "<password>",
 			description: "Decrypt an encrypted WinBox CDB file.",
 		},
+		{
+			flag: "--match",
+			valueName: "<user=name|target=addr|record-type>",
+			description:
+				"Pick one of several CDB records saved for <router> (as `devices show --match`); single target only.",
+		},
 		{
 			flag: "--resolve",
 			valueName: "<none|arp>",
@@ -259,6 +265,9 @@ export function parseTerminalCliArgs(args: readonly string[]): ParsedTerminal {
 			case "--cdb-password":
 				flags.cdbPassword = expectValue(args, ++index, arg);
 				break;
+			case "--match":
+				flags.match = expectValue(args, ++index, arg);
+				break;
 			case "--resolve":
 				flags.resolve = expectValue(args, ++index, arg);
 				break;

package/src/cli/transfer.ts

@@ -73,7 +73,7 @@ export const transferCommand: CliCommandMetadata = {
 			flag: "--via",
 			valueName: "<method>",
 			description:
-				"Pin the method: rest, native, or sftp (large transfers); scp/fetch/ftp are not built yet. Auto picks the cheapest by size/direction.",
+				"Pin the method: rest, native, or sftp (large transfers; `ssh` is an alias); scp/fetch/ftp are not built yet. Auto picks the cheapest by size/direction, after a CDB record's `via=` (ssh→sftp).",
 		},
 		{
 			flag: "--ssh-key",
@@ -164,6 +164,12 @@ export const transferCommand: CliCommandMetadata = {
 			valueName: "<password>",
 			description: "Decrypt an encrypted WinBox CDB file.",
 		},
+		{
+			flag: "--match",
+			valueName: "<user=name|target=addr|record-type>",
+			description:
+				"Pick one of several CDB records saved for <router> (as `devices show --match`); single target only.",
+		},
 		{
 			flag: "--validate / --no-validate",
 			description: "Enable or disable the existence-probe preflight.",
@@ -414,6 +420,9 @@ export function parseTransferCliArgs(
 			case "--cdb-password":
 				flags.cdbPassword = expectValue(args, ++index, arg);
 				break;
+			case "--match":
+				flags.match = expectValue(args, ++index, arg);
+				break;
 			case "--validate":
 				flags.validate = true;
 				break;

package/src/core/error-catalog.ts

@@ -53,6 +53,15 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		summary:
 			"The encrypted CDB could not be decrypted (wrong or missing password).",
 	},
+	{
+		code: "cdb/encrypt-failed",
+		summary: "The CDB could not be rewritten with encryption.",
+	},
+	{
+		code: "cdb/plaintext-backups",
+		summary:
+			"CDB backups may still contain plaintext credentials after encryption.",
+	},
 	{
 		code: "cdb/empty-group",
 		summary:
@@ -95,7 +104,8 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 	},
 	{
 		code: "cdb/password-required",
-		summary: "The CDB is encrypted; a --cdb-password is required to read it.",
+		summary:
+			"A CDB password is required for decryption or explicit encryption.",
 	},
 	{
 		code: "cdb/reserved-key",
@@ -144,6 +154,11 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 	},
 
 	// input/*
+	{
+		code: "input/empty-stdin",
+		summary:
+			"A flag that reads its value from stdin (e.g. `--password-stdin`) received nothing.",
+	},
 	{
 		code: "input/incomplete-gps",
 		summary: "lat/lon (or a --gps tuple) were not given as a complete pair.",
@@ -187,7 +202,13 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 	},
 	{
 		code: "input/invalid-routeros-path",
-		summary: "The RouterOS path is malformed (it must be slash-prefixed).",
+		summary:
+			"The RouterOS path is malformed: not slash-prefixed, a segment that is not a menu name, or characters a REST URL would reinterpret.",
+	},
+	{
+		code: "input/invalid-stdin",
+		summary:
+			"A flag that reads its value from stdin (e.g. `--password-stdin`) received bytes that are not valid UTF-8 text, or began with a byte-order mark.",
 	},
 	{
 		code: "input/invalid-target",
@@ -657,6 +678,11 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		summary:
 			"stdin was redirected but the input came from the positional argument, so anything piped in was not analyzed.",
 	},
+	{
+		code: "usage/stdin-is-tty",
+		summary:
+			"A flag that reads its value from stdin (e.g. `--password-stdin`) was given while stdin is a terminal.",
+	},
 	{
 		code: "usage/fanout-not-supported",
 		summary: