@tikoci/quickchr 0.4.8 → 0.5.1

package/src/cli/index.ts

@@ -3,18 +3,20 @@
  * 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, START_FLAGS, VALUE_FLAGS, unknownFlags, unknownFlagMessage, valuelessFlags, valuelessFlagMessage } from "./flags.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);
@@ -103,6 +105,20 @@ function flagBool(flags: Record<string, string | boolean | string[]>, key: strin
 	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;
@@ -114,6 +130,49 @@ function csvList(values: string[]): string[] {
 	return [...new Set(values.flatMap((value) => value.split(",")).map((value) => value.trim()).filter(Boolean))];
 }
 
+/** 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"));
+
+	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[] = [];
@@ -222,10 +281,27 @@ 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;
 }
@@ -264,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":
@@ -360,7 +439,9 @@ async function main() {
 				console.error(`  Hint: ${err.installHint}`);
 			}
 			for (const line of tipsForError(err.code, command)) tip(line);
-			if (err.code === "PROVISIONING_VERSION_UNSUPPORTED") {
+			// 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:");
@@ -375,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`;
@@ -626,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] : []),
@@ -645,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);
 
@@ -673,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}`);
 }
@@ -1261,29 +1360,81 @@ async function cmdSetup() {
 	}
 }
 
-async function cmdStart(argv: string[]) {
+/** 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`);
+}
+
+/** Single-target start's status word: a machine this call created says so (#194). */
+function startStatusLine(created: boolean, noWait: boolean): string {
+	if (noWait) return `${created ? "created" : "launched"} — not waiting for RouterOS (--no-wait)`;
+	return created ? "created and started" : "started";
+}
+
+export 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;
 	}
@@ -1310,13 +1461,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] : []),
@@ -1327,26 +1480,11 @@ async function cmdStart(argv: string[]) {
 		bootSize: flag(flags, "boot-size"),
 		extraDisks: flagList(flags, "add-disk").length > 0 ? flagList(flags, "add-disk") : undefined,
 		extraPorts: flagList(flags, "forward").flatMap(expandForwardSpec),
-		installDeps: flagBool(flags, "install-deps"),
 		dryRun: flagBool(flags, "dry-run"),
 		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");
@@ -1371,10 +1509,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");
+	// No name, or a name no machine has: this call creates the machine (#194).
+	const target = opts.name ? QuickCHR.get(opts.name) : null;
+	{
+		const { isProvisioningWindowOpen } = await import("../lib/provisioning-window.ts");
+		// 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") ||
@@ -1387,8 +1540,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);
@@ -1396,7 +1550,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 ||
@@ -1423,13 +1577,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)} ${startStatusLine(!target, opts.wait === false)}`);
+		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`);
@@ -1437,6 +1597,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");
@@ -1700,6 +1886,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`;
@@ -1747,14 +1938,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) {
@@ -1883,6 +2080,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;
@@ -1928,28 +2129,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);
 }
@@ -1968,7 +2241,7 @@ async function cmdDisk(argv: string[]) {
 
 	const { QuickCHR } = await import("../lib/quickchr.ts");
 	const { bold, dim, machineNotFoundMessage } = await import("./format.ts");
-	const { getDiskInfo } = await import("../lib/disk.ts");
+	const { bootDiskFormatOf, bootDiskPath, getDiskInfo } = await import("../lib/disk.ts");
 	const { join } = await import("node:path");
 	const { existsSync } = await import("node:fs");
 	const { findQemuImg } = await import("../lib/platform.ts");
@@ -1991,10 +2264,8 @@ async function cmdDisk(argv: string[]) {
 	console.log(bold(`Disks for ${name}\n`));
 
 	// Boot disk
-	const bootPath = state.bootDiskFormat === "qcow2"
-		? join(state.machineDir, "boot.qcow2")
-		: join(state.machineDir, "disk.img");
-	const bootFormat = state.bootDiskFormat ?? "raw";
+	const bootFormat = bootDiskFormatOf(state);
+	const bootPath = bootDiskPath(state.machineDir, bootFormat);
 
 	if (qemuImg && existsSync(bootPath)) {
 		try {
@@ -2567,7 +2838,7 @@ async function cmdCache(argv: string[]) {
 		return;
 	}
 
-	const { listCacheEntries, pruneCache, parseSizeString, formatSizeBytes } = await import("../lib/cache.ts");
+	const { cacheInventory, countEntries, pruneCache, parseSizeString, formatSizeBytes } = await import("../lib/cache.ts");
 
 	const parseDuration = (s: string): number => {
 		const m = s.match(/^(\d+(?:\.\d+)?)([smhdw])$/);
@@ -2579,6 +2850,11 @@ async function cmdCache(argv: string[]) {
 	};
 	const parseSize = parseSizeString;
 	const formatSize = formatSizeBytes;
+	const printFailedDeletes = (failed: Array<{ entry: { basename: string }; error: string }>) => {
+		if (failed.length === 0) return;
+		console.error(`Could not delete ${countEntries(failed.length)} (kept, not counted as freed):`);
+		for (const { entry, error } of failed) console.error(`  - ${entry.basename}: ${error}`);
+	};
 	const formatAge = (ms: number): string => {
 		const s = Math.floor(ms / 1000);
 		if (s < 60) return `${s}s`;
@@ -2629,13 +2905,14 @@ async function cmdCache(argv: string[]) {
 		}
 		case "list":
 		case "ls": {
-			const entries = listCacheEntries();
+			const { entries, unmanagedBytes } = cacheInventory();
 			if (flags.json === true) {
 				console.log(JSON.stringify(entries, null, 2));
 				return;
 			}
 			if (entries.length === 0) {
-				console.log("No cached images.");
+				console.log("No cache entries.");
+				if (unmanagedBytes > 0) console.log(`Other files: ${formatSize(unmanagedBytes)} (not written by quickchr; never pruned)`);
 				return;
 			}
 			const now = Date.now();
@@ -2662,7 +2939,8 @@ async function cmdCache(argv: string[]) {
 				);
 			}
 			const total = entries.reduce((s, e) => s + e.sizeBytes, 0);
-			console.log(`\nTotal: ${entries.length} image(s), ${formatSize(total)}`);
+			console.log(`\nTotal: ${countEntries(entries.length)}, ${formatSize(total)}`);
+			if (unmanagedBytes > 0) console.log(`Other files: ${formatSize(unmanagedBytes)} (not written by quickchr; never pruned)`);
 			break;
 		}
 		case "prune": {
@@ -2676,29 +2954,33 @@ async function cmdCache(argv: string[]) {
 			}
 			const result = pruneCache(opts);
 			const verb = opts.dryRun ? "Would evict" : "Evicted";
-			if (result.evicted.length === 0) {
+			if (result.evicted.length === 0 && result.failed.length === 0) {
 				console.log("Nothing to evict.");
-			} else {
-				console.log(`${verb} ${result.evicted.length} image(s):`);
+			} else if (result.evicted.length > 0) {
+				console.log(`${verb} ${countEntries(result.evicted.length)}:`);
 				for (const e of result.evicted) {
 					const reason = result.reasons[e.basename] ?? "policy";
 					console.log(`  - ${e.basename} (${formatSize(e.sizeBytes)}) — ${reason}`);
 				}
-				console.log(`Freed: ${formatSize(result.freedBytes)}`);
+				console.log(`${opts.dryRun ? "Would free" : "Freed"}: ${formatSize(result.freedBytes)}`);
 			}
+			printFailedDeletes(result.failed);
+			if (result.failed.length > 0) process.exitCode = 1;
 			break;
 		}
 		case "clear": {
 			if (flags.all !== true) {
-				console.error("cache clear: refuses without --all (deletes all non-in-use cached images)");
+				console.error("cache clear: refuses without --all (deletes all non-in-use cache entries)");
 				process.exit(1);
 			}
 			const result = pruneCache({ maxSizeBytes: 0, dryRun: flags["dry-run"] === true });
 			const verb = flags["dry-run"] === true ? "Would delete" : "Deleted";
-			console.log(`${verb} ${result.evicted.length} image(s), freed ${formatSize(result.freedBytes)}`);
+			console.log(`${verb} ${countEntries(result.evicted.length)}, ${flags["dry-run"] === true ? "would free" : "freed"} ${formatSize(result.freedBytes)}`);
+			printFailedDeletes(result.failed);
+			if (result.failed.length > 0) process.exitCode = 1;
 			if (result.kept.some((e) => e.inUse)) {
 				const inUse = result.kept.filter((e) => e.inUse);
-				console.log(`Kept ${inUse.length} in-use image(s):`);
+				console.log(`Kept ${inUse.length} in-use cache ${inUse.length === 1 ? "entry" : "entries"}:`);
 				for (const e of inUse) console.log(`  - ${e.basename}`);
 			}
 			break;
@@ -2724,7 +3006,7 @@ async function cmdSettings(argv: string[]) {
 
 	const displayValue = (key: string, value: unknown): string => {
 		if (value === undefined) return "(unset)";
-		if (key === "cache-max-size" && typeof value === "number") return formatSizeBytes(value);
+		if ((key === "cache-max-size" || key === "storage-reserve") && typeof value === "number") return formatSizeBytes(value);
 		if (key === "timeout-extra" && typeof value === "number") return `${value}s`;
 		return String(value);
 	};
@@ -2811,7 +3093,7 @@ async function cmdDoctor(argv: string[] = []) {
 	const staleImages = await findStaleCacheImages();
 	if (staleImages.length > 0) {
 		const longTerm = staleImages[0]?.olderThan;
-		console.log(`Note: ${staleImages.length} cached image(s) older than current long-term (${longTerm}):`);
+		console.log(`Note: ${staleImages.length} cache item(s) older than current long-term (${longTerm}):`);
 		for (const e of staleImages) console.log(`  - ${e.basename} (${e.version})`);
 		console.log("  Hint: 'quickchr cache prune --older-than " + longTerm + "' to evict them.");
 		console.log();
@@ -2897,7 +3179,8 @@ 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
@@ -2905,15 +3188,16 @@ Commands:
   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)
+  qga <name> <operation>  Query the QEMU Guest Agent (x86 only)
   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 [add|key|list|prune|clear] Manage cached CHR images
+  cache [add|key|list|prune|clear] Manage cached CHR images and packages
   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
@@ -2946,6 +3230,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)
@@ -2956,9 +3242,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
@@ -2976,9 +3262,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)`);
+  --no-network          Start with no NICs (headless)
+
+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
@@ -3012,6 +3307,13 @@ Examples:
   quickchr exec my-chr ":put [:serialize to=json [/ip/address/print]]"
   quickchr exec my-chr "/log/info message=hello"
 
+Exit status:
+  0 means the command was delivered, not that RouterOS accepted it. A rejected
+  command (e.g. "failure: invalid user name") still exits 0, with
+  RouterOS's message as the output. For a pass/fail exit code, use centrs
+  (a write command needs --yes when not run at a TTY):
+    centrs execute --quickchr <name> --yes <command>
+
 ${CENTRS_SEE_ALSO}`);
 			break;
 		case "start":
@@ -3028,10 +3330,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)
@@ -3041,9 +3356,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
@@ -3068,15 +3383,35 @@ 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]
 
@@ -3195,14 +3530,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)
@@ -3213,7 +3564,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]
@@ -3235,7 +3586,7 @@ 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]
@@ -3277,7 +3628,9 @@ Options:
 		case "cache":
 			console.log(`quickchr cache <add|key|list|prune|clear> [options]
 
-Manage cached CHR images in the data dir cache directory.
+Manage cached CHR images and package archives in the data dir cache directory.
+An all-packages archive and its extraction are one entry; an interrupted download
+is a partial entry. Files quickchr did not write are reported, never deleted.
 
 Subcommands:
   add [--channel <ch> | --version <ver>] [--arch <arch>] [--json]
@@ -3285,14 +3638,16 @@ Subcommands:
   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>.
-    --max-age <dur>                   Evict images older than duration (e.g. 7d, 24h).
-    --max-size <size>                 Evict oldest-version images until total size <= <size>.
+  list [--json]                       List cache entries (basename, version, arch, size, age, in-use).
+  prune [options]                     Evict cache entries per policy. Never evicts in-use entries.
+    --older-than <ver>                Evict entries with version < <ver>.
+    --max-age <dur>                   Evict entries not used for longer than duration (e.g. 7d, 24h).
+    --max-size <size>                 Evict entries until total size <= <size>: partial downloads
+                                      first, then oldest RouterOS version.
     --dry-run                         Show what would be evicted without deleting.
-  clear --all                         Delete all non-in-use cached images.
+  clear --all                         Delete all non-in-use cache entries.
 
+A failed delete is listed on stderr, is not counted as freed, and exits 1.
 Duration: <N>(s|m|h|d|w)   Size: <N>(K|M|G|T)[i][B] (case-insensitive, IEC binary).
 
 Default auto-prune cap: 2 GiB — override via 'quickchr settings set cache-max-size <size>'
@@ -3312,6 +3667,8 @@ Managed keys:
                     auto|tcg|hvf|kvm (default: auto = detect)
   cache-max-size    Auto-prune cap applied after each successful start.
                     Size string (e.g. 2G, 512M). (default: 2G)
+  storage-reserve   Free space creating a machine or filling the cache must
+                    leave, beyond what it writes. Size string. (default: 2G)
   timeout-extra     Default for 'start's --timeout-extra/-T when omitted.
                     Non-negative integer seconds. (default: 0)
   secure-login      Default for 'add'/'start's --secure-login when neither