@tikoci/quickchr 0.4.2 → 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.
@@ -362,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 () => {
@@ -376,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.2",
+  "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) {
@@ -191,6 +242,9 @@ 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":
@@ -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,6 +2464,82 @@ async function cmdCache(argv: string[]) {
 	}
 }
 
+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");
@@ -2557,6 +2668,7 @@ 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 [--json]         Check prerequisites
@@ -2600,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
@@ -2679,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)
@@ -2912,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}'.`);

package/src/cli/wizard.ts

@@ -5,12 +5,43 @@
 import type { Arch, Channel, DeviceModeOptions, LicenseLevel, LicenseOptions, NetworkSpecifier, StartOptions } from "../lib/types.ts";
 import { CHANNELS, ARCHES, knownPackagesForArch } from "../lib/types.ts";
 
+export type WizardUserChoice = "custom" | "managed" | "admin";
+
+export interface WizardUserChoiceResult {
+	user?: { name: string; password: string };
+	disableAdmin: boolean;
+	secureLogin?: boolean;
+}
+
+/**
+ * Maps the wizard's "CHR login setup" choice to StartOptions fields. Pulled out as a
+ * pure function (rather than inlined in runWizard) so it's unit-testable without
+ * mocking the entire @clack/prompts prompt sequence — "managed" must set both
+ * disableAdmin AND secureLogin, since provision() only auto-creates the replacement
+ * quickchr account when secureLogin === true (src/lib/provision.ts); disableAdmin
+ * alone would disable the default account with no replacement login provisioned.
+ */
+export function resolveUserChoiceOptions(
+	userChoice: WizardUserChoice,
+	customUser?: { name: string; password: string },
+): WizardUserChoiceResult {
+	if (userChoice === "custom") {
+		return { user: customUser, disableAdmin: true };
+	}
+	if (userChoice === "managed") {
+		return { disableAdmin: true, secureLogin: true };
+	}
+	// "admin" — keep admin with no password
+	return { disableAdmin: false, secureLogin: false };
+}
+
 /** Run the interactive wizard using @clack/prompts. */
 export async function runWizard(wizardOpts?: { firstRun?: boolean }): Promise<void> {
 	// Dynamic import — only loaded when wizard is actually used
 	const clack = await import("@clack/prompts");
 	const { QuickCHR } = await import("../lib/quickchr.ts");
 	const { formatPorts, bold } = await import("./format.ts");
+	const { resolveSetting } = await import("../lib/settings.ts");
 
 	clack.intro("quickchr — MikroTik CHR Manager");
 	if (wizardOpts?.firstRun) {
@@ -31,6 +62,7 @@ export async function runWizard(wizardOpts?: { firstRun?: boolean }): Promise<vo
 	let channel: Channel | undefined;
 
 	if (versionSource === "channel") {
+		const defaultChannel = resolveSetting("default-channel").value as Channel;
 		const ch = await clack.select({
 			message: "Select channel:",
 			options: CHANNELS.map((c) => ({
@@ -38,7 +70,7 @@ export async function runWizard(wizardOpts?: { firstRun?: boolean }): Promise<vo
 				label: c,
 				hint: c === "long-term" ? "recommended for provisioning" : undefined,
 			})),
-			initialValue: "long-term" as Channel,
+			initialValue: defaultChannel,
 		});
 		if (clack.isCancel(ch)) { clack.cancel("Cancelled."); process.exit(0); }
 		channel = ch;
@@ -57,6 +89,8 @@ export async function runWizard(wizardOpts?: { firstRun?: boolean }): Promise<vo
 
 	// 2. Architecture
 	const hostArch = process.arch === "arm64" ? "arm64" : "x86";
+	const settingArch = resolveSetting("default-arch").value as Arch | "auto";
+	const archInitial: Arch = settingArch === "auto" ? hostArch : settingArch;
 	const arch = await clack.select({
 		message: "Architecture:",
 		options: ARCHES.map((a) => ({
@@ -64,7 +98,7 @@ export async function runWizard(wizardOpts?: { firstRun?: boolean }): Promise<vo
 			label: a,
 			hint: a === hostArch ? "host native" : "emulated (slower)",
 		})),
-		initialValue: hostArch as Arch,
+		initialValue: archInitial,
 	});
 	if (clack.isCancel(arch)) { clack.cancel("Cancelled."); process.exit(0); }
 
@@ -304,7 +338,7 @@ export async function runWizard(wizardOpts?: { firstRun?: boolean }): Promise<vo
 	} = await import("../lib/versions.ts");
 	let resolvedVersion = version ?? await resolveVersion(channel ?? "long-term");
 	version = resolvedVersion;
-	let provisioningSupported = isProvisioningSupportedVersion(resolvedVersion);
+	const provisioningSupported = isProvisioningSupportedVersion(resolvedVersion);
 
 	let installAllPackages = false;
 	let packages: string[] = [];
@@ -346,7 +380,6 @@ export async function runWizard(wizardOpts?: { firstRun?: boolean }): Promise<vo
 			channel = "long-term";
 			resolvedVersion = await resolveVersion(channel);
 			version = resolvedVersion;
-			provisioningSupported = true;
 			wantProvision = await askProvisionChoice();
 		}
 	}
@@ -428,6 +461,7 @@ export async function runWizard(wizardOpts?: { firstRun?: boolean }): Promise<vo
 		}
 
 		// 6c. User setup
+		const secureLoginSetting = resolveSetting("secure-login").value;
 		const userChoice = await clack.select({
 			message: "CHR login setup:",
 			options: [
@@ -435,10 +469,11 @@ export async function runWizard(wizardOpts?: { firstRun?: boolean }): Promise<vo
 				{ value: "custom", label: "Custom user", hint: "you provide username + password" },
 				{ value: "admin", label: "Keep admin with no password", hint: "less secure" },
 			],
-			initialValue: "managed",
+			initialValue: secureLoginSetting === false ? "admin" : "managed",
 		});
 		if (clack.isCancel(userChoice)) { clack.cancel("Cancelled."); process.exit(0); }
 
+		let customUser: { name: string; password: string } | undefined;
 		if (userChoice === "custom") {
 			const userName = await clack.text({
 				message: "Username:",
@@ -449,14 +484,9 @@ export async function runWizard(wizardOpts?: { firstRun?: boolean }): Promise<vo
 			const userPass = await clack.password({ message: "Password:" });
 			if (clack.isCancel(userPass)) { clack.cancel("Cancelled."); process.exit(0); }
 
-			user = { name: userName, password: userPass };
-			disableAdmin = true;
-		} else if (userChoice === "managed") {
-			disableAdmin = true;
-		} else {
-			// "admin" — keep admin with no password
-			secureLogin = false;
+			customUser = { name: userName, password: userPass };
 		}
+		({ user, disableAdmin, secureLogin } = resolveUserChoiceOptions(userChoice as WizardUserChoice, customUser));
 
 		// 6d. License
 		const wantLicense = await clack.confirm({

package/src/index.ts

@@ -125,7 +125,7 @@ export { WELL_KNOWN_GUEST_PORTS, lookupGuestPort } from "./lib/guest-ports.ts";
 export type { GuestPortDef } from "./lib/guest-ports.ts";
 
 // Forward spec parsing
-export { parseForwardSpec } from "./lib/forward-spec.ts";
+export { parseForwardSpec, expandForwardSpec, FORWARD_RANGE_MAX } from "./lib/forward-spec.ts";
 
 // Logging
 export { createLogger } from "./lib/log.ts";

package/src/lib/cache.ts

@@ -11,10 +11,28 @@ import { existsSync, readdirSync, statSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { getCacheDir, loadAllMachines } from "./state.ts";
 import { chrImageBasename, compareRouterOsVersion, isValidVersion } from "./versions.ts";
-import type { Arch } from "./types.ts";
+import { QuickCHRError, type Arch } from "./types.ts";
 
 export const DEFAULT_CACHE_MAX_BYTES = 2 * 1024 * 1024 * 1024;
 
+/** Parse a human size string (NK/NM/NG/NT, IEC binary, case-insensitive) to bytes. */
+export function parseSizeString(s: string): number {
+	const m = s.match(/^(\d+(?:\.\d+)?)([KMGT]?)i?B?$/i);
+	if (!m) throw new QuickCHRError("INVALID_SIZE_STRING", `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));
+}
+
+/** Format a byte count as a human size (IEC binary), matching cache list's display. */
+export function formatSizeBytes(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`;
+}
+
 export interface CacheEntry {
 	path: string;
 	basename: string;