@tikoci/quickchr 0.4.6 → 0.4.8

package/src/cli/format.ts

@@ -2,12 +2,21 @@
  * CLI output formatting — tables, colors, status indicators.
  */
 
-import { listMachineNames } from "../lib/state.ts";
+import { listMachineNames, listOrphanMachineDirs } from "../lib/state.ts";
 
 /** Format a "machine not found" error with helpful suggestions. */
 export function machineNotFoundMessage(name: string): string {
-	const names = listMachineNames();
+	// listMachineNames() is directory-based, so it also returns half-created machines.
+	// Offering one as "Available" is what made `remove` name a machine in the same
+	// breath as refusing to find it (#155) — so orphans get their own line.
+	const orphans = listOrphanMachineDirs();
+	const names = listMachineNames().filter((n) => !orphans.includes(n));
 	let msg = `Machine "${name}" not found.`;
+	if (orphans.includes(name)) {
+		msg = `Machine "${name}" has a leftover directory with no readable machine.json — a create that did not finish.`;
+		msg += `\n  Clear it with: quickchr remove ${name}`;
+		return msg;
+	}
 	if (names.length === 0) {
 		msg += `\n  No machines exist. Create one: quickchr start`;
 	} else if (names.length <= 5) {
@@ -15,6 +24,9 @@ export function machineNotFoundMessage(name: string): string {
 	} else {
 		msg += `\n  Run 'quickchr list' to see available machines.`;
 	}
+	if (orphans.length > 0) {
+		msg += `\n  Leftover directories (no readable machine.json): ${orphans.join(", ")} — clear with 'quickchr remove <name>'`;
+	}
 	return msg;
 }
 
@@ -113,7 +125,12 @@ export function formatNetworks(networks: { specifier: unknown; id: string }[]):
 			if (s.type === "socket-listen") return `socket:listen:${s.port}`;
 			if (s.type === "socket-connect") return `socket:connect:${s.port}`;
 			if (s.type === "socket-mcast") return `socket:mcast:${s.group}:${s.port}`;
-			if (s.type === "socket-named") return `socket::${s.name}`;
+			// `{type:"socket"}` is what `parseNetworkSpecifier` emits. This tested for
+			// "socket-named", a type name nothing ever produced, so the branch could not
+			// match and every named socket fell through to JSON.stringify — part of why
+			// the field report had to open machine.json to find out what its link was
+			// (#158).
+			if (s.type === "socket") return `socket::${s.name}`;
 			if (s.type === "tap") return `tap:${s.ifname}`;
 			return JSON.stringify(spec);
 		}

package/src/cli/index.ts

@@ -6,6 +6,9 @@
 import type { StartOptions, Arch, Channel, 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 { QuickCHRError } from "../lib/types.ts";
+import { CENTRS_EXEC_TIP, CENTRS_SEE_ALSO, tip, tipsForError } from "./tips.ts";
 import {
 	MIN_PROVISION_VERSION,
 	PROVISIONING_BOOT_ONLY_SUMMARY,
@@ -17,8 +20,24 @@ import {
 const args = process.argv.slice(2);
 const command = args[0];
 
-/** Parse --flag=value and --flag value pairs from args. */
-export function parseFlags(argv: string[]): { flags: Record<string, string | boolean | string[]>; positional: string[] } {
+/** Stop a removed flag at the parser, naming what replaced it. Thrown rather than
+ *  printed so it reaches `main()`'s handler like any other error, and so no command can
+ *  reach a state where the flag was accepted and ignored (#164). */
+function rejectRemovedFlag(key: string): void {
+	const replacement = REMOVED_FLAGS.get(key);
+	if (replacement === undefined) return;
+	throw new QuickCHRError("INVALID_ARGUMENT", `--${key} was removed. Use: ${replacement}`);
+}
+
+/** Parse --flag=value and --flag value pairs from args.
+ *
+ *  Arity comes from `VALUE_FLAGS`, never from the shape of the next argument: a flag
+ *  that is not in that table is boolean and leaves the following argument alone, so a
+ *  positional cannot be eaten by a flag that has no use for it (#164). */
+export function parseFlags(
+	argv: string[],
+	valueFlags: ReadonlySet<string> = VALUE_FLAGS,
+): { flags: Record<string, string | boolean | string[]>; positional: string[] } {
 	const flags: Record<string, string | boolean | string[]> = {};
 	const positional: string[] = [];
 
@@ -33,13 +52,16 @@ export function parseFlags(argv: string[]): { flags: Record<string, string | boo
 			const eqIdx = arg.indexOf("=");
 			if (eqIdx !== -1) {
 				const key = arg.slice(2, eqIdx);
+				rejectRemovedFlag(key);
 				flags[key] = arg.slice(eqIdx + 1);
 			} else if (arg.startsWith("--no-")) {
+				rejectRemovedFlag(arg.slice(5));
 				flags[arg.slice(5)] = false;
 			} else {
 				const key = arg.slice(2);
+				rejectRemovedFlag(key);
 				const next = argv[i + 1];
-				if (next && !next.startsWith("--")) {
+				if (valueFlags.has(key) && next !== undefined && !next.startsWith("--")) {
 					// Check if this is a repeatable flag
 					const existing = flags[key];
 					if (Array.isArray(existing)) {
@@ -68,6 +90,15 @@ function flag(flags: Record<string, string | boolean | string[]>, key: string):
 	return undefined;
 }
 
+function cacheTargetFlag(flags: Record<string, string | boolean | string[]>, key: string): string | undefined {
+	if (!(key in flags)) return undefined;
+	const value = flags[key];
+	if (typeof value !== "string" || value.length === 0) {
+		throw new Error(`--${key} requires a value`);
+	}
+	return value;
+}
+
 function flagBool(flags: Record<string, string | boolean | string[]>, key: string): boolean {
 	return flags[key] === true || flags[key] === "true";
 }
@@ -83,20 +114,10 @@ function csvList(values: string[]): string[] {
 	return [...new Set(values.flatMap((value) => value.split(",")).map((value) => value.trim()).filter(Boolean))];
 }
 
-/** Build networks array from --add-network, --no-network, and legacy vmnet flags. */
+/** Build networks array from --add-network and --no-network. */
 function buildNetworks(flags: Record<string, string | boolean | string[]>): NetworkSpecifier[] | undefined {
 	const specs: NetworkSpecifier[] = [];
 
-	// Legacy flags first
-	if (flag(flags, "vmnet-shared") !== undefined) {
-		specs.push(parseNetworkSpecifier("shared"));
-	}
-	const bridgeIface = flag(flags, "vmnet-bridge");
-	if (bridgeIface) {
-		specs.push(parseNetworkSpecifier(`bridged:${bridgeIface}`));
-	}
-
-	// New --add-network flags
 	for (const raw of flagList(flags, "add-network")) {
 		specs.push(parseNetworkSpecifier(raw));
 	}
@@ -111,6 +132,28 @@ function buildNetworks(flags: Record<string, string | boolean | string[]>): Netw
 	return specs;
 }
 
+/** Exit with a flag-list error when a machine-creating command is given a flag it does
+ *  not know. An unrecognised flag is a typo, and a typo that downloads 43 MB and creates
+ *  a machine is not a good default (#156). */
+function rejectUnknownFlags(
+	flags: Record<string, string | boolean | string[]>,
+	known: readonly string[],
+	command: string,
+): void {
+	const unknown = unknownFlags(flags, known);
+	if (unknown.length > 0) {
+		console.error(unknownFlagMessage(unknown, command));
+		process.exit(1);
+	}
+	// A known flag given without its value is the same hazard wearing a valid name:
+	// `add --name --version 7.24.3` would otherwise create an auto-named machine.
+	const valueless = valuelessFlags(flags, known);
+	if (valueless.length > 0) {
+		console.error(valuelessFlagMessage(valueless, command));
+		process.exit(1);
+	}
+}
+
 /** True when interactive prompts must be suppressed (e.g. LLM / CI / pipe). */
 function isNoPrompt(): boolean {
 	return !!process.env.QUICKCHR_NO_PROMPT || !process.stdout.isTTY || !process.stdin.isTTY;
@@ -187,8 +230,30 @@ export async function resolveSecureLoginFlag(flags: Record<string, string | bool
 	return resolveSetting("secure-login").value === true ? true : undefined;
 }
 
+/** True when the user asked for help on this subcommand.
+ *
+ *  `--help` used to reach subcommands as an ordinary argument: `add --help` generated a
+ *  name and downloaded 43 MB, and `networks sockets create --help` persisted a socket
+ *  called `--help` (#156). Handling it here — before the dispatch — means a new
+ *  subcommand cannot miss the guard.
+ *
+ *  Everything after a bare `--` is the user's payload (a RouterOS command for `exec`),
+ *  so the scan stops there. */
+function wantsCommandHelp(argv: string[]): boolean {
+	for (const arg of argv) {
+		if (arg === "--") return false;
+		if (arg === "--help" || arg === "-h") return true;
+	}
+	return false;
+}
+
 async function main() {
 	try {
+		// Help before side effects — for every subcommand, present and future (#156).
+		if (command !== undefined && !command.startsWith("-") && wantsCommandHelp(args.slice(1))) {
+			printHelp(command);
+			return;
+		}
 		switch (command) {
 			case "add":
 				await cmdAdd(args.slice(1));
@@ -294,6 +359,7 @@ async function main() {
 			if (err.installHint) {
 				console.error(`  Hint: ${err.installHint}`);
 			}
+			for (const line of tipsForError(err.code, command)) tip(line);
 			if (err.code === "PROVISIONING_VERSION_UNSUPPORTED") {
 				console.error(`  Why this happened: ${provisioningSupportSummary(MIN_PROVISION_VERSION)}`);
 				console.error(`  ${PROVISIONING_BOOT_ONLY_SUMMARY}`);
@@ -552,6 +618,7 @@ function printMachineListWithTip(
 
 async function cmdAdd(argv: string[]) {
 	const { flags, positional } = parseFlags(argv);
+	rejectUnknownFlags(flags, ADD_FLAGS, "add");
 	const { QuickCHR } = await import("../lib/quickchr.ts");
 	const { bold, formatPorts, formatNetworks, dim } = await import("./format.ts");
 	const { resolveSetting } = await import("../lib/settings.ts");
@@ -656,6 +723,7 @@ async function cmdExec(argv: string[]) {
 		} else {
 			console.error("Usage: quickchr exec <name> <command...>\n  Run a RouterOS CLI command on a running instance.");
 		}
+		tip(CENTRS_EXEC_TIP);
 		process.exit(1);
 	}
 
@@ -1196,6 +1264,7 @@ async function cmdSetup() {
 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);
 
@@ -1479,8 +1548,13 @@ async function cmdList(argv: string[] = []) {
 
 	const { table, statusIcon, formatPorts, formatNetworks, dim } = await import("./format.ts");
 	const machines = QuickCHR.list();
+	// A machine whose state went bad keeps its place in the listing. It still holds a
+	// disk image, and `list` is where anyone looks first — deferring it to `doctor`
+	// assumes you already suspect trouble, which a quietly absent machine does not
+	// suggest. The listing itself succeeded, so the exit code stays 0 (#165).
+	const unreadable = QuickCHR.listUnreadable();
 
-	if (machines.length === 0) {
+	if (machines.length === 0 && unreadable.length === 0) {
 		if (asJson) {
 			console.log("[]");
 		} else {
@@ -1490,7 +1564,10 @@ async function cmdList(argv: string[] = []) {
 	}
 
 	if (asJson) {
-		console.log(JSON.stringify(machines, null, 2));
+		console.log(JSON.stringify([
+			...machines,
+			...unreadable.map((u) => ({ name: u.name, status: "unreadable", error: u.error })),
+		], null, 2));
 		return;
 	}
 
@@ -1504,8 +1581,17 @@ async function cmdList(argv: string[] = []) {
 		formatPorts(m.ports),
 		m.pid ? String(m.pid) : dim("—"),
 	]);
+	for (const u of unreadable) {
+		rows.push([statusIcon("error"), u.name, dim("unreadable"), dim("—"), dim("—"), dim("—"), dim("—")]);
+	}
 
 	console.log(table(headers, rows));
+
+	// The row says which machine; this says what to do about it, so neither takes a
+	// second command to learn.
+	for (const u of unreadable) {
+		console.log(`\n${statusIcon("error")} ${u.name}: machine.json unreadable — 'quickchr remove ${u.name}' to clear it`);
+	}
 }
 
 function shellQuoteEnv(value: string): string {
@@ -1713,8 +1799,21 @@ async function cmdRemove(argv: string[]) {
 		return;
 	}
 
-	const instance = QuickCHR.get(name);
+	// A machine.json that does not parse throws out of get(), because a lookup by name
+	// must not answer "no such machine" about a directory that exists (#165). `remove`
+	// is the command whose job is to clear that state, so here it routes into the
+	// orphan path below instead of surfacing the error (#155).
+	let instance: ReturnType<typeof QuickCHR.get> = null;
+	try {
+		instance = QuickCHR.get(name);
+	} catch { /* unreadable state → orphan */ }
 	if (!instance) {
+		// A half-created directory is unremovable any other way, and `remove` naming it
+		// in the "not found" list while refusing to delete it was the worst of both (#155).
+		if (QuickCHR.removeOrphan(name)) {
+			console.log(`${bold(name)} removed (leftover directory — no readable machine.json).`);
+			return;
+		}
 		console.error(machineNotFoundMessage(name));
 		process.exit(1);
 	}
@@ -2053,6 +2152,7 @@ async function cmdNetworks(argv: string[]) {
 async function showNetworkOverview() {
 	const { detectPlatform, detectPhysicalInterfaces } = await import("../lib/platform.ts");
 	const { listNamedSockets } = await import("../lib/socket-registry.ts");
+	const { describeSocketTransport } = await import("../lib/network.ts");
 	const { statusIcon, bold, dim } = await import("./format.ts");
 
 	const platform = await detectPlatform();
@@ -2126,7 +2226,8 @@ async function showNetworkOverview() {
 		console.log("  Named Sockets:");
 		for (const s of sockets) {
 			const members = s.members.length > 0 ? dim(`  members: ${s.members.join(", ")}`) : "";
-			console.log(`    ${s.name.padEnd(16)}${s.mode} port:${s.port}${members}`);
+			// Not `port:${s.port}` — a dgram link has no port and printed `port:undefined`.
+			console.log(`    ${s.name.padEnd(16)}${s.mode}  ${describeSocketTransport(s)}${members}`);
 		}
 	} else {
 		console.log("  Named Sockets:");
@@ -2153,8 +2254,11 @@ async function showInterfaces() {
 	console.log(table(["Device", "Name", "Alias", "MAC"], rows));
 }
 
+const SOCKET_MODES = ["dgram", "listen-connect", "mcast"] as const;
+
 async function handleSockets(argv: string[]) {
-	const { listNamedSockets, createNamedSocket, removeNamedSocket } = await import("../lib/socket-registry.ts");
+	const { listNamedSockets, createNamedSocket, removeNamedSocket, defaultSocketMode } = await import("../lib/socket-registry.ts");
+	const { describeSocketTransport } = await import("../lib/network.ts");
 	const { bold, dim, table: fmtTable } = await import("./format.ts");
 
 	const action = argv[0];
@@ -2168,22 +2272,73 @@ async function handleSockets(argv: string[]) {
 		const rows = sockets.map((s) => [
 			s.name,
 			s.mode,
-			String(s.port),
-			s.mcastGroup ?? "",
+			describeSocketTransport(s),
 			s.members.join(", ") || dim("none"),
 		]);
-		console.log(fmtTable(["Name", "Mode", "Port", "Group", "Members"], rows));
+		console.log(fmtTable(["Name", "Mode", "Transport", "Members"], rows));
 		return;
 	}
 
 	if (action === "create") {
-		const name = argv[1];
+		const { flags, positional } = parseFlags(argv.slice(1));
+		const name = positional[0];
 		if (!name) {
-			console.error("Usage: quickchr networks sockets create <name>");
+			console.error("Usage: quickchr networks sockets create <name> [--mode dgram|listen-connect|mcast] [--port <n>] [--group <addr>]");
 			process.exit(1);
 		}
-		const entry = createNamedSocket(name);
-		console.log(`Created named socket: ${bold(entry.name)} (${entry.mode} port:${entry.port})`);
+		// `parseFlags` stores `true` for a flag with no value and `flag()` turns that back
+		// into `undefined`, so a bare `--mode` would silently fall through to the default
+		// — the same shape as #156's valueless-flag bug.
+		for (const key of ["mode", "port", "group"]) {
+			if (typeof flags[key] === "boolean") {
+				console.error(`Error: --${key} requires a value.`);
+				process.exit(1);
+			}
+		}
+		const mode = flag(flags, "mode");
+		if (mode !== undefined && !(SOCKET_MODES as readonly string[]).includes(mode)) {
+			console.error(`Error: unknown --mode "${mode}" — expected one of ${SOCKET_MODES.join(", ")}.`);
+			process.exit(1);
+		}
+		const portRaw = flag(flags, "port");
+		// Number(), not parseInt(): parseInt stops at the first non-digit, so "4000abc"
+		// came through as 4000.
+		const port = portRaw === undefined ? undefined : Number(portRaw);
+		if (portRaw !== undefined && (!/^\d+$/.test(portRaw) || !Number.isInteger(port) || (port as number) < 1 || (port as number) > 65535)) {
+			console.error(`Error: --port must be a number between 1 and 65535, got "${portRaw}".`);
+			process.exit(1);
+		}
+		const group = flag(flags, "group");
+		const effectiveMode = mode ?? defaultSocketMode();
+		if (group !== undefined && effectiveMode !== "mcast") {
+			console.error(`Error: --group only applies to --mode mcast (this socket is ${effectiveMode}).`);
+			process.exit(1);
+		}
+		if (portRaw !== undefined && effectiveMode === "dgram") {
+			console.error("Error: --port does not apply to --mode dgram — a unix datagram pair uses no port.");
+			process.exit(1);
+		}
+		const entry = createNamedSocket(name, {
+			mode: mode as (typeof SOCKET_MODES)[number] | undefined,
+			port,
+			mcastGroup: group,
+		});
+		console.log(`Created named socket: ${bold(entry.name)} (${entry.mode})`);
+		console.log(`  Transport: ${describeSocketTransport(entry)}`);
+		if (entry.mode === "mcast") {
+			// The caveat belongs at create time, not in a doc: mcast fails with no error
+			// anywhere — interfaces up, addresses assigned, 100% loss. Three distinct
+			// hazards, not one (#167): a macOS delivery bug, a sandbox permission block,
+			// and — because quickchr passes no localaddr= — a group that rides the host's
+			// default interface rather than loopback.
+			console.log(dim("  Note: UDP multicast is the only N-way segment, and the only one that"));
+			console.log(dim("        fails silently. It does not deliver on macOS, and it is refused"));
+			console.log(dim("        in sandboxes that block unconnected UDP sends (some Linux CI)."));
+			console.log(dim(`        This group is not confined to loopback: ${entry.mcastGroup} rides the host's`));
+			console.log(dim("        default multicast interface, so another machine on your LAN using"));
+			console.log(dim("        the same group joins this segment. Use a unique group, or prefer"));
+			console.log(dim("        'dgram' for two machines."));
+		}
 		return;
 	}
 
@@ -2217,6 +2372,21 @@ Usage:
   quickchr networks sockets create <n>  Create a named socket
   quickchr networks sockets remove <n>  Remove a named socket
 
+Socket create options:
+  --mode <mode>    dgram | listen-connect | mcast
+                   Default: dgram (POSIX), listen-connect (Windows)
+  --port <n>       TCP/UDP port for listen-connect and mcast
+  --group <addr>   Multicast group for --mode mcast (default 230.0.0.1)
+
+Transports:
+  dgram            A pair of unix datagram sockets. No ports, no UDP syscalls,
+                   and either machine may start first. Two machines. POSIX only.
+  listen-connect   A TCP pair on loopback. Two machines; the first to join takes
+                   the listening end and keeps it, and must be started first
+                   thereafter. The Windows default.
+  mcast            UDP multicast — the only N-way segment, but broken on macOS
+                   and in UDP-blocked sandboxes, and silent when it fails.
+
 Aliases: quickchr net`);
 }
 
@@ -2418,6 +2588,45 @@ async function cmdCache(argv: string[]) {
 	};
 
 	switch (sub) {
+		case "add": {
+			const { cacheAdd } = await import("../lib/cache-api.ts");
+			const { resolveSetting } = await import("../lib/settings.ts");
+			const version = cacheTargetFlag(flags, "version");
+			const explicitChannel = cacheTargetFlag(flags, "channel") as Channel | undefined;
+			const channel = version !== undefined || explicitChannel !== undefined
+				? explicitChannel
+				: resolveSetting("default-channel").value as Channel;
+			const arch = (cacheTargetFlag(flags, "arch") ?? resolveSetting("default-arch").value) as Arch | "auto";
+			const asJson = flagBool(flags, "json");
+			const quiet = { status() {}, debug() {}, warn() {} };
+			const result = await cacheAdd({ version, channel, arch, logger: asJson ? quiet : undefined });
+			if (asJson) {
+				console.log(JSON.stringify(result));
+			} else {
+				console.log(`${result.cacheHit ? "Already cached" : "Cached"}: RouterOS ${result.version} (${result.arch})`);
+				console.log(`Path: ${result.path}`);
+			}
+			break;
+		}
+		case "key": {
+			const { cacheKey } = await import("../lib/cache-api.ts");
+			const version = cacheTargetFlag(flags, "version");
+			const explicitChannel = cacheTargetFlag(flags, "channel") as Channel | undefined;
+			const { resolveSetting } = await import("../lib/settings.ts");
+			const channel = version !== undefined || explicitChannel !== undefined
+				? explicitChannel
+				: resolveSetting("default-channel").value as Channel;
+			const arch = (cacheTargetFlag(flags, "arch") ?? resolveSetting("default-arch").value) as Arch | "auto";
+			const result = await cacheKey({ version, channel, arch });
+			if (flagBool(flags, "json")) {
+				console.log(JSON.stringify(result));
+			} else {
+				console.log(`dir=${result.dir}`);
+				console.log(`version=${result.version}`);
+				console.log(`arch=${result.arch}`);
+			}
+			break;
+		}
 		case "list":
 		case "ls": {
 			const entries = listCacheEntries();
@@ -2695,6 +2904,7 @@ Commands:
   env <name> [--json]     Print subprocess environment for a running machine
   console <name>          Attach to serial console of a running instance
   exec <name> <command>   Run a RouterOS CLI command on a running instance
+                          (raw /rest/execute — see 'quickchr exec --help' for centrs)
   remove [<name>|--all]   Remove instance(s) and disk
   clean [<name>|--all]    Reset instance disk to fresh image
   get <name> [group]          Show machine config (license, device-mode, admin)
@@ -2703,7 +2913,7 @@ Commands:
   disk <name>             Show disk details for an instance
   snapshot <name> [cmd]   Manage snapshots (list/save/load/delete)
   networks                Network discovery & socket management
-  cache [list|prune|clear] Manage cached CHR images
+  cache [add|key|list|prune|clear] Manage cached CHR images
   settings [print|get|set|reset]  Manage quickchr's own global settings (quickchr.env)
   completions             Manage shell completions (Tab completion)
   logs <name>             Tail the QEMU log for an instance
@@ -2768,9 +2978,7 @@ Options:
   --device-mode <m>     Set device-mode on first boot: rose|advanced|basic|home|auto|skip
   --add-network <spec>  Add a network NIC (repeatable). Specs: user, shared, bridged:<if>,
                         socket::<name>, tap:<if>. Default: single user NIC.
-  --no-network          Start with no NICs (headless)
-  --vmnet-shared        [deprecated] Use --add-network shared
-  --vmnet-bridge <if>   [deprecated] Use --add-network bridged:<if>`);
+  --no-network          Start with no NICs (headless)`);
 			break;
 		case "setup":
 			console.log(`quickchr setup
@@ -2802,7 +3010,9 @@ Options:
 Examples:
   quickchr exec my-chr /system/resource/print
   quickchr exec my-chr ":put [:serialize to=json [/ip/address/print]]"
-  quickchr exec my-chr "/log/info message=hello"`);
+  quickchr exec my-chr "/log/info message=hello"
+
+${CENTRS_SEE_ALSO}`);
 			break;
 		case "start":
 			console.log(`quickchr start [<name>] [options]
@@ -2849,8 +3059,6 @@ Options:
   --add-network <spec>  Add a network NIC (repeatable). Specs: user, shared, bridged:<if>,
                         socket::<name>, tap:<if>. Default: single user NIC.
   --no-network          Start with no NICs (headless)
-  --vmnet-shared        [deprecated] Use --add-network shared
-  --vmnet-bridge <if>   [deprecated] Use --add-network bridged:<if>
   --install-all-packages  Install all packages from all_packages.zip
   --license-level <l>   Apply trial license: p1 (1 Gbps), p10 (10 Gbps), unlimited
   --license-account <a> MikroTik account email (or use MIKROTIK_WEB_ACCOUNT env var)
@@ -2875,6 +3083,7 @@ Options:
 Alias for 'quickchr list'. See 'quickchr help list'.`);
 			break;
 		case "list":
+		case "ls":
 			console.log(`quickchr list [<name>] [--json]
 
 List all CHR instances or show detailed info for one.
@@ -3028,6 +3237,14 @@ Credential resolution order (highest priority first):
   3. OS native secret store (macOS Keychain, Linux GNOME Keyring, Windows Credential Manager)
   4. ~/.config/quickchr/credentials.json (fallback)`);
 			break;
+		case "qga":
+			console.log(`quickchr qga <name> <operation> [options]
+
+Query the QEMU Guest Agent on a running CHR instance.
+QGA is x86-only — the arm64 CHR image does not start the guest agent.
+
+Run 'quickchr qga <name>' with no operation to list every operation.`);
+			break;
 		case "clean":
 			console.log(`quickchr clean [<name>] [--all]
 
@@ -3036,6 +3253,7 @@ Credential resolution order (highest priority first):
   --all       Clean all instances.`);
 			break;
 		case "remove":
+		case "rm":
 			console.log(`quickchr remove [<name>] [--all]
 
   <name>      Remove an instance (stops if running, deletes disk and state).
@@ -3057,11 +3275,16 @@ Options:
 			showNetworksHelp();
 			break;
 		case "cache":
-			console.log(`quickchr cache <list|prune|clear> [options]
+			console.log(`quickchr cache <add|key|list|prune|clear> [options]
 
 Manage cached CHR images in the data dir cache directory.
 
 Subcommands:
+  add [--channel <ch> | --version <ver>] [--arch <arch>] [--json]
+                                      Resolve, download, and cache one CHR image without booting.
+  key [--channel <ch> | --version <ver>] [--arch <arch>] [--json]
+                                      Print cache directory, resolved version, and architecture for CI.
+                                      Without --json, output is GITHUB_OUTPUT-compatible key=value lines.
   list [--json]                       List cached images (basename, version, arch, size, age, in-use).
   prune [options]                     Evict cached images per policy. Never evicts in-use images.
     --older-than <ver>                Evict images with version < <ver>.
@@ -3110,6 +3333,7 @@ Credentials (--add-user, MIKROTIK_WEB_ACCOUNT/PASSWORD) are never stored here.`)
 			break;
 		default:
 			console.log(`No detailed help for '${command}'.`);
+			console.log("Run 'quickchr help' for the command list.");
 	}
 }
 

package/src/cli/tips.ts

@@ -0,0 +1,57 @@
+/**
+ * Tips — short, dim, one-line pointers at the thing that would have gone better.
+ *
+ * Three rules, so tips stay useful instead of becoming chrome:
+ *
+ * 1. **stderr, always.** stdout is the command's result and has to stay parseable:
+ *    `quickchr inspect --json | jq` must not have to filter advice out of its input.
+ * 2. **A tip names a next command or a better-suited tool.** It never restates what
+ *    just happened, and it never appears where the command already said the thing.
+ * 3. **Suppressible.** `QUICKCHR_NO_TIPS=1` silences them. Not gated on TTY: the
+ *    audience for "you probably wanted X" is agents and first-time users, both of
+ *    which usually run without one.
+ */
+
+/** Where quickchr stops and a validating RouterOS client starts.
+ *
+ *  quickchr's `exec` is a thin `/rest/execute` pipe: it will happily send a command
+ *  RouterOS rejects, and hand back the rejection. centrs validates a RouterOS-shaped
+ *  command before running it and has a per-verb help system — the difference between
+ *  one round trip and five. It takes a verb first (`retrieve` to read, `execute` to
+ *  write, `explain` to analyze without running) and resolves the machine through
+ *  `quickchr inspect`; see docs/centrs-interface.md. */
+export const CENTRS_EXEC_TIP =
+	"centrs validates RouterOS commands before running them: centrs execute --quickchr <name> <command>";
+
+/** The same pointer, as a help-text block. Help is where a reader is already asking
+ *  "what should I use for this?", so it gets the fuller version. */
+export const CENTRS_SEE_ALSO = `See also — centrs (@tikoci/centrs) validates a RouterOS-shaped command
+before running it, and has per-verb help. 'quickchr exec' does not: it is a
+raw /rest/execute pipe, and whatever you type is what RouterOS is asked to run.
+
+  centrs retrieve --quickchr <name> /system/resource    Read state
+  centrs execute  --quickchr <name> <command>           Run a read/write command
+  centrs explain  <command>                             Analyze without running it
+
+centrs resolves the machine through 'quickchr inspect' — it never reads machine.json.
+Install: bun add -g @tikoci/centrs`;
+
+/** True when tips are switched off for this run. */
+export function tipsSuppressed(): boolean {
+	const value = process.env.QUICKCHR_NO_TIPS;
+	return value !== undefined && value !== "" && value !== "0";
+}
+
+/** Print one tip line to stderr. No-op when tips are suppressed. */
+export function tip(line: string): void {
+	if (tipsSuppressed()) return;
+	const dim = process.env.NO_COLOR ? (s: string) => s : (s: string) => `\x1b[2m${s}\x1b[0m`;
+	console.error(dim(`tip: ${line}`));
+}
+
+/** Tips that belong with a specific error code, printed by the CLI's error handler.
+ *  `command` is the subcommand that failed, so a tip can stay scoped to where it helps. */
+export function tipsForError(code: string, command?: string): string[] {
+	if (code === "EXEC_FAILED" && command === "exec") return [CENTRS_EXEC_TIP];
+	return [];
+}

package/src/index.ts

@@ -71,6 +71,16 @@ export type {
 export { QuickCHRError, SERVICE_IDS, QUICKCHR_DESCRIPTOR_VERSION } from "./lib/types.ts";
 export type { ErrorCode, HostInterface } from "./lib/types.ts";
 
+// Cache utilities
+export { cacheAdd, cacheKey, CACHE_VERSION_UNRESOLVED } from "./lib/cache-api.ts";
+export type {
+	CacheAddOptions,
+	CacheAddResult,
+	CacheKeyResult,
+	CacheTargetOptions,
+	CacheVersionResolver,
+} from "./lib/cache-api.ts";
+
 // Interface detection
 export { detectPhysicalInterfaces, resolveInterfaceAlias } from "./lib/platform.ts";
 
@@ -108,6 +118,7 @@ export type { QgaCommandInfo } from "./lib/qga.ts";
 
 // Console exec utilities
 export { consoleExec, isConsoleReady, stripAnsi } from "./lib/console.ts";
+export type { ConsoleExecResult } from "./lib/console.ts";
 
 // Channel utilities
 export { isQgaReady } from "./lib/channels.ts";