@tikoci/centrs 0.1.2 → 0.1.3

package/src/cli/devices.ts

@@ -4,20 +4,31 @@
  * unchanged from the former monolithic `cli.ts`.
  */
 
-import { asCentrsError, formatCentrsErrorText } from "../errors.ts";
+import {
+	asCentrsError,
+	CentrsError,
+	formatCentrsErrorText,
+} from "../errors.ts";
 import {
 	addDevice,
+	type BboxPredicate,
 	buildDevicesErrorEnvelope,
 	type CommentKvUpdate,
+	canonicalizeGeoKey,
 	type DevicesCommand,
 	type DevicesEnvelope,
 	type DevicesOutputFormat,
+	type DevicesWhereClause,
 	describeCentrs,
 	devicesOutputFormats,
 	editInteractiveOnlyError,
 	listDevices,
 	listGroups,
 	loadCdb,
+	type NearPredicate,
+	parseBbox,
+	parseGpsTuple,
+	parseNear,
 	recordTypeFromName,
 	removeDevice,
 	renderDevicesEnvelope,
@@ -30,6 +41,7 @@ import {
 	type CliCommandMetadata,
 	expectValue,
 	renderCommandHelp,
+	unknownFlagError,
 } from "./common.ts";
 
 export const devicesCommand: CliCommandMetadata = {
@@ -62,6 +74,24 @@ export const devicesCommand: CliCommandMetadata = {
 			description:
 				"`list` filter / `add`,`edit` first-class group field for the target entry.",
 		},
+		{
+			flag: "--where",
+			valueName: "<attr=value>",
+			description:
+				"`list` only — repeatable device-class filter over CDB facts (AND-combined), e.g. `--where lat=37.7749`.",
+		},
+		{
+			flag: "--near",
+			valueName: "<lat>,<lon>,<radius>",
+			description:
+				"`list` only — GPS filter: devices within radius (m/km/mi/ft; bare number = km). Lat-first.",
+		},
+		{
+			flag: "--bbox",
+			valueName: "<south>,<west>,<north>,<east>",
+			description:
+				"`list` only — GPS filter: devices inside the lat-first bounding box.",
+		},
 		{
 			flag: "--members",
 			description: "`groups` only — expand each group's membership.",
@@ -115,6 +145,36 @@ export const devicesCommand: CliCommandMetadata = {
 			valueName: `<${Object.keys(winBoxCdbRecordType).join("|")}>`,
 			description: "`add` only — record type (default `ipAdmin`).",
 		},
+		{
+			flag: "--lat / --latitude",
+			valueName: "<deg>",
+			description:
+				"`add`,`set` — latitude in decimal degrees (-90..90); a comment-kv fact, paired with --lon.",
+		},
+		{
+			flag: "--lon / --lng / --longitude / --long",
+			valueName: "<deg>",
+			description:
+				"`add`,`set` — longitude in decimal degrees (-180..180); a comment-kv fact, paired with --lat.",
+		},
+		{
+			flag: "--altitude / --alt / --ele / --elevation",
+			valueName: "<meters>",
+			description:
+				"`add`,`set` — altitude in meters (may be negative); a comment-kv fact.",
+		},
+		{
+			flag: "--altitude-type / --alt-type",
+			valueName: "<MSL|AGL>",
+			description:
+				"`add`,`set` — vertical datum for --altitude (default MSL); case-insensitive.",
+		},
+		{
+			flag: "--gps",
+			valueName: "<lat>,<lon>[,<altitude>[,<altitude-type>]]",
+			description:
+				"`add`,`set` — combined lat,lon[,altitude[,altitude-type]] convenience (lat-first; missing altitude-type defaults MSL).",
+		},
 		{
 			flag: "--force",
 			description: "`add` only — overwrite the existing (target, user) entry.",
@@ -164,6 +224,7 @@ interface DevicesCliArgs {
 	cdbFile?: string;
 	cdbPassword?: string;
 	group?: string;
+	where?: string[];
 	via?: string;
 	members?: boolean;
 	explain?: boolean;
@@ -181,6 +242,13 @@ interface DevicesCliArgs {
 	format?: DevicesOutputFormat;
 	target?: string;
 	kvArgs?: string[];
+	lat?: string;
+	lon?: string;
+	altitude?: string;
+	altitudeType?: string;
+	gps?: string;
+	near?: NearPredicate;
+	bbox?: BboxPredicate;
 }
 
 function parseDevicesCliArgs(args: readonly string[]): DevicesCliArgs {
@@ -206,6 +274,18 @@ function parseDevicesCliArgs(args: readonly string[]): DevicesCliArgs {
 			case "--group":
 				parsed.group = expectValue(args, ++index, arg);
 				break;
+			case "--where":
+				parsed.where = [
+					...(parsed.where ?? []),
+					expectValue(args, ++index, arg),
+				];
+				break;
+			case "--near":
+				parsed.near = parseNear(expectValue(args, ++index, arg));
+				break;
+			case "--bbox":
+				parsed.bbox = parseBbox(expectValue(args, ++index, arg));
+				break;
 			case "--via":
 				parsed.via = expectValue(args, ++index, arg);
 				break;
@@ -242,6 +322,29 @@ function parseDevicesCliArgs(args: readonly string[]): DevicesCliArgs {
 			case "--record-type":
 				parsed.recordType = expectValue(args, ++index, arg);
 				break;
+			case "--lat":
+			case "--latitude":
+				parsed.lat = expectValue(args, ++index, arg);
+				break;
+			case "--lon":
+			case "--lng":
+			case "--longitude":
+			case "--long":
+				parsed.lon = expectValue(args, ++index, arg);
+				break;
+			case "--altitude":
+			case "--alt":
+			case "--ele":
+			case "--elevation":
+				parsed.altitude = expectValue(args, ++index, arg);
+				break;
+			case "--altitude-type":
+			case "--alt-type":
+				parsed.altitudeType = expectValue(args, ++index, arg);
+				break;
+			case "--gps":
+				parsed.gps = expectValue(args, ++index, arg);
+				break;
 			case "--force":
 				parsed.force = true;
 				break;
@@ -263,7 +366,7 @@ function parseDevicesCliArgs(args: readonly string[]): DevicesCliArgs {
 				break;
 			default:
 				if (arg.startsWith("-")) {
-					throw new Error(`Unknown devices flag: ${arg}`);
+					throw unknownFlagError("devices", arg, devicesCommand.options);
 				}
 				positional.push(arg);
 				break;
@@ -298,6 +401,48 @@ function parseDevicesCliArgs(args: readonly string[]): DevicesCliArgs {
 	}
 	parsed.subcommand = sub;
 
+	// Reject flags that don't apply to the resolved subcommand instead of
+	// silently ignoring the user's input: `--where`/`--near`/`--bbox` select
+	// records for `list`; the GPS *setter* flags write via `add`/`set`.
+	const selectorFlag =
+		(parsed.where?.length ?? 0) > 0
+			? "--where"
+			: parsed.near !== undefined
+				? "--near"
+				: parsed.bbox !== undefined
+					? "--bbox"
+					: undefined;
+	if (selectorFlag !== undefined && sub !== "list") {
+		throw new CentrsError({
+			code: "input/invalid-command",
+			summary: `\`${selectorFlag}\` is not supported by \`centrs devices ${sub}\`.`,
+			remediation:
+				"`--where`/`--near`/`--bbox` select records for `centrs devices list`. For `add`/`set`, name the `<target>` directly.",
+			context: { subcommand: sub, flag: selectorFlag },
+		});
+	}
+	const geoFlag =
+		parsed.lat !== undefined
+			? "--lat"
+			: parsed.lon !== undefined
+				? "--lon"
+				: parsed.altitude !== undefined
+					? "--altitude"
+					: parsed.altitudeType !== undefined
+						? "--altitude-type"
+						: parsed.gps !== undefined
+							? "--gps"
+							: undefined;
+	if (geoFlag !== undefined && sub !== "add" && sub !== "set") {
+		throw new CentrsError({
+			code: "input/invalid-command",
+			summary: `GPS flag \`${geoFlag}\` is not supported by \`centrs devices ${sub}\`.`,
+			remediation:
+				"Store GPS with `centrs devices add`/`set` (e.g. `--gps <lat>,<lon>`); query it with `centrs devices list --where lat=…` / `--near`.",
+			context: { subcommand: sub, flag: geoFlag },
+		});
+	}
+
 	if (sub === "show" || sub === "edit" || sub === "remove") {
 		if (rest.length !== 1) {
 			throw new Error(
@@ -324,6 +469,32 @@ function parseDevicesCliArgs(args: readonly string[]): DevicesCliArgs {
 	return parsed;
 }
 
+/**
+ * Parse a `--where attr=value` token for `devices list` (constitution: target
+ * selection grammar). Mirrors `src/cli/selection.ts` `parseWhereClause`: a
+ * structured `input/invalid-command` (not a bare `Error`) so the surfaced error
+ * keeps its remediation/context, consistent with every other CLI surface. Geo
+ * alias canonicalization (`latitude=`→`lat=`) is NOT done here — it happens once,
+ * centrally, in `matchesWhere` (`src/resolver/facts.ts`), so `devices list` and
+ * every fan-out command's `--where` behave identically.
+ */
+function parseWhereClause(token: string): DevicesWhereClause {
+	const eq = token.indexOf("=");
+	if (eq <= 0) {
+		throw new CentrsError({
+			code: "input/invalid-command",
+			summary: `--where must be \`<attr>=<value>\`; received: ${token}`,
+			remediation:
+				"Pass a device-class selector like `--where board=RB5009` (matches a CDB fact or core field).",
+			context: { where: token },
+		});
+	}
+	return {
+		key: token.slice(0, eq),
+		value: token.slice(eq + 1),
+	};
+}
+
 function parseKvArg(token: string): CommentKvUpdate {
 	const eq = token.indexOf("=");
 	if (eq <= 0) {
@@ -331,7 +502,51 @@ function parseKvArg(token: string): CommentKvUpdate {
 			`Invalid kv override "${token}"; expected key=value (use key= to clear a value).`,
 		);
 	}
-	return { key: token.slice(0, eq), value: parseKvValue(token.slice(eq + 1)) };
+	// Alias canonicalization happens in ONE place (`canonicalizeGeoKey`) so a
+	// bare `lng=…`/`latitude=…`/`elevation=…` positional lands under the same
+	// 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)) };
+}
+
+/**
+ * Lower the per-device GPS flags (`--lat`/`--lon`/`--altitude`/
+ * `--altitude-type` and their aliases, plus the combined `--gps`) into
+ * comment-kv updates. These are CLI conveniences only — no new first-class CDB
+ * tag — so they merge into the same `CommentKvUpdate[]` as bare `k=v`
+ * positionals; range/enum/pairing validation happens once, in
+ * `validateCommentKvUpdates` (`src/devices.ts`), regardless of which flag
+ * produced the update. `--gps` is expanded first so a discrete `--lat`/`--lon`/
+ * `--altitude`/`--altitude-type` flag passed alongside it wins (applied later
+ * in the array).
+ */
+function buildGeoUpdates(parsed: DevicesCliArgs): CommentKvUpdate[] {
+	const updates: CommentKvUpdate[] = [];
+	if (parsed.gps !== undefined) {
+		const gps = parseGpsTuple(parsed.gps);
+		updates.push({ key: "lat", value: gps.raw.lat });
+		updates.push({ key: "lon", value: gps.raw.lon });
+		if (gps.raw.altitude !== undefined) {
+			updates.push({ key: "altitude", value: gps.raw.altitude });
+		}
+		if (gps.raw.altitudeType !== undefined) {
+			updates.push({ key: "altitude-type", value: gps.raw.altitudeType });
+		}
+	}
+	if (parsed.lat !== undefined) {
+		updates.push({ key: "lat", value: parsed.lat });
+	}
+	if (parsed.lon !== undefined) {
+		updates.push({ key: "lon", value: parsed.lon });
+	}
+	if (parsed.altitude !== undefined) {
+		updates.push({ key: "altitude", value: parsed.altitude });
+	}
+	if (parsed.altitudeType !== undefined) {
+		updates.push({ key: "altitude-type", value: parsed.altitudeType });
+	}
+	return updates;
 }
 
 function parseKvValue(value: string): string {
@@ -400,7 +615,13 @@ export async function runDevicesCli(args: readonly string[]): Promise<number> {
 		let envelope: DevicesEnvelope<unknown>;
 		switch (parsed.subcommand) {
 			case "list":
-				envelope = listDevices({ cdb, group: parsed.group });
+				envelope = listDevices({
+					cdb,
+					group: parsed.group,
+					where: (parsed.where ?? []).map(parseWhereClause),
+					near: parsed.near,
+					bbox: parsed.bbox,
+				});
 				break;
 			case "show":
 				if (!parsed.target) {
@@ -441,7 +662,10 @@ export async function runDevicesCli(args: readonly string[]): Promise<number> {
 					profile: resolveProfile(parsed),
 					session: parsed.session,
 					comment: parsed.comment,
-					commentKvUpdates: (parsed.kvArgs ?? []).map(parseKvArg),
+					commentKvUpdates: [
+						...buildGeoUpdates(parsed),
+						...(parsed.kvArgs ?? []).map(parseKvArg),
+					],
 					force: parsed.force,
 					strict: parsed.strict,
 				});
@@ -459,7 +683,10 @@ export async function runDevicesCli(args: readonly string[]): Promise<number> {
 					cdb,
 					target: parsed.target,
 					match: parsed.match,
-					updates: (parsed.kvArgs ?? []).map(parseKvArg),
+					updates: [
+						...buildGeoUpdates(parsed),
+						...(parsed.kvArgs ?? []).map(parseKvArg),
+					],
 					user: parsed.user,
 					password: parsed.password,
 					group: parsed.group,
@@ -506,8 +733,10 @@ export async function runDevicesCli(args: readonly string[]): Promise<number> {
 			centrsError,
 		);
 		if (format === "json" || format === "yaml") {
+			// codeql[js/clear-text-logging] password reaches here only as SettingSource provenance ({kind,key}), never the value — see CommonSettingsMeta.password in src/core/envelope.ts.
 			console.error(renderDevicesEnvelope(envelope, format));
 		} else {
+			// codeql[js/clear-text-logging] password reaches here only as SettingSource provenance ({kind,key}), never the value — see CommonSettingsMeta.password in src/core/envelope.ts.
 			console.error(formatCentrsErrorText(centrsError));
 		}
 		return 1;

package/src/cli/discover.ts

@@ -20,6 +20,7 @@ import {
 	type CliCommandMetadata,
 	expectValue,
 	renderCommandHelp,
+	unknownFlagError,
 } from "./common.ts";
 
 export const discoverCommand: CliCommandMetadata = {
@@ -134,7 +135,7 @@ function parseDiscoverCliArgs(args: readonly string[]): DiscoverCliArgs {
 				break;
 			default:
 				if (arg.startsWith("-")) {
-					throw new Error(`Unknown discover flag: ${arg}`);
+					throw unknownFlagError("discover", arg, discoverCommand.options);
 				}
 				throw new Error(
 					`\`centrs discover\` does not accept positional arguments; got: ${arg}.`,
@@ -206,6 +207,7 @@ export async function runDiscoverCli(args: readonly string[]): Promise<number> {
 			remediation:
 				"Use `centrs discover --help` to inspect the supported flags.",
 		});
+		// codeql[js/clear-text-logging] password reaches here only as SettingSource provenance ({kind,key}), never the value — see CommonSettingsMeta.password in src/core/envelope.ts.
 		console.error(formatCentrsErrorText(centrsError));
 		return 1;
 	}

package/src/cli/execute.ts

@@ -1,3 +1,4 @@
+import { fanoutExitCode } from "../core/fanout.ts";
 import { asCentrsError, formatCentrsErrorText } from "../errors.ts";
 import {
 	buildExecuteErrorEnvelope,
@@ -7,11 +8,17 @@ import {
 	executeOutputFormats,
 	renderExecuteEnvelope,
 } from "../execute.ts";
+import {
+	buildExecuteFanoutErrorEnvelope,
+	executeFanout,
+	renderExecuteFanoutEnvelope,
+} from "../execute-fanout.ts";
 import { describeCentrs } from "../index.ts";
 import {
 	type CliCommandMetadata,
 	expectValue,
 	renderCommandHelp,
+	unknownFlagError,
 } from "./common.ts";
 import {
 	buildTargetSelectionTips,
@@ -21,10 +28,19 @@ import {
 	missingTargetError,
 	withTips,
 } from "./missing-target.ts";
+import {
+	buildTargetSelection,
+	consumeSelectionFlag,
+	emptySelectionFlags,
+	isFanoutMode,
+	type SelectionFlags,
+	selectionCommandOptions,
+} from "./selection.ts";
 
 export const executeCommand: CliCommandMetadata = {
 	name: "execute",
-	usage: "centrs execute <target> <command> [flags]",
+	usage:
+		"centrs execute <target> <command> [flags] | centrs execute <target...> -- <command> [flags] | centrs execute --group <name> <command> [flags]",
 	summary:
 		"Run a RouterOS read or write command via native API, REST, or mac-telnet.",
 	options: [
@@ -34,6 +50,7 @@ export const executeCommand: CliCommandMetadata = {
 			description:
 				"Pin the protocol selector; no silent downgrade when set. A bare MAC target defaults to mac-telnet.",
 		},
+		...selectionCommandOptions,
 		{
 			flag: "--host",
 			valueName: "<host|url>",
@@ -127,11 +144,15 @@ export const executeCommand: CliCommandMetadata = {
 interface ExecuteCliArgs extends ExecuteRequest {
 	help?: boolean;
 	format?: ExecuteOutputFormat;
+	selectionFlags?: SelectionFlags;
+	targetPositionals?: readonly string[];
 }
 
 export function parseExecuteCliArgs(args: readonly string[]): ExecuteCliArgs {
 	const parsed: ExecuteCliArgs = { command: "" };
+	const selectionFlags = emptySelectionFlags();
 	const positional: string[] = [];
+	const afterDashDash: string[] = [];
 	let endOfOptions = false;
 
 	for (let index = 0; index < args.length; index += 1) {
@@ -144,7 +165,7 @@ export function parseExecuteCliArgs(args: readonly string[]): ExecuteCliArgs {
 		// tokens like `--` / `-foo` (or a value that looks like a flag) without the
 		// parser claiming them. `--` itself is consumed, not added to the command.
 		if (endOfOptions) {
-			positional.push(arg);
+			afterDashDash.push(arg);
 			continue;
 		}
 		if (arg === "--") {
@@ -226,17 +247,42 @@ export function parseExecuteCliArgs(args: readonly string[]): ExecuteCliArgs {
 				parsed.format = value as ExecuteOutputFormat;
 				break;
 			}
-			default:
+			default: {
+				const consumed = consumeSelectionFlag(args, index, selectionFlags);
+				if (consumed !== null) {
+					index = consumed;
+					break;
+				}
 				if (arg.startsWith("-")) {
-					throw new Error(`Unknown execute flag: ${arg}`);
+					throw unknownFlagError("execute", arg, executeCommand.options);
 				}
 				positional.push(arg);
 				break;
+			}
 		}
 	}
 
-	parsed.targetInput = positional[0];
-	parsed.command = positional.slice(1).join(" ");
+	parsed.selectionFlags = selectionFlags;
+	// Positional boundary for execute (see `docs/CONSTITUTION.md` → Target selection):
+	//   - `--` present: targets are the positionals BEFORE it, command is AFTER it.
+	//   - selector flag present, no `--`: every positional is the command (targets
+	//     come from the selector).
+	//   - otherwise (no `--`, no selector): legacy single-target split — first
+	//     positional is the target, the rest is the command. Multiple positional
+	//     targets therefore REQUIRE `--`.
+	const hasSelector = isFanoutMode(selectionFlags, 0);
+	if (endOfOptions) {
+		parsed.targetPositionals = positional;
+		parsed.command = afterDashDash.join(" ");
+	} else if (hasSelector) {
+		parsed.targetPositionals = [];
+		parsed.command = positional.join(" ");
+	} else {
+		parsed.targetPositionals =
+			positional[0] !== undefined ? [positional[0]] : [];
+		parsed.command = positional.slice(1).join(" ");
+	}
+	parsed.targetInput = parsed.targetPositionals[0];
 	parsed.stdinIsTty = process.stdin.isTTY;
 	return parsed;
 }
@@ -249,6 +295,20 @@ export async function runExecuteCli(args: readonly string[]): Promise<number> {
 			console.log(renderCommandHelp(describeCentrs(), executeCommand));
 			return 0;
 		}
+
+		// Fan-out mode (a selector flag, or >1 positional target before `--`) has its
+		// own envelope shape, single up-front write-confirm, and granular exit code.
+		const selectionFlags = parsed.selectionFlags ?? emptySelectionFlags();
+		const targetPositionals = parsed.targetPositionals ?? [];
+		if (isFanoutMode(selectionFlags, targetPositionals.length)) {
+			return await runExecuteFanoutCli(
+				parsed,
+				selectionFlags,
+				targetPositionals,
+				args,
+			);
+		}
+
 		// No positional at all: lead with the missing-target guidance (CDB picker /
 		// discover) rather than the missing-command error — there is nothing to run
 		// without a device. A lone positional is treated as the target, so the
@@ -296,12 +356,14 @@ export async function runExecuteCli(args: readonly string[]): Promise<number> {
 				tips,
 			);
 			console.error(
+				// codeql[js/clear-text-logging] No secret reaches this sink. The tainted 'password' flows in only as provenance (SettingSource={kind,key}), never the value — see CommonSettingsMeta.password in src/core/envelope.ts.
 				renderExecuteEnvelope(envelope, format, {
 					verbose: parsed?.verbose ?? false,
 				}),
 			);
 		} else {
 			console.error(
+				// codeql[js/clear-text-logging] Same false-positive pattern: password parsed from args never reaches error.message in the text-format catch path.
 				formatCentrsErrorText(
 					asCentrsError(error, {
 						code: "input/invalid-command",
@@ -317,6 +379,45 @@ export async function runExecuteCli(args: readonly string[]): Promise<number> {
 	}
 }
 
+async function runExecuteFanoutCli(
+	parsed: ExecuteCliArgs,
+	selectionFlags: SelectionFlags,
+	targetPositionals: readonly string[],
+	args: readonly string[],
+): Promise<number> {
+	const selection = buildTargetSelection(selectionFlags, targetPositionals);
+	const format = inferExecuteFormat(args, parsed);
+	try {
+		const envelope = await executeFanout(
+			parsed,
+			selection,
+			Bun.env,
+			{},
+			{
+				concurrency: selectionFlags.concurrency,
+				allowAdhoc: true,
+			},
+		);
+		const resolvedFormat = envelope.meta.operation?.request.format ?? format;
+		console.log(
+			renderExecuteFanoutEnvelope(envelope, resolvedFormat, {
+				verbose: parsed.verbose ?? false,
+			}),
+		);
+		// Granular exit contract: 0 all-ok / 2 partial / 1 all-failed.
+		return fanoutExitCode(envelope);
+	} catch (error) {
+		const envelope = buildExecuteFanoutErrorEnvelope(parsed, error);
+		console.error(
+			// codeql[js/clear-text-logging] Twin of #80/#81/#83/#84. No secret logged: buildExecuteFanoutErrorEnvelope meta is {target:{},via,settings:{}}; CodeQL taints the whole request object but the builder projects the password away.
+			renderExecuteFanoutEnvelope(envelope, format, {
+				verbose: parsed.verbose ?? false,
+			}),
+		);
+		return 1;
+	}
+}
+
 function inferExecuteFormat(
 	args: readonly string[],
 	parsed?: ExecuteCliArgs,

package/src/cli/mcp.ts

@@ -11,10 +11,12 @@ import { asCentrsError, formatCentrsErrorText } from "../errors.ts";
 import { describeCentrs } from "../index.ts";
 import { resolveMcpConfig } from "../mcp/config.ts";
 import { runMcpStdio } from "../mcp/server.ts";
+import { loadEnvFileDefaults } from "../resolver/index.ts";
 import {
 	type CliCommandMetadata,
 	expectValue,
 	renderCommandHelp,
+	unknownFlagError,
 } from "./common.ts";
 
 export const mcpCommand: CliCommandMetadata = {
@@ -55,6 +57,9 @@ export function parseMcpCliArgs(args: readonly string[]): McpCliArgs {
 	const parsed: McpCliArgs = {};
 	for (let index = 0; index < args.length; index += 1) {
 		const arg = args[index];
+		if (arg === undefined) {
+			continue;
+		}
 		switch (arg) {
 			case "start":
 				// Optional verb; `centrs mcp` and `centrs mcp start` are equivalent.
@@ -73,7 +78,7 @@ export function parseMcpCliArgs(args: readonly string[]): McpCliArgs {
 				parsed.allowAdhocTargets = true;
 				break;
 			default:
-				throw new Error(`Unknown flag for centrs mcp: ${arg}`);
+				throw unknownFlagError("mcp", arg, mcpCommand.options);
 		}
 	}
 	return parsed;
@@ -90,11 +95,13 @@ export async function runMcpCli(args: readonly string[]): Promise<number> {
 			cdbFile: parsed.cdbFile,
 			cdbPassword: parsed.cdbPassword,
 			allowAdhocTargets: parsed.allowAdhocTargets,
+			config: await loadEnvFileDefaults(),
 		});
 		await runMcpStdio(config);
 		return 0;
 	} catch (error) {
 		console.error(
+			// codeql[js/clear-text-logging] password reaches here only as SettingSource provenance ({kind,key}), never the value — see CommonSettingsMeta.password in src/core/envelope.ts.
 			formatCentrsErrorText(
 				asCentrsError(error, {
 					code: "internal/mcp-start",