@tikoci/quickchr 0.4.7 → 0.5.0

package/src/cli/index.ts

@@ -3,22 +3,43 @@
  * quickchr CLI entry point — command router.
  */
 
-import type { StartOptions, Arch, Channel, ServiceName, NetworkSpecifier } from "../lib/types.ts";
+import type { StartOptions, Arch, Channel, DeviceModeOptions, ServiceName, NetworkSpecifier } from "../lib/types.ts";
 import { parseNetworkSpecifier } from "../lib/network.ts";
 import { expandForwardSpec } from "../lib/forward-spec.ts";
+import { ADD_FLAGS, REMOVED_FLAGS, SET_FLAGS, START_FLAGS, VALUE_FLAGS, unknownFlags, unknownFlagMessage, valuelessFlags, valuelessFlagMessage } from "./flags.ts";
+import { QuickCHRError } from "../lib/types.ts";
+import { CENTRS_EXEC_TIP, CENTRS_SEE_ALSO, tip, tipsForError } from "./tips.ts";
 import {
+	isRouterOs6,
 	MIN_PROVISION_VERSION,
 	PROVISIONING_BOOT_ONLY_SUMMARY,
 	PROVISIONING_FEATURE_SUMMARY,
 	provisioningSupportHint,
 	provisioningSupportSummary,
+	ROUTEROS6_BOOT_ONLY,
 } from "../lib/versions.ts";
 
 const args = process.argv.slice(2);
 const command = args[0];
 
-/** Parse --flag=value and --flag value pairs from args. */
-export function parseFlags(argv: string[]): { flags: Record<string, string | boolean | string[]>; positional: string[] } {
+/** Stop a removed flag at the parser, naming what replaced it. Thrown rather than
+ *  printed so it reaches `main()`'s handler like any other error, and so no command can
+ *  reach a state where the flag was accepted and ignored (#164). */
+function rejectRemovedFlag(key: string): void {
+	const replacement = REMOVED_FLAGS.get(key);
+	if (replacement === undefined) return;
+	throw new QuickCHRError("INVALID_ARGUMENT", `--${key} was removed. Use: ${replacement}`);
+}
+
+/** Parse --flag=value and --flag value pairs from args.
+ *
+ *  Arity comes from `VALUE_FLAGS`, never from the shape of the next argument: a flag
+ *  that is not in that table is boolean and leaves the following argument alone, so a
+ *  positional cannot be eaten by a flag that has no use for it (#164). */
+export function parseFlags(
+	argv: string[],
+	valueFlags: ReadonlySet<string> = VALUE_FLAGS,
+): { flags: Record<string, string | boolean | string[]>; positional: string[] } {
 	const flags: Record<string, string | boolean | string[]> = {};
 	const positional: string[] = [];
 
@@ -33,13 +54,16 @@ export function parseFlags(argv: string[]): { flags: Record<string, string | boo
 			const eqIdx = arg.indexOf("=");
 			if (eqIdx !== -1) {
 				const key = arg.slice(2, eqIdx);
+				rejectRemovedFlag(key);
 				flags[key] = arg.slice(eqIdx + 1);
 			} else if (arg.startsWith("--no-")) {
+				rejectRemovedFlag(arg.slice(5));
 				flags[arg.slice(5)] = false;
 			} else {
 				const key = arg.slice(2);
+				rejectRemovedFlag(key);
 				const next = argv[i + 1];
-				if (next && !next.startsWith("--")) {
+				if (valueFlags.has(key) && next !== undefined && !next.startsWith("--")) {
 					// Check if this is a repeatable flag
 					const existing = flags[key];
 					if (Array.isArray(existing)) {
@@ -68,10 +92,33 @@ function flag(flags: Record<string, string | boolean | string[]>, key: string):
 	return undefined;
 }
 
+function cacheTargetFlag(flags: Record<string, string | boolean | string[]>, key: string): string | undefined {
+	if (!(key in flags)) return undefined;
+	const value = flags[key];
+	if (typeof value !== "string" || value.length === 0) {
+		throw new Error(`--${key} requires a value`);
+	}
+	return value;
+}
+
 function flagBool(flags: Record<string, string | boolean | string[]>, key: string): boolean {
 	return flags[key] === true || flags[key] === "true";
 }
 
+/** A boolean flag that keeps "not given" apart from `--no-<key>`: `true`, `false`, or
+ *  `undefined` when the flag is absent.
+ *
+ *  `flagBool()` collapses absent into `false`, and that is the wrong answer for any
+ *  option `start()` merges with stored intent (`opts.x ?? existing.x`): `false ?? true`
+ *  is `false`, so `quickchr add --install-all-packages` followed by a plain
+ *  `quickchr start <name>` booted without the packages and said nothing (#185). Same
+ *  rule as `--no-device-mode`: silence and refusal are different instructions, and only
+ *  silence may fall through to what `add` recorded. */
+export function flagOptionalBool(flags: Record<string, string | boolean | string[]>, key: string): boolean | undefined {
+	if (flags[key] === undefined) return undefined;
+	return flags[key] !== false && flags[key] !== "false";
+}
+
 function flagList(flags: Record<string, string | boolean | string[]>, key: string): string[] {
 	const val = flags[key];
 	if (Array.isArray(val)) return val;
@@ -83,20 +130,53 @@ function csvList(values: string[]): string[] {
 	return [...new Set(values.flatMap((value) => value.split(",")).map((value) => value.trim()).filter(Boolean))];
 }
 
-/** Build networks array from --add-network, --no-network, and legacy vmnet flags. */
-function buildNetworks(flags: Record<string, string | boolean | string[]>): NetworkSpecifier[] | undefined {
-	const specs: NetworkSpecifier[] = [];
+/** The device-mode request the `--device-mode*` flags describe, or `undefined` when
+ *  they describe nothing.
+ *
+ *  One reader for all three verbs that take these flags. `add` and `start` had
+ *  separate copies and they had already drifted: only `start` honoured
+ *  `--no-device-mode`, so `quickchr add --no-device-mode --device-mode-enable container`
+ *  enabled container while the same flags on `start` skipped device-mode with a
+ *  warning. Two spellings of one intent producing opposite results is the silent-drop
+ *  failure in another costume (#176).
+ *
+ *  `--no-device-mode` means *skip device-mode entirely*, so it wins over the feature
+ *  lists and says so rather than quietly discarding them.
+ *
+ *  It returns an explicit `{ mode: "skip" }` rather than `undefined`, because
+ *  `undefined` means *the user said nothing* and the two are not the same instruction.
+ *  `start()` resolves a silent request against stored intent — `opts.deviceMode ??
+ *  existing.deviceMode` — so a machine created with `add --device-mode-enable
+ *  container` and then started with `--no-device-mode` provisioned container anyway,
+ *  power cycle included. Measured on CHR 7.24.4: 48 s and `container=yes`, from a flag
+ *  whose documented job is to skip the step. A flag that is accepted and does nothing
+ *  is the defect this whole area exists to remove (#176). */
+export function deviceModeFromFlags(
+	flags: Record<string, string | boolean | string[]>,
+): DeviceModeOptions | undefined {
+	const mode = flag(flags, "device-mode");
+	const enable = csvList(flagList(flags, "device-mode-enable"));
+	const disable = csvList(flagList(flags, "device-mode-disable"));
 
-	// Legacy flags first
-	if (flag(flags, "vmnet-shared") !== undefined) {
-		specs.push(parseNetworkSpecifier("shared"));
-	}
-	const bridgeIface = flag(flags, "vmnet-bridge");
-	if (bridgeIface) {
-		specs.push(parseNetworkSpecifier(`bridged:${bridgeIface}`));
+	if (flags["device-mode"] === false) {
+		if (enable.length > 0 || disable.length > 0) {
+			console.warn("Warning: --device-mode-enable/--device-mode-disable ignored because --no-device-mode was set.");
+		}
+		return { mode: "skip" };
 	}
+	if (mode === undefined && enable.length === 0 && disable.length === 0) return undefined;
+
+	return {
+		mode: mode ?? "auto",
+		enable: enable.length > 0 ? enable : undefined,
+		disable: disable.length > 0 ? disable : undefined,
+	};
+}
+
+/** Build networks array from --add-network and --no-network. */
+function buildNetworks(flags: Record<string, string | boolean | string[]>): NetworkSpecifier[] | undefined {
+	const specs: NetworkSpecifier[] = [];
 
-	// New --add-network flags
 	for (const raw of flagList(flags, "add-network")) {
 		specs.push(parseNetworkSpecifier(raw));
 	}
@@ -111,6 +191,28 @@ function buildNetworks(flags: Record<string, string | boolean | string[]>): Netw
 	return specs;
 }
 
+/** Exit with a flag-list error when a machine-creating command is given a flag it does
+ *  not know. An unrecognised flag is a typo, and a typo that downloads 43 MB and creates
+ *  a machine is not a good default (#156). */
+function rejectUnknownFlags(
+	flags: Record<string, string | boolean | string[]>,
+	known: readonly string[],
+	command: string,
+): void {
+	const unknown = unknownFlags(flags, known);
+	if (unknown.length > 0) {
+		console.error(unknownFlagMessage(unknown, command));
+		process.exit(1);
+	}
+	// A known flag given without its value is the same hazard wearing a valid name:
+	// `add --name --version 7.24.3` would otherwise create an auto-named machine.
+	const valueless = valuelessFlags(flags, known);
+	if (valueless.length > 0) {
+		console.error(valuelessFlagMessage(valueless, command));
+		process.exit(1);
+	}
+}
+
 /** True when interactive prompts must be suppressed (e.g. LLM / CI / pipe). */
 function isNoPrompt(): boolean {
 	return !!process.env.QUICKCHR_NO_PROMPT || !process.stdout.isTTY || !process.stdin.isTTY;
@@ -179,16 +281,55 @@ export async function applyAccelFlag(flags: Record<string, string | boolean | st
 
 /** Resolve --secure-login/--no-secure-login, falling back to the secure-login setting
  *  only when neither flag was passed. Shared by cmdAdd, cmdStart, and cmdStart's
- *  --all bulk-restart path. */
-export async function resolveSecureLoginFlag(flags: Record<string, string | boolean | string[]>): Promise<boolean | undefined> {
+ *  --all bulk-restart path.
+ *
+ *  `applySetting` is **required**, and deliberately so. The setting is a *first-boot*
+ *  default: carrying it into the start of a machine whose provisioning window has
+ *  closed turns `quickchr start <name>` — and every such machine in `start --all` —
+ *  into a request to provision a booted guest, which now refuses out loud (#176).
+ *  Callers pass the target's own window state, not "does this machine exist": a
+ *  machine that was `add`ed and never started is still on its first boot and keeps
+ *  the setting. An explicit flag always wins over both.
+ *
+ *  Making the argument required is the guard. An earlier pass left `cmdStart`'s
+ *  single-target call on the defaulted form while believing it had been updated, so
+ *  the restart regression stayed live behind a fix that had landed in `cmdAdd`
+ *  instead. A missing argument is now a type error rather than a silent default. */
+export async function resolveSecureLoginFlag(
+	flags: Record<string, string | boolean | string[]>,
+	applySetting: boolean,
+): Promise<boolean | undefined> {
 	if (flags["secure-login"] === false) return false;
 	if (flagBool(flags, "secure-login")) return true;
+	if (!applySetting) return undefined;
 	const { resolveSetting } = await import("../lib/settings.ts");
 	return resolveSetting("secure-login").value === true ? true : undefined;
 }
 
+/** True when the user asked for help on this subcommand.
+ *
+ *  `--help` used to reach subcommands as an ordinary argument: `add --help` generated a
+ *  name and downloaded 43 MB, and `networks sockets create --help` persisted a socket
+ *  called `--help` (#156). Handling it here — before the dispatch — means a new
+ *  subcommand cannot miss the guard.
+ *
+ *  Everything after a bare `--` is the user's payload (a RouterOS command for `exec`),
+ *  so the scan stops there. */
+function wantsCommandHelp(argv: string[]): boolean {
+	for (const arg of argv) {
+		if (arg === "--") return false;
+		if (arg === "--help" || arg === "-h") return true;
+	}
+	return false;
+}
+
 async function main() {
 	try {
+		// Help before side effects — for every subcommand, present and future (#156).
+		if (command !== undefined && !command.startsWith("-") && wantsCommandHelp(args.slice(1))) {
+			printHelp(command);
+			return;
+		}
 		switch (command) {
 			case "add":
 				await cmdAdd(args.slice(1));
@@ -199,6 +340,9 @@ async function main() {
 			case "stop":
 				await cmdStop(args.slice(1));
 				break;
+			case "shutdown":
+				await cmdShutdown(args.slice(1));
+				break;
 			case "list":
 			case "ls":
 			case "status":
@@ -294,7 +438,10 @@ async function main() {
 			if (err.installHint) {
 				console.error(`  Hint: ${err.installHint}`);
 			}
-			if (err.code === "PROVISIONING_VERSION_UNSUPPORTED") {
+			for (const line of tipsForError(err.code, command)) tip(line);
+			// The 7.x baseline explanation; a RouterOS 6 refusal already says why, and
+			// "for older 7.x" would point a 6.x user at the wrong fix.
+			if (err.code === "PROVISIONING_VERSION_UNSUPPORTED" && !err.message.includes(ROUTEROS6_BOOT_ONLY)) {
 				console.error(`  Why this happened: ${provisioningSupportSummary(MIN_PROVISION_VERSION)}`);
 				console.error(`  ${PROVISIONING_BOOT_ONLY_SUMMARY}`);
 				console.error("  Try this:");
@@ -309,6 +456,12 @@ async function main() {
 
 // --- Commands ---
 
+/** RouterOS 6 in `add`/`start --help` (#182): what it is for, and what it is not. */
+const ROUTEROS6_HELP = `RouterOS 6.x is a best-effort boot-only target (x86 only): quickchr downloads,
+boots and tracks it, and reports its ports and login. It is there for testing v6→v7
+migration tooling, not as supported RouterOS. Readiness is a native-API login, every
+provisioning flag is refused, and REST-based commands (exec, get, set) say so.`;
+
 /** Print QEMU keyboard shortcuts before foreground launch. Screen clears after QEMU starts. */
 function printForegroundTips(hasProvisioning = false) {
 	const bold = (s: string) => `\x1b[1m${s}\x1b[0m`;
@@ -552,6 +705,7 @@ function printMachineListWithTip(
 
 async function cmdAdd(argv: string[]) {
 	const { flags, positional } = parseFlags(argv);
+	rejectUnknownFlags(flags, ADD_FLAGS, "add");
 	const { QuickCHR } = await import("../lib/quickchr.ts");
 	const { bold, formatPorts, formatNetworks, dim } = await import("./format.ts");
 	const { resolveSetting } = await import("../lib/settings.ts");
@@ -559,13 +713,15 @@ async function cmdAdd(argv: string[]) {
 
 	const opts: StartOptions = {
 		version: flag(flags, "version"),
-		channel: (flag(flags, "channel") as Channel | undefined) ?? (resolveSetting("default-channel").value as Channel | undefined),
+		// The default channel only stands in for a missing --version; applied alongside
+		// one, it reads to start()/add() as a caller passing both (#178).
+		channel: (flag(flags, "channel") as Channel | undefined) ?? (flag(flags, "version") ? undefined : resolveSetting("default-channel").value as Channel | undefined),
 		arch: (flag(flags, "arch") as Arch | "auto" | undefined) ?? (resolveSetting("default-arch").value as Arch | "auto" | undefined),
 		name: flag(flags, "name") ?? positional[0],
 		cpu: flag(flags, "cpu") ? Number(flag(flags, "cpu")) : undefined,
 		mem: flag(flags, "mem") ? Number(flag(flags, "mem")) : undefined,
 		packages: csvList(flagList(flags, "add-package")),
-		installAllPackages: flagBool(flags, "install-all-packages"),
+		installAllPackages: flagOptionalBool(flags, "install-all-packages"),
 		portBase: flag(flags, "port-base") ? Number(flag(flags, "port-base")) : undefined,
 		excludePorts: [
 			...(flags.winbox === false ? ["winbox" as ServiceName] : []),
@@ -578,24 +734,18 @@ async function cmdAdd(argv: string[]) {
 		extraPorts: flagList(flags, "forward").flatMap(expandForwardSpec),
 	};
 
-	const deviceModeValue = flag(flags, "device-mode");
-	const deviceModeEnable = csvList(flagList(flags, "device-mode-enable"));
-	const deviceModeDisable = csvList(flagList(flags, "device-mode-disable"));
-	if (deviceModeValue !== undefined || deviceModeEnable.length > 0 || deviceModeDisable.length > 0) {
-		opts.deviceMode = {
-			mode: deviceModeValue ?? "auto",
-			enable: deviceModeEnable.length > 0 ? deviceModeEnable : undefined,
-			disable: deviceModeDisable.length > 0 ? deviceModeDisable : undefined,
-		};
-	}
+	opts.deviceMode = deviceModeFromFlags(flags);
 
 	const userStr = flag(flags, "add-user");
 	if (userStr) {
 		const [uname = "", password] = userStr.split(":");
 		opts.user = { name: uname, password: password ?? "" };
 	}
-	opts.disableAdmin = flagBool(flags, "disable-admin");
-	opts.secureLogin = await resolveSecureLoginFlag(flags);
+	opts.disableAdmin = flagOptionalBool(flags, "disable-admin");
+	// `add` always creates a machine, so its provisioning window is open by definition.
+	// A RouterOS 6 machine takes no provisioning at all, so the setting — a default, not
+	// a request — stays out of it; only an explicit --secure-login is refused.
+	opts.secureLogin = await resolveSecureLoginFlag(flags, !isRouterOs6(opts.version ?? ""));
 
 	const state = await QuickCHR.add(opts);
 
@@ -606,10 +756,26 @@ async function cmdAdd(argv: string[]) {
 	console.log(`  CPU/Mem: ${state.cpu} vCPU${state.cpu > 1 ? "s" : ""}, ${state.mem} MB`);
 	console.log(`  Network: ${formatNetworks(state.networks ?? [])}`);
 	console.log(`  Ports:   ${formatPorts(state.ports)}`);
-	console.log(`  REST:    http://127.0.0.1:${ports.http}  ${dim("(after start)")}`);
+	if (isRouterOs6(state.version)) {
+		console.log(`  API:     127.0.0.1:${ports.api}  ${dim("(after start; RouterOS 6 is boot-only and has no REST)")}`);
+	} else {
+		console.log(`  REST:    http://127.0.0.1:${ports.http}  ${dim("(after start)")}`);
+	}
 	console.log(`  Dir:     ${dim(state.machineDir)}`);
-	if (state.packages.length > 0) console.log(`  Packages: ${state.packages.join(", ")}  ${dim("(applied on first start)")}`);
-	if (state.deviceMode) console.log(`  Device-mode: ${state.deviceMode.mode ?? "auto"}  ${dim("(applied on first start)")}`);
+	if (state.installAllPackages) console.log(`  Packages: all extra packages  ${dim("(applied on first start)")}`);
+	else if (state.packages.length > 0) console.log(`  Packages: ${state.packages.join(", ")}  ${dim("(applied on first start)")}`);
+	const login = [
+		...(state.user ? [`add user "${state.user.name}"`] : []),
+		...(state.secureLogin === true ? ["managed quickchr account"] : []),
+		...(state.disableAdmin ? ["disable admin"] : []),
+	];
+	if (login.length > 0) console.log(`  Login:   ${login.join(", ")}  ${dim("(applied on first start)")}`);
+	if (state.deviceMode) {
+		const { shouldApplyDeviceMode: willApplyDm, resolveDeviceModeOptions: resolveDm } = await import("../lib/device-mode.ts");
+		console.log(willApplyDm(resolveDm(state.deviceMode))
+			? `  Device-mode: ${state.deviceMode.mode ?? "auto"}  ${dim("(applied on first start)")}`
+			: `  Device-mode: ${dim("skipped (--no-device-mode)")}`);
+	}
 	console.log();
 	console.log(`${dim("tip:")}  quickchr start ${state.name}`);
 }
@@ -656,6 +822,7 @@ async function cmdExec(argv: string[]) {
 		} else {
 			console.error("Usage: quickchr exec <name> <command...>\n  Run a RouterOS CLI command on a running instance.");
 		}
+		tip(CENTRS_EXEC_TIP);
 		process.exit(1);
 	}
 
@@ -1193,28 +1360,75 @@ async function cmdSetup() {
 	}
 }
 
+/** Whether the `secure-login` *setting* reaches this start. The setting is a default,
+ *  not a request, so it stays out of every start that cannot provision: a closed
+ *  window, a `--no-wait` start (#159), and a RouterOS 6 machine (#182). Otherwise a
+ *  user with `secure-login=true` configured could never use either. An explicit
+ *  `--secure-login` is still passed through, and refused by name. */
+export function secureLoginSettingApplies(
+	flags: Record<string, string | boolean | string[]>,
+	windowOpen: boolean,
+	version: string | undefined,
+): boolean {
+	return windowOpen && flags.wait !== false && !isRouterOs6(version ?? "");
+}
+
+/** `--bg` never did what it reads as (#159): background is the default, and the flag
+ *  only ever chose where the serial console went. It stays accepted so existing
+ *  scripts keep working, and says once that it does nothing. */
+function warnDeprecatedBackgroundFlag(flags: Record<string, string | boolean | string[]>): void {
+	const given = flags.bg === true ? "--bg" : flags.background === true ? "--background" : undefined;
+	if (!given) return;
+	console.error(`Warning: ${given} is deprecated and does nothing — background is already the default, and it never made start return early. Use --no-wait to return as soon as QEMU is running.`);
+}
+
+/** After a `--no-wait` start the caller owns readiness; name the command that does it. */
+function printReadinessTip(name: string, version: string): void {
+	// 6.x: native API, and no validation — centrs checks paths against the 7.x tree
+	// and rejects /system/resource on 6.49 (checked 2026-10-21).
+	const via = isRouterOs6(version) ? " --via native-api --no-validate" : "";
+	tip(`wait for readiness with: centrs retrieve --quickchr ${name} /system/resource${via} --wait 5m`);
+}
+
 async function cmdStart(argv: string[]) {
 	const { flags, positional } = parseFlags(argv);
 	applyTimeoutExtraShortFlag(argv, flags, positional);
+	rejectUnknownFlags(flags, START_FLAGS, "start");
 	// Before the --all branch: both start paths must see the same override.
 	await applyAccelFlag(flags);
+	warnDeprecatedBackgroundFlag(flags);
+	const wait = flags.wait === false ? false : undefined;
 
 	// --all: start every stopped machine in background
 	if (flagBool(flags, "all")) {
+		// Batch starts only accept options this branch actually forwards. In particular,
+		// a provisioning flag must never disappear on a --no-wait start.
+		const batchFlags = new Set(["all", "wait", "bg", "background", "accel", "timeout-extra", "secure-login"]);
+		const unsupported = Object.keys(flags).filter((key) => !batchFlags.has(key));
+		if (unsupported.length > 0 || flags.bg === false || flags.background === false) {
+			throw new QuickCHRError("INVALID_ARGUMENT", "start --all runs in background and accepts only --no-wait, --bg, --background, --accel, --timeout-extra, --secure-login and --no-secure-login. Start an individual machine to use other options.");
+		}
 		const { QuickCHR } = await import("../lib/quickchr.ts");
 		const { statusIcon, link, bold, resolveDisplayCredentials, formatRestUrl, formatSshCommand } = await import("./format.ts");
 		const timeoutExtra = await resolveTimeoutExtraMs(flags);
-		const secureLogin = await resolveSecureLoginFlag(flags);
 		const stopped = QuickCHR.list().filter((m) => m.status !== "running");
 		if (stopped.length === 0) {
 			console.log("No stopped instances.");
 			return;
 		}
+		const { isProvisioningWindowOpen } = await import("../lib/provisioning-window.ts");
 		for (const m of stopped) {
 			console.log(`Starting ${bold(m.name)}...`);
-			const instance = await QuickCHR.start({ name: m.name, background: true, timeoutExtra, secureLogin });
+			// Per machine, not per invocation: a never-started machine in this batch is
+			// still entitled to the secure-login setting on its first boot.
+			const secureLogin = await resolveSecureLoginFlag(flags, secureLoginSettingApplies(flags, isProvisioningWindowOpen(m), m.version));
+			const instance = await QuickCHR.start({ name: m.name, background: true, wait, timeoutExtra, secureLogin });
 			const creds = await resolveDisplayCredentials(instance.state);
-			console.log(`${statusIcon("running")} ${bold(instance.name)}  REST: ${link(formatRestUrl(instance.ports.http, creds.user, creds.password))}  SSH: ${formatSshCommand(creds.user, instance.sshPort)}`);
+			const endpoint = isRouterOs6(instance.state.version)
+				? `API: 127.0.0.1:${instance.ports.api}`
+				: `REST: ${link(formatRestUrl(instance.ports.http, creds.user, creds.password))}`;
+			console.log(`${statusIcon("running")} ${bold(instance.name)}  ${endpoint}  SSH: ${formatSshCommand(creds.user, instance.sshPort)}${wait === false ? "  (not waited for)" : ""}`);
+			if (wait === false) printReadinessTip(instance.name, instance.state.version);
 		}
 		return;
 	}
@@ -1241,13 +1455,15 @@ async function cmdStart(argv: string[]) {
 
 	const opts: StartOptions = {
 		version: flag(flags, "version"),
-		channel: (flag(flags, "channel") as Channel | undefined) ?? (resolveSetting("default-channel").value as Channel | undefined),
+		// The default channel only stands in for a missing --version; applied alongside
+		// one, it reads to start()/add() as a caller passing both (#178).
+		channel: (flag(flags, "channel") as Channel | undefined) ?? (flag(flags, "version") ? undefined : resolveSetting("default-channel").value as Channel | undefined),
 		arch: (flag(flags, "arch") as Arch | "auto" | undefined) ?? (resolveSetting("default-arch").value as Arch | "auto" | undefined),
 		name: flag(flags, "name") ?? positional[0],
 		cpu: flag(flags, "cpu") ? Number(flag(flags, "cpu")) : undefined,
 		mem: flag(flags, "mem") ? Number(flag(flags, "mem")) : undefined,
-		packages: flagList(flags, "add-package"),
-		installAllPackages: flagBool(flags, "install-all-packages"),
+		packages: csvList(flagList(flags, "add-package")),
+		installAllPackages: flagOptionalBool(flags, "install-all-packages"),
 		portBase: flag(flags, "port-base") ? Number(flag(flags, "port-base")) : undefined,
 		excludePorts: [
 			...(flags.winbox === false ? ["winbox" as ServiceName] : []),
@@ -1263,21 +1479,7 @@ async function cmdStart(argv: string[]) {
 		timeoutExtra: await resolveTimeoutExtraMs(flags),
 	};
 
-	const deviceModeValue = flag(flags, "device-mode");
-	const deviceModeEnable = csvList(flagList(flags, "device-mode-enable"));
-	const deviceModeDisable = csvList(flagList(flags, "device-mode-disable"));
-	const noDeviceMode = flags["device-mode"] === false;
-	if (noDeviceMode) {
-		if (deviceModeEnable.length > 0 || deviceModeDisable.length > 0) {
-			console.warn("Warning: --device-mode-enable/--device-mode-disable ignored because --no-device-mode was set.");
-		}
-	} else if (deviceModeValue !== undefined || deviceModeEnable.length > 0 || deviceModeDisable.length > 0) {
-		opts.deviceMode = {
-			mode: deviceModeValue ?? "auto",
-			enable: deviceModeEnable.length > 0 ? deviceModeEnable : undefined,
-			disable: deviceModeDisable.length > 0 ? deviceModeDisable : undefined,
-		};
-	}
+	opts.deviceMode = deviceModeFromFlags(flags);
 
 	// --license-* flags (credentials from env if not supplied)
 	const licenseLevel = flag(flags, "license-level");
@@ -1302,10 +1504,25 @@ async function cmdStart(argv: string[]) {
 		opts.user = { name, password: password ?? "" };
 	}
 
-	opts.disableAdmin = flagBool(flags, "disable-admin");
-	opts.secureLogin = await resolveSecureLoginFlag(flags);
+	opts.disableAdmin = flagOptionalBool(flags, "disable-admin");
+	{
+		const { QuickCHR } = await import("../lib/quickchr.ts");
+		const { isProvisioningWindowOpen } = await import("../lib/provisioning-window.ts");
+		const target = opts.name ? QuickCHR.get(opts.name) : null;
+		// No machine yet, or one that was added and never booted: still a first boot,
+		// so the setting applies. Only a closed window suppresses it — otherwise a
+		// plain `quickchr start <booted-name>` would ask to provision a booted guest
+		// and be refused.
+		opts.secureLogin = await resolveSecureLoginFlag(flags, secureLoginSettingApplies(
+			flags,
+			!target || isProvisioningWindowOpen(target.state),
+			target?.state.version ?? opts.version,
+		));
+	}
+	opts.wait = wait;
 
 	// Background default: true. Explicitly foreground only with --fg / --foreground / --no-background / --no-bg.
+	// `--bg` / `--background` are accepted and change nothing (see warnDeprecatedBackgroundFlag).
 	const wantFg =
 		flagBool(flags, "fg") ||
 		flagBool(flags, "foreground") ||
@@ -1318,8 +1535,9 @@ async function cmdStart(argv: string[]) {
 		return;
 	}
 
-	// --fg on already-running machine: attach to its serial console
-	if (!opts.background && opts.name) {
+	// --fg on already-running machine: attach to its serial console.
+	// `--fg --no-wait` skips both foreground blocks so start() refuses the pair before any I/O.
+	if (!opts.background && opts.wait !== false && opts.name) {
 		const runningMachine = QuickCHR.list().find((m) => m.name === opts.name && m.status === "running");
 		if (runningMachine) {
 			await attachSerial(runningMachine.name, runningMachine.machineDir);
@@ -1327,7 +1545,7 @@ async function cmdStart(argv: string[]) {
 		}
 	}
 
-	if (!opts.background) {
+	if (!opts.background && opts.wait !== false) {
 		const wantsDeviceMode = !!opts.deviceMode && !["skip", "none", "off", "disabled"].includes((opts.deviceMode.mode ?? "auto").toLowerCase());
 		const hasProv = !!(
 			opts.installAllPackages ||
@@ -1354,13 +1572,19 @@ async function cmdStart(argv: string[]) {
 		console.log(`  ${dim("Tip: run background")}   quickchr start ${instance.name}`);
 	} else {
 		const creds = await resolveDisplayCredentials(instance.state);
-		console.log(`${statusIcon("running")} ${bold(instance.name)} started`);
-		console.log(`  Version: ${instance.state.version} (${instance.state.arch})`);
+		const v6 = isRouterOs6(instance.state.version);
+		console.log(`${statusIcon("running")} ${bold(instance.name)} ${opts.wait === false ? "launched — not waiting for RouterOS (--no-wait)" : "started"}`);
+		console.log(`  Version: ${instance.state.version} (${instance.state.arch})${v6 ? `  ${dim("boot-only: no REST, no provisioning")}` : ""}`);
 		console.log(`  Network: ${formatNetworks(instance.state.networks ?? [])}`);
 		console.log(`  Ports:   ${formatPorts(instance.state.ports)}`);
-		console.log(`  REST:    ${link(formatRestUrl(instance.ports.http, creds.user, creds.password))}`);
+		if (v6) {
+			console.log(`  API:     127.0.0.1:${instance.ports.api}  ${dim(`(native API, user ${creds.user})`)}`);
+		} else {
+			console.log(`  REST:    ${link(formatRestUrl(instance.ports.http, creds.user, creds.password))}`);
+		}
 		console.log(`  SSH:     ${formatSshCommand(creds.user, instance.sshPort)}`);
 		console.log(`  WinBox:  127.0.0.1:${instance.ports.winbox}`);
+		if (opts.wait === false) printReadinessTip(instance.name, instance.state.version);
 		if (creds.user !== "admin") {
 			console.log(`  Login:   ${creds.user} / ${creds.password || "(no password)"}`);
 			console.log(`  Run:     quickchr exec ${instance.name} /system/resource/print`);
@@ -1368,6 +1592,32 @@ async function cmdStart(argv: string[]) {
 	}
 }
 
+async function cmdShutdown(argv: string[]) {
+	const { flags, positional } = parseFlags(argv);
+	const invalid = unknownFlags(flags, ["timeout"]);
+	if (invalid.length) throw new QuickCHRError("INVALID_ARGUMENT", "shutdown accepts only <name> and --timeout <seconds>");
+	if (positional.length !== 1 || positional[0] === undefined) throw new QuickCHRError("INVALID_ARGUMENT", "Usage: quickchr shutdown <name> [--timeout <seconds>]");
+	const raw = flags.timeout === undefined ? (process.env.QUICKCHR_SHUTDOWN_TIMEOUT ?? "10") : flag(flags, "timeout");
+	if (raw === undefined || !/^[0-9]+$/.test(raw) || Number(raw) <= 0) {
+		throw new QuickCHRError("INVALID_ARGUMENT", "shutdown timeout must be a positive integer number of seconds");
+	}
+	const { validateShutdownTimeout } = await import("../lib/shutdown.ts");
+	const timeoutMs = validateShutdownTimeout(Number(raw) * 1000);
+	const { QuickCHR } = await import("../lib/quickchr.ts");
+	const name = positional[0];
+	const instance = QuickCHR.get(name);
+	if (!instance) throw new QuickCHRError("MACHINE_NOT_FOUND", `Machine "${name}" not found`);
+	const result = await instance.shutdown({ timeoutMs });
+	if (result.outcome === "forced") {
+		console.log(`${name}: forced power cut — guest shutdown not confirmed`);
+		if (result.requestError) console.error(`Shutdown request: ${result.requestError}`);
+	} else if (result.outcome === "already-stopped") {
+		console.log(`${name}: already stopped`);
+	} else {
+		console.log(`${name}: guest exited after shutdown request`);
+	}
+}
+
 async function cmdStop(argv: string[]) {
 	const { flags, positional } = parseFlags(argv);
 	const { QuickCHR } = await import("../lib/quickchr.ts");
@@ -1479,8 +1729,13 @@ async function cmdList(argv: string[] = []) {
 
 	const { table, statusIcon, formatPorts, formatNetworks, dim } = await import("./format.ts");
 	const machines = QuickCHR.list();
+	// A machine whose state went bad keeps its place in the listing. It still holds a
+	// disk image, and `list` is where anyone looks first — deferring it to `doctor`
+	// assumes you already suspect trouble, which a quietly absent machine does not
+	// suggest. The listing itself succeeded, so the exit code stays 0 (#165).
+	const unreadable = QuickCHR.listUnreadable();
 
-	if (machines.length === 0) {
+	if (machines.length === 0 && unreadable.length === 0) {
 		if (asJson) {
 			console.log("[]");
 		} else {
@@ -1490,7 +1745,10 @@ async function cmdList(argv: string[] = []) {
 	}
 
 	if (asJson) {
-		console.log(JSON.stringify(machines, null, 2));
+		console.log(JSON.stringify([
+			...machines,
+			...unreadable.map((u) => ({ name: u.name, status: "unreadable", error: u.error })),
+		], null, 2));
 		return;
 	}
 
@@ -1504,8 +1762,17 @@ async function cmdList(argv: string[] = []) {
 		formatPorts(m.ports),
 		m.pid ? String(m.pid) : dim("—"),
 	]);
+	for (const u of unreadable) {
+		rows.push([statusIcon("error"), u.name, dim("unreadable"), dim("—"), dim("—"), dim("—"), dim("—")]);
+	}
 
 	console.log(table(headers, rows));
+
+	// The row says which machine; this says what to do about it, so neither takes a
+	// second command to learn.
+	for (const u of unreadable) {
+		console.log(`\n${statusIcon("error")} ${u.name}: machine.json unreadable — 'quickchr remove ${u.name}' to clear it`);
+	}
 }
 
 function shellQuoteEnv(value: string): string {
@@ -1614,6 +1881,11 @@ async function cmdGet(argv: string[]) {
 		return;
 	}
 
+	// Every live group is a REST read. Refused here rather than left to fetchGroup(),
+	// which swallows errors and would print an empty report for a v6 machine (#182).
+	const { assertRestAvailable } = await import("../lib/versions.ts");
+	assertRestAvailable(s, "'quickchr get' (live properties)");
+
 	const { resolveAuth } = await import("../lib/auth.ts");
 	const auth = resolveAuth(s);
 	const base = `http://127.0.0.1:${instance.ports.http}/rest`;
@@ -1661,14 +1933,20 @@ async function cmdGet(argv: string[]) {
 	}
 
 	if (results["device-mode"]) {
+		const { DEVICE_MODE_NON_FEATURE_KEYS, isDeviceModeFeatureEnabled } = await import("../lib/device-mode.ts");
 		const dm = results["device-mode"] as Record<string, unknown>;
 		const mode = dm.mode ?? "(not set)";
 		console.log(`\n  ${bold("Device Mode")}`);
 		console.log(`    Mode: ${mode}`);
-		const features = Object.entries(dm)
-			.filter(([k, v]) => k !== "mode" && v === true)
-			.map(([k]) => k);
-		if (features.length > 0) console.log(`    Enabled: ${features.join(", ")}`);
+		// RouterOS reports these as strings ("true"/"false"), so the old `v === true`
+		// test matched nothing and the feature lines never printed — `get` could not
+		// read back what `set` had just written. Both lines are shown: after
+		// `--device-mode-disable smb` the interesting answer is the one that is off.
+		const features = Object.entries(dm).filter(([k]) => !DEVICE_MODE_NON_FEATURE_KEYS.has(k));
+		const enabled = features.filter(([, v]) => isDeviceModeFeatureEnabled(v)).map(([k]) => k);
+		const disabled = features.filter(([, v]) => !isDeviceModeFeatureEnabled(v)).map(([k]) => k);
+		if (enabled.length > 0) console.log(`    Enabled:  ${enabled.join(", ")}`);
+		if (disabled.length > 0) console.log(`    Disabled: ${disabled.join(", ")}`);
 	}
 
 	if (results.admin) {
@@ -1713,8 +1991,21 @@ async function cmdRemove(argv: string[]) {
 		return;
 	}
 
-	const instance = QuickCHR.get(name);
+	// A machine.json that does not parse throws out of get(), because a lookup by name
+	// must not answer "no such machine" about a directory that exists (#165). `remove`
+	// is the command whose job is to clear that state, so here it routes into the
+	// orphan path below instead of surfacing the error (#155).
+	let instance: ReturnType<typeof QuickCHR.get> = null;
+	try {
+		instance = QuickCHR.get(name);
+	} catch { /* unreadable state → orphan */ }
 	if (!instance) {
+		// A half-created directory is unremovable any other way, and `remove` naming it
+		// in the "not found" list while refusing to delete it was the worst of both (#155).
+		if (QuickCHR.removeOrphan(name)) {
+			console.log(`${bold(name)} removed (leftover directory — no readable machine.json).`);
+			return;
+		}
 		console.error(machineNotFoundMessage(name));
 		process.exit(1);
 	}
@@ -1784,6 +2075,10 @@ async function applyLicense(argv: string[]) {
 		console.error(`Machine "${name}" is not running.`);
 		process.exit(1);
 	}
+	// Before any credential prompt: instance.license() refuses RouterOS 6 too, but only
+	// after the user has typed a MikroTik password for nothing.
+	const { assertProvisioningSupportedVersion } = await import("../lib/versions.ts");
+	assertProvisioningSupportedVersion(instance.state.version, "apply a license");
 
 	let account = flag(flags, "account") ?? process.env.MIKROTIK_WEB_ACCOUNT;
 	let password = flag(flags, "password") ?? process.env.MIKROTIK_WEB_PASSWORD;
@@ -1829,28 +2124,100 @@ async function applyLicense(argv: string[]) {
 	console.log(`License applied: ${before} → ${level}`);
 }
 
+/** `set` applies a change to a machine that has already booted.
+ *
+ *  It is the post-boot half of the provisioning flags, and deliberately narrow: only
+ *  the steps that are safe to run against a guest whose configuration quickchr no
+ *  longer knows get a home here (#176). `--license` is account-level. `--device-mode`
+ *  is a capability flag — it gates whether a feature *can* run and describes nothing
+ *  about how the guest is configured, so applying it later cannot clobber working
+ *  config; the config it was blocking could not have been applied while it was off.
+ *
+ *  `--add-user`, `--disable-admin` and `--secure-login` are excluded on purpose. They
+ *  are working config rather than a capability, they collide with whatever has been
+ *  created since, and they are the steps that drift. Their route stays
+ *  `quickchr clean <name>` and a fresh provisioning run. */
 async function cmdSet(argv: string[]) {
 	const { flags, positional } = parseFlags(argv);
-	const name = positional[0];
+	// Positional first, `--name` as the fallback — the same order `applyLicense` uses,
+	// which `set --license` delegates to. Without this `quickchr set --name lab
+	// --license` printed a usage error while `quickchr license --name lab` worked.
+	const name = positional[0] ?? flag(flags, "name");
 
+	const usage = "Usage: quickchr set <name> [--license [--level=p1|p10|unlimited]] [--device-mode <mode>] [--device-mode-enable <features>] [--device-mode-disable <features>]";
 	if (!name) {
-		console.error("Usage: quickchr set <name> --license [--level=p1|p10|unlimited]");
+		console.error(usage);
+		process.exit(1);
+	}
+
+	const valueless = valuelessFlags(flags, SET_FLAGS);
+	if (valueless.length > 0) {
+		console.error(valuelessFlagMessage(valueless, "set"));
+		process.exit(1);
+	}
+
+	if (flags["device-mode"] === false) {
+		// `--no-device-mode` means "skip device-mode provisioning" on add/start. There is
+		// nothing to skip in an imperative set, so honouring it would be accepting a flag
+		// and doing nothing — the failure this whole area exists to stop.
+		console.error("--no-device-mode is a provisioning flag for 'add'/'start' (skip the step); 'set' applies a change, so pass a mode or a feature list instead.");
 		process.exit(1);
 	}
 
 	const wantsLicense = flagBool(flags, "license");
+	const deviceMode = deviceModeFromFlags(flags);
 
-	if (!wantsLicense) {
-		console.error("Nothing to set. Available flags: --license");
+	if (!wantsLicense && !deviceMode) {
+		console.error("Nothing to set. Available flags: --license, --device-mode, --device-mode-enable, --device-mode-disable");
 		process.exit(1);
 	}
 
+	// Device-mode first: it power-cycles the guest, and a license applied beforehand
+	// would be read back across a reboot it did not expect.
+	if (deviceMode) await applyDeviceModeChange(name, deviceMode);
 	if (wantsLicense) {
 		const subcmdArgs = [name, ...Object.entries(flags).flatMap(([k, v]) => v === true ? [`--${k}`] : [`--${k}=${v}`]), ...positional.slice(1)];
 		await applyLicense(subcmdArgs);
 	}
 }
 
+/** `set <name> --device-mode…` — the post-boot route the refusal names.
+ *
+ *  Device-mode needs a **power cycle**: RouterOS will not apply it otherwise, and
+ *  `/system/device-mode/update` issued from inside the guest simply never returns,
+ *  because it is waiting for a power cycle it cannot perform on itself. quickchr owns
+ *  the power button, which is why this lives here and not in a tool that talks to a
+ *  router over the network. */
+async function applyDeviceModeChange(name: string, deviceMode: DeviceModeOptions) {
+	const { QuickCHR } = await import("../lib/quickchr.ts");
+	const { bold, dim, machineNotFoundMessage } = await import("./format.ts");
+	const { formatDeviceModeSelection, resolveDeviceModeOptions } = await import("../lib/device-mode.ts");
+	const { shellQuote } = await import("../lib/names.ts");
+
+	const instance = QuickCHR.get(name);
+	if (!instance) {
+		console.error(machineNotFoundMessage(name));
+		process.exit(1);
+	}
+
+	// Before announcing a change that cannot happen (setDeviceMode() refuses it as well).
+	const { assertProvisioningSupportedVersion } = await import("../lib/versions.ts");
+	assertProvisioningSupportedVersion(instance.state.version, "set device-mode");
+
+	const selection = formatDeviceModeSelection(resolveDeviceModeOptions(deviceMode));
+	console.log(`Setting device-mode on ${bold(name)}: ${selection}`);
+	// Hedged on purpose: a request the guest already satisfies costs nothing, and
+	// setDeviceMode() skips the power cycle in that case. Promising a restart before
+	// reading the guest would make the quiet no-op look like a failure to restart.
+	console.log(dim("  RouterOS only applies device-mode across a power cycle, so any setting that moves restarts the machine."));
+	// setDeviceMode() checks the preconditions (running, user-mode NIC), prints the
+	// settings that will actually move, and skips the power cycle when none would.
+	await instance.setDeviceMode(deviceMode);
+	// Quoted for the same reason the refusal routes are: a legacy machine name can
+	// contain a space, and an unquoted read-back hint would name a different machine.
+	console.log(`Device-mode set. Read it back with: quickchr get ${shellQuote(name)} device-mode`);
+}
+
 async function cmdLicense(argv: string[]) {
 	await applyLicense(argv);
 }
@@ -2053,6 +2420,7 @@ async function cmdNetworks(argv: string[]) {
 async function showNetworkOverview() {
 	const { detectPlatform, detectPhysicalInterfaces } = await import("../lib/platform.ts");
 	const { listNamedSockets } = await import("../lib/socket-registry.ts");
+	const { describeSocketTransport } = await import("../lib/network.ts");
 	const { statusIcon, bold, dim } = await import("./format.ts");
 
 	const platform = await detectPlatform();
@@ -2126,7 +2494,8 @@ async function showNetworkOverview() {
 		console.log("  Named Sockets:");
 		for (const s of sockets) {
 			const members = s.members.length > 0 ? dim(`  members: ${s.members.join(", ")}`) : "";
-			console.log(`    ${s.name.padEnd(16)}${s.mode} port:${s.port}${members}`);
+			// Not `port:${s.port}` — a dgram link has no port and printed `port:undefined`.
+			console.log(`    ${s.name.padEnd(16)}${s.mode}  ${describeSocketTransport(s)}${members}`);
 		}
 	} else {
 		console.log("  Named Sockets:");
@@ -2153,8 +2522,11 @@ async function showInterfaces() {
 	console.log(table(["Device", "Name", "Alias", "MAC"], rows));
 }
 
+const SOCKET_MODES = ["dgram", "listen-connect", "mcast"] as const;
+
 async function handleSockets(argv: string[]) {
-	const { listNamedSockets, createNamedSocket, removeNamedSocket } = await import("../lib/socket-registry.ts");
+	const { listNamedSockets, createNamedSocket, removeNamedSocket, defaultSocketMode } = await import("../lib/socket-registry.ts");
+	const { describeSocketTransport } = await import("../lib/network.ts");
 	const { bold, dim, table: fmtTable } = await import("./format.ts");
 
 	const action = argv[0];
@@ -2168,22 +2540,73 @@ async function handleSockets(argv: string[]) {
 		const rows = sockets.map((s) => [
 			s.name,
 			s.mode,
-			String(s.port),
-			s.mcastGroup ?? "",
+			describeSocketTransport(s),
 			s.members.join(", ") || dim("none"),
 		]);
-		console.log(fmtTable(["Name", "Mode", "Port", "Group", "Members"], rows));
+		console.log(fmtTable(["Name", "Mode", "Transport", "Members"], rows));
 		return;
 	}
 
 	if (action === "create") {
-		const name = argv[1];
+		const { flags, positional } = parseFlags(argv.slice(1));
+		const name = positional[0];
 		if (!name) {
-			console.error("Usage: quickchr networks sockets create <name>");
+			console.error("Usage: quickchr networks sockets create <name> [--mode dgram|listen-connect|mcast] [--port <n>] [--group <addr>]");
+			process.exit(1);
+		}
+		// `parseFlags` stores `true` for a flag with no value and `flag()` turns that back
+		// into `undefined`, so a bare `--mode` would silently fall through to the default
+		// — the same shape as #156's valueless-flag bug.
+		for (const key of ["mode", "port", "group"]) {
+			if (typeof flags[key] === "boolean") {
+				console.error(`Error: --${key} requires a value.`);
+				process.exit(1);
+			}
+		}
+		const mode = flag(flags, "mode");
+		if (mode !== undefined && !(SOCKET_MODES as readonly string[]).includes(mode)) {
+			console.error(`Error: unknown --mode "${mode}" — expected one of ${SOCKET_MODES.join(", ")}.`);
+			process.exit(1);
+		}
+		const portRaw = flag(flags, "port");
+		// Number(), not parseInt(): parseInt stops at the first non-digit, so "4000abc"
+		// came through as 4000.
+		const port = portRaw === undefined ? undefined : Number(portRaw);
+		if (portRaw !== undefined && (!/^\d+$/.test(portRaw) || !Number.isInteger(port) || (port as number) < 1 || (port as number) > 65535)) {
+			console.error(`Error: --port must be a number between 1 and 65535, got "${portRaw}".`);
+			process.exit(1);
+		}
+		const group = flag(flags, "group");
+		const effectiveMode = mode ?? defaultSocketMode();
+		if (group !== undefined && effectiveMode !== "mcast") {
+			console.error(`Error: --group only applies to --mode mcast (this socket is ${effectiveMode}).`);
 			process.exit(1);
 		}
-		const entry = createNamedSocket(name);
-		console.log(`Created named socket: ${bold(entry.name)} (${entry.mode} port:${entry.port})`);
+		if (portRaw !== undefined && effectiveMode === "dgram") {
+			console.error("Error: --port does not apply to --mode dgram — a unix datagram pair uses no port.");
+			process.exit(1);
+		}
+		const entry = createNamedSocket(name, {
+			mode: mode as (typeof SOCKET_MODES)[number] | undefined,
+			port,
+			mcastGroup: group,
+		});
+		console.log(`Created named socket: ${bold(entry.name)} (${entry.mode})`);
+		console.log(`  Transport: ${describeSocketTransport(entry)}`);
+		if (entry.mode === "mcast") {
+			// The caveat belongs at create time, not in a doc: mcast fails with no error
+			// anywhere — interfaces up, addresses assigned, 100% loss. Three distinct
+			// hazards, not one (#167): a macOS delivery bug, a sandbox permission block,
+			// and — because quickchr passes no localaddr= — a group that rides the host's
+			// default interface rather than loopback.
+			console.log(dim("  Note: UDP multicast is the only N-way segment, and the only one that"));
+			console.log(dim("        fails silently. It does not deliver on macOS, and it is refused"));
+			console.log(dim("        in sandboxes that block unconnected UDP sends (some Linux CI)."));
+			console.log(dim(`        This group is not confined to loopback: ${entry.mcastGroup} rides the host's`));
+			console.log(dim("        default multicast interface, so another machine on your LAN using"));
+			console.log(dim("        the same group joins this segment. Use a unique group, or prefer"));
+			console.log(dim("        'dgram' for two machines."));
+		}
 		return;
 	}
 
@@ -2217,6 +2640,21 @@ Usage:
   quickchr networks sockets create <n>  Create a named socket
   quickchr networks sockets remove <n>  Remove a named socket
 
+Socket create options:
+  --mode <mode>    dgram | listen-connect | mcast
+                   Default: dgram (POSIX), listen-connect (Windows)
+  --port <n>       TCP/UDP port for listen-connect and mcast
+  --group <addr>   Multicast group for --mode mcast (default 230.0.0.1)
+
+Transports:
+  dgram            A pair of unix datagram sockets. No ports, no UDP syscalls,
+                   and either machine may start first. Two machines. POSIX only.
+  listen-connect   A TCP pair on loopback. Two machines; the first to join takes
+                   the listening end and keeps it, and must be started first
+                   thereafter. The Windows default.
+  mcast            UDP multicast — the only N-way segment, but broken on macOS
+                   and in UDP-blocked sandboxes, and silent when it fails.
+
 Aliases: quickchr net`);
 }
 
@@ -2418,6 +2856,45 @@ async function cmdCache(argv: string[]) {
 	};
 
 	switch (sub) {
+		case "add": {
+			const { cacheAdd } = await import("../lib/cache-api.ts");
+			const { resolveSetting } = await import("../lib/settings.ts");
+			const version = cacheTargetFlag(flags, "version");
+			const explicitChannel = cacheTargetFlag(flags, "channel") as Channel | undefined;
+			const channel = version !== undefined || explicitChannel !== undefined
+				? explicitChannel
+				: resolveSetting("default-channel").value as Channel;
+			const arch = (cacheTargetFlag(flags, "arch") ?? resolveSetting("default-arch").value) as Arch | "auto";
+			const asJson = flagBool(flags, "json");
+			const quiet = { status() {}, debug() {}, warn() {} };
+			const result = await cacheAdd({ version, channel, arch, logger: asJson ? quiet : undefined });
+			if (asJson) {
+				console.log(JSON.stringify(result));
+			} else {
+				console.log(`${result.cacheHit ? "Already cached" : "Cached"}: RouterOS ${result.version} (${result.arch})`);
+				console.log(`Path: ${result.path}`);
+			}
+			break;
+		}
+		case "key": {
+			const { cacheKey } = await import("../lib/cache-api.ts");
+			const version = cacheTargetFlag(flags, "version");
+			const explicitChannel = cacheTargetFlag(flags, "channel") as Channel | undefined;
+			const { resolveSetting } = await import("../lib/settings.ts");
+			const channel = version !== undefined || explicitChannel !== undefined
+				? explicitChannel
+				: resolveSetting("default-channel").value as Channel;
+			const arch = (cacheTargetFlag(flags, "arch") ?? resolveSetting("default-arch").value) as Arch | "auto";
+			const result = await cacheKey({ version, channel, arch });
+			if (flagBool(flags, "json")) {
+				console.log(JSON.stringify(result));
+			} else {
+				console.log(`dir=${result.dir}`);
+				console.log(`version=${result.version}`);
+				console.log(`arch=${result.arch}`);
+			}
+			break;
+		}
 		case "list":
 		case "ls": {
 			const entries = listCacheEntries();
@@ -2688,22 +3165,24 @@ Commands:
   setup                   Interactive setup wizard (TTY only)
   add [options]           Create a new CHR machine (without starting)
   start [<name>|options]  Start or restart a CHR instance
-  stop [<name>|--all]     Stop instance(s) — print list if no name
+  stop [<name>|--all]     Power cut — print list if no name
+  shutdown <name>         Request guest shutdown, then bounded hard-stop fallback
   list [<name>] [--json]  List all instances, or detail for one
   status                  Alias for list
   inspect <name> [--json] Print running machine descriptor as JSON
   env <name> [--json]     Print subprocess environment for a running machine
   console <name>          Attach to serial console of a running instance
   exec <name> <command>   Run a RouterOS CLI command on a running instance
+                          (raw /rest/execute — see 'quickchr exec --help' for centrs)
   remove [<name>|--all]   Remove instance(s) and disk
   clean [<name>|--all]    Reset instance disk to fresh image
-  get <name> [group]          Show machine config (license, device-mode, admin)
-  set <name> --license    Apply/renew CHR trial license
+  get <name> [group]      Show machine config (license, device-mode, admin)
+  set <name> [flags]      Change a booted machine (license, device-mode)
   license <name>          Deprecated — use 'set <name> --license'
   disk <name>             Show disk details for an instance
   snapshot <name> [cmd]   Manage snapshots (list/save/load/delete)
   networks                Network discovery & socket management
-  cache [list|prune|clear] Manage cached CHR images
+  cache [add|key|list|prune|clear] Manage cached CHR images
   settings [print|get|set|reset]  Manage quickchr's own global settings (quickchr.env)
   completions             Manage shell completions (Tab completion)
   logs <name>             Tail the QEMU log for an instance
@@ -2736,6 +3215,8 @@ Post-boot provisioning flags in this command (--add-package, --install-all-packa
 RouterOS ${MIN_PROVISION_VERSION}+ only. Older 7.x remains boot-only. Disk and network
 options still work on older versions when the required host tools are installed.
 
+${ROUTEROS6_HELP}
+
 Options:
   --name <name>         Instance name (required)
   --version <ver>       RouterOS version (e.g., 7.22.1)
@@ -2746,9 +3227,9 @@ Options:
   --accel <mode>        Force QEMU accelerator: auto|tcg|hvf|kvm (default: auto).
                         Anything but 'auto' bypasses detection, including the
                         arm64-on-Apple-Silicon TCG fallback (tikoci/quickchr#97).
-	--boot-disk-format <f> Boot disk format: qcow2|raw (default: qcow2)
-	--boot-size <size>    Resize boot disk (e.g., 512M, 2G) — qcow2 only, requires qemu-img
-	--add-disk <size>     Add an extra blank qcow2 disk (repeatable, requires qemu-img)
+  --boot-disk-format <f> Boot disk format: qcow2|raw (default: qcow2)
+  --boot-size <size>    Resize boot disk (e.g., 512M, 2G) — qcow2 only, requires qemu-img
+  --add-disk <size>     Add an extra blank qcow2 disk (repeatable, requires qemu-img)
   --add-package <pkg>   Extra package to install on first boot (repeatable)
   --forward <spec>      Add an extra hostfwd port (repeatable). Spec:
                         name[:host[:guest]][/proto], or a port range
@@ -2766,11 +3247,18 @@ Options:
   --no-winbox           Exclude WinBox port mapping
   --no-api-ssl          Exclude API-SSL port mapping
   --device-mode <m>     Set device-mode on first boot: rose|advanced|basic|home|auto|skip
+  --device-mode-enable <f>  Set one or more device-mode flags to yes (e.g. container)
+  --device-mode-disable <f> Set one or more device-mode flags to no
+  --no-device-mode      Skip device-mode provisioning entirely
   --add-network <spec>  Add a network NIC (repeatable). Specs: user, shared, bridged:<if>,
                         socket::<name>, tap:<if>. Default: single user NIC.
   --no-network          Start with no NICs (headless)
-  --vmnet-shared        [deprecated] Use --add-network shared
-  --vmnet-bridge <if>   [deprecated] Use --add-network bridged:<if>`);
+
+Provisioning flags apply on the machine's first boot — whether they are given
+here or on that first 'start'. After the guest has booted, a flag the machine already
+has is accepted as a no-op; any other is refused rather than ignored, naming where the
+change can still be made (often 'quickchr set <name>'). 'quickchr clean <name>' also
+reopens the window, but resets the disk to factory and erases the guest's configuration.`);
 			break;
 		case "setup":
 			console.log(`quickchr setup
@@ -2802,7 +3290,9 @@ Options:
 Examples:
   quickchr exec my-chr /system/resource/print
   quickchr exec my-chr ":put [:serialize to=json [/ip/address/print]]"
-  quickchr exec my-chr "/log/info message=hello"`);
+  quickchr exec my-chr "/log/info message=hello"
+
+${CENTRS_SEE_ALSO}`);
 			break;
 		case "start":
 			console.log(`quickchr start [<name>] [options]
@@ -2818,10 +3308,23 @@ validated on RouterOS ${MIN_PROVISION_VERSION}+ only. Older 7.x remains boot-onl
 Disk and network options still work on older versions when the required host tools
 are installed.
 
+${ROUTEROS6_HELP}
+
+By default 'start' returns once RouterOS is ready (REST answers; on 6.x, a native-API
+login). --no-wait returns as soon as QEMU is running and leaves readiness to you:
+    centrs retrieve --quickchr <name> /system/resource --wait 5m
+QEMU runs detached either way. --no-wait is refused with --fg, and with provisioning
+flags, including ones 'add' recorded for the first boot — provisioning needs a booted
+guest.
+
 Options:
-  --all                 Start all stopped machines
-  --bg / --background   Run in background (default)
+  --all                 Start all stopped machines, in background. Accepts only
+                        --no-wait, --accel, --timeout-extra and --[no-]secure-login
+                        (plus the deprecated no-op --bg / --background); any other
+                        option is refused rather than ignored
+  --no-wait             Return once QEMU is running; do not wait for RouterOS (not with --fg)
   --fg / --foreground   Run in foreground — serial console on stdio
+  --bg / --background   Deprecated, does nothing: background is already the default
   --version <ver>       RouterOS version (e.g., 7.22.1)
   --channel <ch>        Channel: stable, long-term, testing, development
   --arch <arch>         Architecture: arm64, x86, auto (default: host native)
@@ -2831,9 +3334,9 @@ Options:
   --accel <mode>        Force QEMU accelerator: auto|tcg|hvf|kvm (default: auto).
                         Anything but 'auto' bypasses detection, including the
                         arm64-on-Apple-Silicon TCG fallback (tikoci/quickchr#97).
-	--boot-disk-format <f> Boot disk format: qcow2|raw (default: qcow2)
-	--boot-size <size>    Resize boot disk (e.g., 512M, 2G) — qcow2 only, requires qemu-img
-	--add-disk <size>     Add an extra blank qcow2 disk (repeatable, requires qemu-img)
+  --boot-disk-format <f> Boot disk format: qcow2|raw (default: qcow2)
+  --boot-size <size>    Resize boot disk (e.g., 512M, 2G) — qcow2 only, requires qemu-img
+  --add-disk <size>     Add an extra blank qcow2 disk (repeatable, requires qemu-img)
   --add-package <pkg>   Extra package to install (repeatable)
   --forward <spec>      Add an extra hostfwd port (repeatable). Spec:
                         name[:host[:guest]][/proto], or a range
@@ -2849,8 +3352,6 @@ Options:
   --add-network <spec>  Add a network NIC (repeatable). Specs: user, shared, bridged:<if>,
                         socket::<name>, tap:<if>. Default: single user NIC.
   --no-network          Start with no NICs (headless)
-  --vmnet-shared        [deprecated] Use --add-network shared
-  --vmnet-bridge <if>   [deprecated] Use --add-network bridged:<if>
   --install-all-packages  Install all packages from all_packages.zip
   --license-level <l>   Apply trial license: p1 (1 Gbps), p10 (10 Gbps), unlimited
   --license-account <a> MikroTik account email (or use MIKROTIK_WEB_ACCOUNT env var)
@@ -2860,21 +3361,42 @@ Options:
   --device-mode-disable <f> Set one or more device-mode flags to no
   --no-device-mode      Skip device-mode provisioning entirely
   --timeout-extra <s>, -T <s>  Add extra seconds to the auto-computed boot timeout
-  --dry-run             Print what would run without starting`);
+  --dry-run             Print what would run without starting
+
+Provisioning flags (packages, login, device-mode, license) apply only on a machine's
+first boot. On a machine that has booted, a flag the machine already has (same
+packages, user, license, device-mode) is accepted as a no-op. Any other is refused,
+naming where the change can still be made — often 'quickchr set <name>'. Only reach for
+'quickchr clean <name>' if you mean it: it resets the disk to factory, erasing the
+guest's configuration, and reopens the first-boot window.`);
 			break;
 		case "stop":
 			console.log(`quickchr stop [<name>] [--all]
 
+  Power cut: QEMU SIGTERM, then SIGKILL if needed. Pending guest changes may be lost.
+  Use shutdown to request /system/shutdown first.
+
   <name>      Stop a specific running instance.
               Omit to see a list of running instances.
   --all       Stop all running instances.`);
 			break;
+		case "shutdown":
+			console.log(`quickchr shutdown <name> [--timeout <seconds>]
+
+  Request /system/shutdown over REST, then wait for QEMU to exit.
+  If it is still running at the deadline, force a power cut and report it.
+  --timeout <seconds>  Positive integer seconds (default 10).
+                       Overrides QUICKCHR_SHUTDOWN_TIMEOUT.
+  Lock wait and hard-stop escalation are separate bounded waits.
+  Preserves disks and credentials. Use stop for immediate teardown.`);
+			break;
 		case "status":
 			console.log(`quickchr status [<name>] [--json]
 
 Alias for 'quickchr list'. See 'quickchr help list'.`);
 			break;
 		case "list":
+		case "ls":
 			console.log(`quickchr list [<name>] [--json]
 
 List all CHR instances or show detailed info for one.
@@ -2986,14 +3508,30 @@ When no group is given, all properties are shown.
 The machine must be running to query live properties.`);
 			break;
 		case "set":
-			console.log(`quickchr set <name> --license [options]
+			console.log(`quickchr set <name> [--license | --device-mode...] [options]
 
-Set properties on a CHR instance.
+Change a property on a machine that has already booted. This is the post-boot
+half of the provisioning flags: 'add'/'start' apply them at first boot, 'set'
+applies them now.
 
   <name>              Name of a running CHR instance (required).
 
 Flags:
   --license           Apply or renew a CHR trial license.
+  --device-mode <m>   Set device-mode: rose|advanced|basic|home|auto
+  --device-mode-enable <f>   Set one or more device-mode flags to yes (e.g. container)
+  --device-mode-disable <f>  Set one or more device-mode flags to no
+
+Device-mode notes:
+  RouterOS only applies device-mode across a power cycle, so 'set' restarts the
+  machine (roughly double a plain start). Enabling a feature without naming a
+  mode resolves the mode to 'rose'; quickchr prints every setting that moves
+  before it restarts. The machine must be running and have a user-mode NIC.
+  Read it back with 'quickchr get <name> device-mode'.
+
+Not available here: --add-user, --disable-admin and --secure-login. Those rewrite
+working config rather than unlock a capability, so their route stays
+'quickchr clean <name>' followed by the original add/start command.
 
 License options (used with --license):
   --level <level>     License level: p1 (1 Gbps), p10 (10 Gbps), unlimited (default: p1)
@@ -3004,7 +3542,7 @@ Credential resolution order:
   1. --account / --password flags
   2. MIKROTIK_WEB_ACCOUNT / MIKROTIK_WEB_PASSWORD environment variables
   3. OS native secret store (macOS Keychain / Linux Keyring)
-  4. ~/.config/quickchr/credentials.json (fallback)`);
+  4. ~/.config/quickchr/com.quickchr.mikrotik-web.json (fallback)`);
 			break;
 		case "license":
 			console.log(`quickchr license <name> [options]
@@ -3026,7 +3564,15 @@ Credential resolution order (highest priority first):
   1. --account / --password flags
   2. MIKROTIK_WEB_ACCOUNT / MIKROTIK_WEB_PASSWORD environment variables
   3. OS native secret store (macOS Keychain, Linux GNOME Keyring, Windows Credential Manager)
-  4. ~/.config/quickchr/credentials.json (fallback)`);
+  4. ~/.config/quickchr/com.quickchr.mikrotik-web.json (fallback)`);
+			break;
+		case "qga":
+			console.log(`quickchr qga <name> <operation> [options]
+
+Query the QEMU Guest Agent on a running CHR instance.
+QGA is x86-only — the arm64 CHR image does not start the guest agent.
+
+Run 'quickchr qga <name>' with no operation to list every operation.`);
 			break;
 		case "clean":
 			console.log(`quickchr clean [<name>] [--all]
@@ -3036,6 +3582,7 @@ Credential resolution order (highest priority first):
   --all       Clean all instances.`);
 			break;
 		case "remove":
+		case "rm":
 			console.log(`quickchr remove [<name>] [--all]
 
   <name>      Remove an instance (stops if running, deletes disk and state).
@@ -3057,11 +3604,16 @@ Options:
 			showNetworksHelp();
 			break;
 		case "cache":
-			console.log(`quickchr cache <list|prune|clear> [options]
+			console.log(`quickchr cache <add|key|list|prune|clear> [options]
 
 Manage cached CHR images in the data dir cache directory.
 
 Subcommands:
+  add [--channel <ch> | --version <ver>] [--arch <arch>] [--json]
+                                      Resolve, download, and cache one CHR image without booting.
+  key [--channel <ch> | --version <ver>] [--arch <arch>] [--json]
+                                      Print cache directory, resolved version, and architecture for CI.
+                                      Without --json, output is GITHUB_OUTPUT-compatible key=value lines.
   list [--json]                       List cached images (basename, version, arch, size, age, in-use).
   prune [options]                     Evict cached images per policy. Never evicts in-use images.
     --older-than <ver>                Evict images with version < <ver>.
@@ -3110,6 +3662,7 @@ Credentials (--add-user, MIKROTIK_WEB_ACCOUNT/PASSWORD) are never stored here.`)
 			break;
 		default:
 			console.log(`No detailed help for '${command}'.`);
+			console.log("Run 'quickchr help' for the command list.");
 	}
 }