@tikoci/quickchr 0.4.2 → 0.4.4

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,28 +288,44 @@ 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.
 
 ### Machine Descriptors and Subprocess Environments
 
-`quickchr inspect <name> [--json]` emits a stable JSON descriptor for a
-**running** machine: status, ports, URLs, auth, env vars, and the machine
-directory. `--json` is accepted for parity; inspect output is always JSON.
+`quickchr inspect <name> [--json]` emits a stable, versioned
+(`descriptorVersion: 1`) JSON descriptor for a **running** machine — the
+quickchr ↔ centrs interface contract
+([issue #71](https://github.com/tikoci/quickchr/issues/71),
+[`docs/centrs-interface.md`](docs/centrs-interface.md)): status, machine
+identity, and a per-service `services` map (`rest-api`, `native-api`, `ssh`)
+giving host/port/transport/`tls`/availability/auth for each, plus optional
+`customForwards` and `networks`. `--json` is accepted for parity; inspect
+output is always JSON. It has no `env` field — use `quickchr env` for
+subprocess env vars.
 
 `quickchr env <name> [--json]` prints the same subprocess environment as
 `ChrInstance.subprocessEnv()`: shell `KEY=value` lines by default, or a JSON
 map with `--json`.
 
-> **Credential caveat:** descriptor/env output includes connection secrets
-> (`auth.password`, `auth.basic`, `auth.header`, `QUICKCHR_AUTH`, `BASICAUTH`)
-> so child processes can connect without reading quickchr's secret store. Treat
-> it like a password: do not commit it, paste it into public issues, or leave it
-> in CI logs. Stopped machines fail with `MACHINE_STOPPED`; start the machine
-> before requesting a descriptor or env map.
+> **Credential caveat:** descriptor/env output includes connection secrets —
+> `subprocessEnv()`/`quickchr env`'s `QUICKCHR_AUTH`/`BASICAUTH`, and each
+> `descriptor()` service's own auth fields (`services["rest-api"].auth.password`/
+> `.basic`/`.header`; `services["native-api"].auth.password`, no basic/header;
+> `services.ssh.auth.privateKeyPath`) — so child processes can connect without
+> reading quickchr's secret store. Treat it like a password: do not commit it,
+> paste it into public issues, or leave it in CI logs. Stopped machines fail
+> with `MACHINE_STOPPED`; start the machine before requesting a descriptor or
+> env map.
 
 ### Library Usage
 
@@ -362,7 +389,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 +403,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.4",
   "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 =
@@ -1443,7 +1490,7 @@ function shellQuoteEnv(value: string): string {
 	return `'${value.replaceAll("'", "'\\''")}'`;
 }
 
-async function getRunningDescriptor(name: string) {
+async function getRunningInstance(name: string) {
 	const { QuickCHR } = await import("../lib/quickchr.ts");
 	const { machineNotFoundMessage } = await import("./format.ts");
 	const instance = QuickCHR.get(name);
@@ -1451,6 +1498,18 @@ async function getRunningDescriptor(name: string) {
 		console.error(machineNotFoundMessage(name));
 		process.exit(1);
 	}
+	if (instance.state.status !== "running") {
+		const { QuickCHRError } = await import("../lib/types.ts");
+		throw new QuickCHRError(
+			"MACHINE_STOPPED",
+			`Machine "${name}" must be running to inspect its connection environment (current status: ${instance.state.status}).`,
+		);
+	}
+	return instance;
+}
+
+async function getRunningDescriptor(name: string) {
+	const instance = await getRunningInstance(name);
 	return instance.descriptor();
 }
 
@@ -1473,12 +1532,13 @@ async function cmdEnv(argv: string[] = []) {
 		console.error("Usage: quickchr env <name> [--json]");
 		process.exit(1);
 	}
-	const descriptor = await getRunningDescriptor(name);
+	const instance = await getRunningInstance(name);
+	const env = await instance.subprocessEnv();
 	if (asJson) {
-		console.log(JSON.stringify(descriptor.env, null, 2));
+		console.log(JSON.stringify(env, null, 2));
 		return;
 	}
-	for (const [key, value] of Object.entries(descriptor.env)) {
+	for (const [key, value] of Object.entries(env)) {
 		console.log(`${key}=${shellQuoteEnv(value)}`);
 	}
 }
@@ -2314,7 +2374,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 +2384,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 +2477,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 +2681,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 +2725,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 +2807,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)
@@ -2729,8 +2859,9 @@ List all CHR instances or show detailed info for one.
 		case "inspect":
 			console.log(`quickchr inspect <name> [--json]
 
-Print a stable JSON descriptor for a running CHR instance: ports, URLs,
-credentials, status, and subprocess env vars.
+Print a stable JSON descriptor for a running CHR instance: status, machine
+identity, and per-service connection facts (rest-api, native-api, ssh).
+Use 'quickchr env' for subprocess env vars.
 
   <name>      Name of a running CHR instance.
   --json      Accepted for parity; output is always JSON.`);
@@ -2912,7 +3043,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}'.`);