@tikoci/quickchr 0.4.1 → 0.4.3

package/README.md

@@ -136,6 +136,11 @@ quickchr networks sockets
 # Set up shell completions (bash/zsh/fish)
 quickchr completions
 
+# Persist a default so you stop repeating a flag on every add/start
+quickchr settings set default-channel long-term
+quickchr settings set secure-login true
+quickchr settings print
+
 # Reset disk to fresh image
 quickchr clean my-chr
 
@@ -251,6 +256,12 @@ quickchr start --name r2 --add-network socket::lab-switch
 quickchr start --name gw --add-network user --add-network bridged:en0
 ```
 
+Not sure which mechanism fits your traffic (host→guest service, host receiving
+guest-originated UDP, L2 broadcasts, VM↔VM links, real LAN)? See the
+[networking recipes guide](./docs/networking-recipes.md) — a "traffic shape →
+mechanism" decision table. The CLI flags map 1:1 to the library:
+`--add-network` ↔ `StartOptions.networks`, `--forward` ↔ `StartOptions.extraPorts`.
+
 ### Port Layout
 
 Each instance gets a block of 10 ports. With the default base of 9100, the first instance maps:
@@ -277,8 +288,14 @@ registry when it knows the guest port:
 quickchr add lab --forward smb                  # auto host port → guest 445/tcp
 quickchr add dude-lab --forward winbox:8291     # host 8291 → guest WinBox 8291/tcp
 quickchr add app-lab --forward myapp:9200:7777/udp
+quickchr add btest-lab --forward btest:9200-9210:2000-2010/udp  # UDP port range
 ```
 
+A **port range** (`name:hostStart-hostEnd[:guestStart-guestEnd][/proto]`) expands
+to one `hostfwd` per port — handy for L3 peers with dynamic data ports. To
+*receive* UDP a guest sends (no forward at all), see the gateway path in the
+[networking recipes guide](./docs/networking-recipes.md).
+
 Reusing a built-in service name such as `winbox` pins/replaces that service's
 host port for the machine. Existing machines keep the mapping stored in
 `machine.json`; recreate the machine to change fixed service ports cleanly.
@@ -331,6 +348,25 @@ console.log(chr.state.bootDiskFormat); // "qcow2"
 console.log(chr.state.extraDisks);     // ["512M", "2G"]
 ```
 
+### Version & channel API
+
+Pick which CHRs are worth booting (handy for CI matrices) without scraping CLI text:
+
+```typescript
+import { resolveActiveChannels, resolveAllVersions } from "@tikoci/quickchr";
+
+await resolveAllVersions();
+// { stable: "7.23.1", "long-term": "7.21.4", testing: "7.23rc4", development: "7.24beta2" }
+
+await resolveActiveChannels();
+// ["stable", "long-term", "development"]
+//   released channels always, plus any pre-release at/ahead of stable
+```
+
+`compareRouterOsVersion` orders pre-release suffixes (`7.24beta2` < `7.24rc1` <
+`7.24` < `7.24.1`). The same map is available from the CLI via
+`quickchr version --json`. See [MANUAL.md](./MANUAL.md) → *Version & channel helpers*.
+
 ### Use in Tests
 
 ```typescript
@@ -343,7 +379,7 @@ test("boot CHR and check version", async () => {
   chr = await QuickCHR.start({ channel: "stable" });
 
   const resource = await chr.rest("/system/resource");
-  expect(resource["board-name"]).toBe("CHR");
+  expect(resource["board-name"]).toContain("CHR");
 }, 120_000);
 
 afterAll(async () => {
@@ -357,17 +393,34 @@ afterAll(async () => {
 |----------|-------------|
 | `MIKROTIK_WEB_ACCOUNT` | MikroTik.com account email (for license renewal) |
 | `MIKROTIK_WEB_PASSWORD` | MikroTik.com password (for license renewal) |
+| `QUICKCHR_DEFAULT_CHANNEL`, `QUICKCHR_DEFAULT_ARCH`, `QUICKCHR_CACHE_MAX_SIZE`, `QUICKCHR_TIMEOUT_EXTRA`, `QUICKCHR_SECURE_LOGIN` | Env-tier overrides for the 5 `quickchr settings` keys — see [MANUAL.md §3 `settings`](./MANUAL.md#3-cli-command-reference) |
 | `QUICKCHR_INTEGRATION` | Set to `1` to run integration tests |
+| `QUICKCHR_TEST_TARGET` | Integration tests only: RouterOS channel (`stable`/`long-term`/`testing`/`development`) or pinned version (e.g. `7.22.1`) to boot. Empty = `stable`. The Integration workflow (`integration.yml`) sets this from its `routeros-target` dispatch input to test a release across platforms |
+
+The full list (including `QUICKCHR_DATA_DIR`, `QUICKCHR_NO_PROMPT`, `QUICKCHR_DEBUG`,
+`NO_COLOR`) is in [MANUAL.md §11](./MANUAL.md#11-auth-secrets-environment-variables).
 
 ## Documentation
 
 - **[MANUAL.md](./MANUAL.md)** — complete reference: every CLI command,
   every library API, provisioning, channels, networking, storage,
   errors. Source-checked.
+- **[examples/](./examples/)** — runnable scripts (`bun run`): `quickstart/`
+  (boot + query), `grounding/` (apply config → read back — the one `bun:test`),
+  `dude/` (install a package), `harness/` (drive an external tool), `rollback/`,
+  `service-forward/`, `file-transfer/`, `device-mode/`, plus `mndp`/`udp-gateway`/
+  `version-matrix`. See [examples/COVERAGE.md](./examples/COVERAGE.md).
+- **[docs/networking-recipes.md](./docs/networking-recipes.md)** — which
+  networking mechanism for which traffic shape.
 - **[DESIGN.md](./DESIGN.md)** — architecture, layers, design principles.
 - **[CONTRIBUTING.md](./CONTRIBUTING.md)** — dev setup and `bun run check`.
 - **[CHANGELOG.md](./CHANGELOG.md)** — release history.
 
+**Using quickchr with an AI agent?** The **`routeros-quickchr`** skill (in
+[tikoci/routeros-skills](https://github.com/tikoci/routeros-skills)) teaches
+agents the grounding workflow — boot a CHR, apply config, read it back — plus
+the networking recipes and harness patterns.
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tikoci/quickchr",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "CLI and library to download, launch, and manage MikroTik CHR virtual machines via QEMU",
   "module": "src/index.ts",
   "main": "src/index.ts",
@@ -17,21 +17,24 @@
   "files": [
     "src",
     "README.md",
-    "DESIGN.md"
+    "DESIGN.md",
+    "MANUAL.md"
   ],
   "scripts": {
-    "check": "bun run lint:biome && bun run lint:typecheck && bun run lint:markdown && bun run lint:cspell",
+    "check": "bun run lint:biome && bun run lint:typecheck && bun run lint:markdown && bun run lint:cspell && bun run lint:examples && bun run lint:shell",
     "lint": "biome check . && tsc --noEmit",
     "lint:biome": "biome check .",
     "lint:typecheck": "tsc --noEmit",
     "lint:markdown": "bunx markdownlint-cli2 '**/*.md'",
     "lint:cspell": "cspell lint . --no-progress",
+    "lint:examples": "bun run scripts/validate-examples.ts",
+    "lint:shell": "sh scripts/lint-shell.sh",
     "test": "bun test test/unit/",
     "test:examples": "bun test examples/",
+    "smoke:examples": "QUICKCHR_INTEGRATION=1 EXAMPLES_SMOKE=1 bun test test/integration/examples-smoke.test.ts",
     "test:integration": "QUICKCHR_INTEGRATION=1 bun test test/integration/",
     "test:all": "QUICKCHR_INTEGRATION=1 bun test test/unit/ test/integration/ examples/",
     "dev": "bun run src/cli/index.ts",
-    "release": "bun scripts/release.ts",
     "install:deps:ubuntu": "sudo apt-get --yes install qemu-system-x86 qemu-system-arm qemu-efi-aarch64 qemu-utils socat && curl -fsSL https://bun.sh/install | bash"
   },
   "devDependencies": {

package/src/cli/index.ts

@@ -5,7 +5,7 @@
 
 import type { StartOptions, Arch, Channel, ServiceName, NetworkSpecifier } from "../lib/types.ts";
 import { parseNetworkSpecifier } from "../lib/network.ts";
-import { parseForwardSpec } from "../lib/forward-spec.ts";
+import { expandForwardSpec } from "../lib/forward-spec.ts";
 import {
 	MIN_PROVISION_VERSION,
 	PROVISIONING_BOOT_ONLY_SUMMARY,
@@ -116,6 +116,57 @@ function isNoPrompt(): boolean {
 	return !!process.env.QUICKCHR_NO_PROMPT || !process.stdout.isTTY || !process.stdin.isTTY;
 }
 
+/** Merge the `-T` short-flag alias for `--timeout-extra` into `flags`, since parseFlags
+ *  only recognizes `--` flags. Also consumes the `-T <value>` pair from `positional`
+ *  so `quickchr start -T 15 lab` still targets `lab`. */
+export function applyTimeoutExtraShortFlag(
+	argv: readonly string[],
+	flags: Record<string, string | boolean | string[]>,
+	positional?: string[],
+): Record<string, string | boolean | string[]> {
+	const tIdx = argv.indexOf("-T");
+	if (tIdx !== -1) {
+		const value = argv[tIdx + 1];
+		if (flags["timeout-extra"] === undefined && value !== undefined) {
+			flags["timeout-extra"] = value;
+		}
+		if (positional) {
+			const pIdx = positional.indexOf("-T");
+			if (pIdx !== -1) {
+				positional.splice(pIdx, 1);
+				if (value !== undefined && positional[pIdx] === value) {
+					positional.splice(pIdx, 1);
+				}
+			}
+		}
+	}
+	return flags;
+}
+
+/** Resolve --timeout-extra into a millisecond boot-timeout addend. Validates an
+ *  explicit flag with the same non-negative-integer rule the timeout-extra setting
+ *  itself uses, falling back to the setting (env/file/default) only when the flag
+ *  is absent. Shared by cmdStart's single-target and --all bulk-restart paths.
+ *  Callers merge the `-T` short-flag alias into `flags["timeout-extra"]` before
+ *  calling this — `-T` is single-dash and parseFlags only recognizes `--` flags
+ *  (same reason cmdLogs scans argv directly for its own `-f`/`-n` aliases). */
+export async function resolveTimeoutExtraMs(flags: Record<string, string | boolean | string[]>): Promise<number | undefined> {
+	const { resolveSetting, parseTimeoutExtraSeconds } = await import("../lib/settings.ts");
+	const flagRaw = flag(flags, "timeout-extra");
+	const seconds = flagRaw !== undefined ? parseTimeoutExtraSeconds(flagRaw) : (resolveSetting("timeout-extra").value as number | undefined);
+	return seconds !== undefined ? seconds * 1000 : undefined;
+}
+
+/** 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> {
+	if (flags["secure-login"] === false) return false;
+	if (flagBool(flags, "secure-login")) return true;
+	const { resolveSetting } = await import("../lib/settings.ts");
+	return resolveSetting("secure-login").value === true ? true : undefined;
+}
+
 async function main() {
 	try {
 		switch (command) {
@@ -179,7 +230,7 @@ async function main() {
 				await cmdCompletions(args.slice(1));
 				break;
 			case "doctor":
-				await cmdDoctor();
+				await cmdDoctor(args.slice(1));
 				break;
 			case "logs":
 				await cmdLogs(args.slice(1));
@@ -191,10 +242,13 @@ async function main() {
 			case "cache":
 				await cmdCache(args.slice(1));
 				break;
+			case "settings":
+				await cmdSettings(args.slice(1));
+				break;
 			case "version":
 			case "--version":
 			case "-v":
-				await cmdVersion();
+				await cmdVersion(args.slice(1));
 				break;
 			case "help":
 			case "--help":
@@ -480,11 +534,12 @@ async function cmdAdd(argv: string[]) {
 	const { flags, positional } = parseFlags(argv);
 	const { QuickCHR } = await import("../lib/quickchr.ts");
 	const { bold, formatPorts, formatNetworks, dim } = await import("./format.ts");
+	const { resolveSetting } = await import("../lib/settings.ts");
 
 	const opts: StartOptions = {
 		version: flag(flags, "version"),
-		channel: flag(flags, "channel") as Channel | undefined,
-		arch: flag(flags, "arch") as Arch | "auto" | undefined,
+		channel: (flag(flags, "channel") as Channel | 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,
@@ -499,7 +554,7 @@ async function cmdAdd(argv: string[]) {
 		bootDiskFormat: (flag(flags, "boot-disk-format") as StartOptions["bootDiskFormat"] | undefined) ?? "qcow2",
 		bootSize: flag(flags, "boot-size"),
 		extraDisks: flagList(flags, "add-disk").length > 0 ? flagList(flags, "add-disk") : undefined,
-		extraPorts: flagList(flags, "forward").map(parseForwardSpec),
+		extraPorts: flagList(flags, "forward").flatMap(expandForwardSpec),
 	};
 
 	const deviceModeValue = flag(flags, "device-mode");
@@ -519,13 +574,7 @@ async function cmdAdd(argv: string[]) {
 		opts.user = { name: uname, password: password ?? "" };
 	}
 	opts.disableAdmin = flagBool(flags, "disable-admin");
-
-	// --secure-login / --no-secure-login
-	if (flags["secure-login"] === false) {
-		opts.secureLogin = false;
-	} else if (flagBool(flags, "secure-login")) {
-		opts.secureLogin = true;
-	}
+	opts.secureLogin = await resolveSecureLoginFlag(flags);
 
 	const state = await QuickCHR.add(opts);
 
@@ -1125,11 +1174,14 @@ async function cmdSetup() {
 
 async function cmdStart(argv: string[]) {
 	const { flags, positional } = parseFlags(argv);
+	applyTimeoutExtraShortFlag(argv, flags, positional);
 
 	// --all: start every stopped machine in background
 	if (flagBool(flags, "all")) {
 		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.");
@@ -1137,7 +1189,7 @@ async function cmdStart(argv: string[]) {
 		}
 		for (const m of stopped) {
 			console.log(`Starting ${bold(m.name)}...`);
-			const instance = await QuickCHR.start({ name: m.name, background: true });
+			const instance = await QuickCHR.start({ name: m.name, background: true, 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)}`);
 		}
@@ -1162,11 +1214,12 @@ async function cmdStart(argv: string[]) {
 	// Build start options from flags
 	const { QuickCHR } = await import("../lib/quickchr.ts");
 	const { statusIcon, formatPorts, formatNetworks, link, bold, dim, resolveDisplayCredentials, formatRestUrl, formatSshCommand } = await import("./format.ts");
+	const { resolveSetting } = await import("../lib/settings.ts");
 
 	const opts: StartOptions = {
 		version: flag(flags, "version"),
-		channel: flag(flags, "channel") as Channel | undefined,
-		arch: flag(flags, "arch") as Arch | "auto" | undefined,
+		channel: (flag(flags, "channel") as Channel | 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,
@@ -1181,10 +1234,10 @@ async function cmdStart(argv: string[]) {
 		bootDiskFormat: (flag(flags, "boot-disk-format") as StartOptions["bootDiskFormat"] | undefined) ?? "qcow2",
 		bootSize: flag(flags, "boot-size"),
 		extraDisks: flagList(flags, "add-disk").length > 0 ? flagList(flags, "add-disk") : undefined,
-		extraPorts: flagList(flags, "forward").map(parseForwardSpec),
+		extraPorts: flagList(flags, "forward").flatMap(expandForwardSpec),
 		installDeps: flagBool(flags, "install-deps"),
 		dryRun: flagBool(flags, "dry-run"),
-		timeoutExtra: parseInt(flag(flags, "timeout-extra") ?? flag(flags, "T") ?? "0", 10) * 1000 || undefined,
+		timeoutExtra: await resolveTimeoutExtraMs(flags),
 	};
 
 	const deviceModeValue = flag(flags, "device-mode");
@@ -1227,13 +1280,7 @@ async function cmdStart(argv: string[]) {
 	}
 
 	opts.disableAdmin = flagBool(flags, "disable-admin");
-
-	// --secure-login / --no-secure-login
-	if (flags["secure-login"] === false) {
-		opts.secureLogin = false;
-	} else if (flagBool(flags, "secure-login")) {
-		opts.secureLogin = true;
-	}
+	opts.secureLogin = await resolveSecureLoginFlag(flags);
 
 	// Background default: true. Explicitly foreground only with --fg / --foreground / --no-background / --no-bg.
 	const wantFg =
@@ -2314,7 +2361,7 @@ async function cmdCache(argv: string[]) {
 		return;
 	}
 
-	const { listCacheEntries, pruneCache } = await import("../lib/cache.ts");
+	const { listCacheEntries, pruneCache, parseSizeString, formatSizeBytes } = await import("../lib/cache.ts");
 
 	const parseDuration = (s: string): number => {
 		const m = s.match(/^(\d+(?:\.\d+)?)([smhdw])$/);
@@ -2324,20 +2371,8 @@ async function cmdCache(argv: string[]) {
 		const mult: Record<string, number> = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000, w: 604_800_000 };
 		return Math.floor(n * (mult[unit ?? ""] ?? 0));
 	};
-	const parseSize = (s: string): number => {
-		const m = s.match(/^(\d+(?:\.\d+)?)([KMGT]?)i?B?$/i);
-		if (!m) throw new Error(`Invalid size "${s}" (use NK/NM/NG/NT, e.g. 2G)`);
-		const n = Number.parseFloat(m[1] ?? "0");
-		const unit = (m[2] ?? "").toUpperCase();
-		const mult: Record<string, number> = { "": 1, K: 1024, M: 1024 ** 2, G: 1024 ** 3, T: 1024 ** 4 };
-		return Math.floor(n * (mult[unit] ?? 1));
-	};
-	const formatSize = (b: number): string => {
-		if (b >= 1024 ** 3) return `${(b / 1024 ** 3).toFixed(2)} GiB`;
-		if (b >= 1024 ** 2) return `${(b / 1024 ** 2).toFixed(1)} MiB`;
-		if (b >= 1024) return `${(b / 1024).toFixed(1)} KiB`;
-		return `${b} B`;
-	};
+	const parseSize = parseSizeString;
+	const formatSize = formatSizeBytes;
 	const formatAge = (ms: number): string => {
 		const s = Math.floor(ms / 1000);
 		if (s < 60) return `${s}s`;
@@ -2429,38 +2464,113 @@ async function cmdCache(argv: string[]) {
 	}
 }
 
-async function cmdDoctor() {
+async function cmdSettings(argv: string[]) {
+	const { flags, positional } = parseFlags(argv);
+	const sub = positional[0] ?? "print";
+
+	if (sub === "help" || sub === "--help" || sub === "-h") {
+		printCommandHelp("settings");
+		return;
+	}
+
+	const { settingsFilePath, settingsGet, settingsSet, settingsReset, settingsPrint } = await import("../lib/settings.ts");
+	const { formatSizeBytes } = await import("../lib/cache.ts");
+	const asJson = flags.json === true;
+
+	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 === "timeout-extra" && typeof value === "number") return `${value}s`;
+		return String(value);
+	};
+
+	switch (sub) {
+		case "print": {
+			const key = positional[1];
+			// All-keys print uses the tolerant settingsPrint() — a single malformed
+			// env/file value must not crash the whole table (settingsGet, used for a
+			// single named key below, is intentionally strict).
+			const entries = key ? [settingsGet(key)] : settingsPrint();
+			if (asJson) {
+				console.log(JSON.stringify({ file: settingsFilePath(), settings: entries }, null, 2));
+				return;
+			}
+			console.log(`Settings file: ${settingsFilePath()}\n`);
+			for (const e of entries) {
+				console.log(`${e.key.padEnd(16)} ${displayValue(e.key, e.value).padEnd(12)} [${e.source}]`);
+			}
+			break;
+		}
+		case "get": {
+			const key = positional[1];
+			if (!key) {
+				console.error("Usage: quickchr settings get <key>");
+				process.exit(1);
+			}
+			const entry = settingsGet(key);
+			console.log(asJson ? JSON.stringify(entry, null, 2) : displayValue(entry.key, entry.value));
+			break;
+		}
+		case "set": {
+			const key = positional[1];
+			const value = positional[2];
+			if (!key || value === undefined) {
+				console.error("Usage: quickchr settings set <key> <value>");
+				process.exit(1);
+			}
+			const result = settingsSet(key, value);
+			console.log(`${result.key}: ${displayValue(result.key, result.previous)} -> ${displayValue(result.key, result.value)}`);
+			break;
+		}
+		case "reset": {
+			const key = positional[1];
+			const result = settingsReset(key);
+			console.log(
+				result.cleared.length === 0
+					? key
+						? `${key} was not set.`
+						: "Nothing to clear."
+					: `Cleared: ${result.cleared.join(", ")}`,
+			);
+			break;
+		}
+		default:
+			console.error(`Unknown settings subcommand: ${sub}\nRun 'quickchr help settings' for usage.`);
+			process.exit(1);
+	}
+}
+
+async function cmdDoctor(argv: string[] = []) {
+	const { flags } = parseFlags(argv);
+	const asJson = flagBool(flags, "json");
 	const { QuickCHR } = await import("../lib/quickchr.ts");
-	const { statusIcon, bold } = await import("./format.ts");
 
 	const result = await QuickCHR.doctor();
 
+	if (asJson) {
+		// Best-effort: cache entries older than current long-term (offline → empty).
+		const staleImages = await findStaleCacheImages();
+		console.log(JSON.stringify({ ok: result.ok, checks: result.checks, staleImages }, null, 2));
+		if (!result.ok) process.exit(1);
+		return;
+	}
+
+	const { statusIcon, bold } = await import("./format.ts");
 	console.log(bold("quickchr doctor\n"));
 	for (const check of result.checks) {
 		console.log(`${statusIcon(check.status)} ${check.label}: ${check.detail}`);
 	}
-
 	console.log();
 
-	// Best-effort: warn about cache entries older than current long-term.
-	try {
-		const { listCacheEntries } = await import("../lib/cache.ts");
-		const { resolveVersion, compareRouterOsVersion } = await import("../lib/versions.ts");
-		const entries = listCacheEntries();
-		if (entries.length > 0) {
-			const longTerm = await resolveVersion("long-term");
-			const stale = entries.filter((e) => {
-				if (e.version === "unknown" || e.inUse) return false;
-				try { return compareRouterOsVersion(e.version, longTerm) < 0; } catch { return false; }
-			});
-			if (stale.length > 0) {
-				console.log(`Note: ${stale.length} cached image(s) older than current long-term (${longTerm}):`);
-				for (const e of stale) console.log(`  - ${e.basename} (${e.version})`);
-				console.log("  Hint: 'quickchr cache prune --older-than " + longTerm + "' to evict them.");
-				console.log();
-			}
-		}
-	} catch { /* offline or no cache — silent */ }
+	// Best-effort, after the checks print so the network lookup never delays them.
+	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}):`);
+		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();
+	}
 
 	if (result.ok) {
 		console.log("All checks passed.");
@@ -2470,12 +2580,50 @@ async function cmdDoctor() {
 	}
 }
 
-async function cmdVersion() {
+interface StaleCacheImage {
+	basename: string;
+	version: string;
+	/** The current long-term version this image is older than. */
+	olderThan: string;
+}
+
+/** Cached images older than the current long-term release. Empty when offline or no cache. */
+async function findStaleCacheImages(): Promise<StaleCacheImage[]> {
+	try {
+		const { listCacheEntries } = await import("../lib/cache.ts");
+		const { resolveVersion, compareRouterOsVersion } = await import("../lib/versions.ts");
+		const entries = listCacheEntries();
+		if (entries.length === 0) return [];
+		const longTerm = await resolveVersion("long-term");
+		return entries
+			.filter((e) => {
+				if (e.version === "unknown" || e.inUse) return false;
+				try { return compareRouterOsVersion(e.version, longTerm) < 0; } catch { return false; }
+			})
+			.map((e) => ({ basename: e.basename, version: e.version, olderThan: longTerm }));
+	} catch {
+		return []; // offline or no cache
+	}
+}
+
+async function cmdVersion(argv: string[] = []) {
+	const { flags } = parseFlags(argv);
+	const asJson = flagBool(flags, "json");
+	const { resolveAllVersions } = await import("../lib/versions.ts");
+
+	if (asJson) {
+		// Stable machine-readable contract: { channel: version }. Offline → {}.
+		let versions: Record<string, string> = {};
+		try {
+			versions = await resolveAllVersions();
+		} catch { /* offline — emit empty object */ }
+		console.log(JSON.stringify(versions));
+		return;
+	}
+
 	const pkg = await import("../../package.json");
 	console.log(`quickchr ${pkg.version}`);
-
 	try {
-		const { resolveAllVersions } = await import("../lib/versions.ts");
 		const versions = await resolveAllVersions();
 		console.log("\nLatest RouterOS versions:");
 		for (const [channel, version] of Object.entries(versions)) {
@@ -2520,10 +2668,11 @@ Commands:
   snapshot <name> [cmd]   Manage snapshots (list/save/load/delete)
   networks                Network discovery & socket management
   cache [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
-  doctor                  Check prerequisites
-  version                 Show version info
+  doctor [--json]         Check prerequisites
+  version [--json]        Show version info
   help [command]          Show help
 
 Environment:
@@ -2563,10 +2712,13 @@ Options:
 	--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]. Examples:
+                        name[:host[:guest]][/proto], or a port range
+                        name:hostStart-hostEnd[:guestStart-guestEnd][/proto].
+                        Examples:
                           --forward smb              (host auto, guest 445/tcp from registry)
                           --forward winbox:9300      (host pinned, guest from registry)
                           --forward myapp:9200:7777/udp  (fully explicit)
+                          --forward btest:9200-9210:2000-2010/udp  (range, e.g. dynamic ports)
   --install-all-packages  Install all packages on first boot
   --add-user <u:p>      Create user on first boot (name:password)
   --disable-admin       Disable the default admin account on first boot
@@ -2642,8 +2794,10 @@ Options:
 	--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]. Examples: smb,
-                        winbox:9300, myapp:9200:7777/udp.
+                        name[:host[:guest]][/proto], or a range
+                        name:hostStart-hostEnd[:guestStart-guestEnd][/proto].
+                        Examples: smb, winbox:9300, myapp:9200:7777/udp,
+                        btest:9200-9210:2000-2010/udp.
   --add-user <u:p>      Create user with name:password
   --disable-admin       Disable the default admin account
   --no-secure-login     Keep admin with no password (skip managed account)
@@ -2707,11 +2861,14 @@ Print environment variables for subprocesses that connect to a running CHR.
   --json      Output the env map as JSON instead of KEY=value lines.`);
 			break;
 		case "doctor":
-			console.log(`quickchr doctor
+			console.log(`quickchr doctor [--json]
 
 Check system prerequisites: QEMU binaries, firmware, acceleration,
 sshpass (for package upload), qemu-img (for disk operations), data directories,
-and cached images. Also reports the current shell and completion install status.`);
+and cached images. Also reports the current shell and completion install status.
+
+Options:
+  --json      Emit { ok, checks, staleImages } as JSON. Exit code still reflects ok.`);
 			break;
 		case "logs":
 			console.log(`quickchr logs <name> [options]
@@ -2842,6 +2999,16 @@ Credential resolution order (highest priority first):
               Omit to see a list of instances.
   --all       Remove all instances.`);
 			break;
+		case "version":
+			console.log(`quickchr version [--json]
+
+Show the quickchr version and the latest RouterOS version per channel.
+
+Options:
+  --json      Emit the latest RouterOS versions as a { channel: version } object
+              (stable, long-term, testing, development). Offline emits {}.
+              Omits the quickchr version line — query package.json for that.`);
+			break;
 		case "networks":
 		case "net":
 			showNetworksHelp();
@@ -2862,7 +3029,39 @@ Subcommands:
 
 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 (applied after each successful start).`);
+Default auto-prune cap: 2 GiB — override via 'quickchr settings set cache-max-size <size>'
+or the QUICKCHR_CACHE_MAX_SIZE env var (applied after each successful start).`);
+			break;
+		case "settings":
+			console.log(`quickchr settings [print|get|set|reset] [key] [value] [--json]
+
+Manage quickchr's own global preferences, stored in
+~/.config/quickchr/quickchr.env (dotenv-style: QUICKCHR_KEY=value lines).
+
+Managed keys:
+  default-channel   Default --channel for 'add'/'start' and the setup wizard.
+                    stable|long-term|testing|development (default: stable)
+  default-arch      Default --arch. arm64|x86|auto (default: auto = host native)
+  cache-max-size    Auto-prune cap applied after each successful start.
+                    Size string (e.g. 2G, 512M). (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
+                    --secure-login nor --no-secure-login is passed.
+                    true|false (default: false — 'settings print' shows this
+                    one as "(unset)" rather than "false"; the setup wizard
+                    needs to tell "not configured" apart from "explicitly
+                    false" to know whether to still recommend managed login)
+
+Precedence (highest wins): CLI flag > QUICKCHR_<KEY> env var > quickchr.env > built-in default.
+
+Subcommands:
+  print [key] [--json]     Show resolved value + source for one/all keys.
+  get <key> [--json]       Print one key's resolved value.
+  set <key> <value>        Validate and write a value to quickchr.env.
+  reset [key]              Delete one managed line, or all managed lines.
+
+Credentials (--add-user, MIKROTIK_WEB_ACCOUNT/PASSWORD) are never stored here.`);
 			break;
 		default:
 			console.log(`No detailed help for '${command}'.`);