@tikoci/quickchr 0.4.7 → 0.5.0

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/cli/wizard.ts

@@ -81,6 +81,11 @@ export async function runWizard(wizardOpts?: { firstRun?: boolean }): Promise<vo
 				if (!/^\d+\.\d+(\.\d+)?(beta\d+|rc\d+)?$/.test(v)) {
 					return "Invalid version format";
 				}
+				// RouterOS 6 is a CLI-only boot target (#182) — the wizard offers
+				// provisioning at every step, none of which 6.x can take.
+				if (/^6\./.test(v)) {
+					return "RouterOS 6 is boot-only and not offered here — use: quickchr add --version <6.x> --arch x86";
+				}
 			},
 		});
 		if (clack.isCancel(ver)) { clack.cancel("Cancelled."); process.exit(0); }
@@ -557,7 +562,8 @@ export async function runWizard(wizardOpts?: { firstRun?: boolean }): Promise<vo
 	const background = await clack.select({
 		message: "Run mode:",
 		options: [
-			{ value: true, label: "Background", hint: "returns immediately" },
+			// Not "returns immediately": a background start waits for RouterOS to be ready (#159).
+			{ value: true, label: "Background", hint: "console logged; returns when RouterOS is ready" },
 			{ value: false, label: "Foreground", hint: "serial console on stdio" },
 		],
 		initialValue: true,
@@ -566,8 +572,10 @@ export async function runWizard(wizardOpts?: { firstRun?: boolean }): Promise<vo
 
 	// 11. Confirm
 	const opts: StartOptions = {
+		// The channel has already been resolved into `version` above; passing both reads
+		// to start() as a caller asking for two releases.
 		version,
-		channel,
+		channel: version ? undefined : channel,
 		arch,
 		name: name || undefined,
 		cpu: Number(cpu),

package/src/index.ts

@@ -64,6 +64,8 @@ export type {
 	ServiceEndpoint,
 	ServiceName,
 	SnapshotInfo,
+	ShutdownOptions,
+	ShutdownResult,
 	SshServiceEndpoint,
 	StartOptions,
 } from "./lib/types.ts";
@@ -71,6 +73,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";
 

package/src/lib/api-login.ts

@@ -0,0 +1,138 @@
+/**
+ * Native API (`/login` on guest port 8728) as a readiness signal.
+ *
+ * Built for RouterOS 6, which has no REST API, so the REST probe can never succeed
+ * against it — the field report behind #182 watched a 6.49 guest answer www, ssh and
+ * api from 15 s in, then get removed at 180 s for not answering `/rest`. It is written
+ * as a general alternative to the REST probe rather than a v6 special case: a 7.x
+ * guest with REST disabled is the same problem.
+ *
+ * Only the post-6.43 plain login is spoken (`=name=` + `=password=` in one sentence).
+ * Grounded against CHR 6.49.23 under HVF, 2026-10-21:
+ *
+ * - `admin` / empty password → `!done`, as one 7-byte reply.
+ * - wrong user or password → `!trap =message=invalid user name or password (6)`
+ *   followed by `!done`, in the same read.
+ *
+ * Either answer means the API service is up, the way a REST 401 does — the probe is a
+ * readiness check, not a credential check.
+ */
+
+import { connect } from "node:net";
+
+/** Encode one API word length (RouterOS API "length" prefix, 1–5 bytes). */
+export function encodeApiLength(length: number): Uint8Array {
+	if (length < 0x80) return Uint8Array.of(length);
+	if (length < 0x4000) return Uint8Array.of((length >> 8) | 0x80, length & 0xff);
+	if (length < 0x200000) return Uint8Array.of((length >> 16) | 0xc0, (length >> 8) & 0xff, length & 0xff);
+	if (length < 0x10000000) {
+		return Uint8Array.of((length >>> 24) | 0xe0, (length >> 16) & 0xff, (length >> 8) & 0xff, length & 0xff);
+	}
+	return Uint8Array.of(0xf0, (length >>> 24) & 0xff, (length >> 16) & 0xff, (length >> 8) & 0xff, length & 0xff);
+}
+
+/** A sentence is its words, each length-prefixed, then a zero-length word. */
+export function encodeApiSentence(words: string[]): Uint8Array {
+	const encoder = new TextEncoder();
+	const parts: Uint8Array[] = [];
+	for (const word of words) {
+		const bytes = encoder.encode(word);
+		parts.push(encodeApiLength(bytes.length), bytes);
+	}
+	parts.push(Uint8Array.of(0));
+	const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+	let offset = 0;
+	for (const part of parts) {
+		out.set(part, offset);
+		offset += part.length;
+	}
+	return out;
+}
+
+/** Decode a length prefix at `offset`. `null` when the buffer ends inside it. */
+function decodeApiLength(buf: Uint8Array, offset: number): { length: number; size: number } | null {
+	const first = buf[offset];
+	if (first === undefined) return null;
+	const size = (first & 0x80) === 0 ? 1
+		: (first & 0xc0) === 0x80 ? 2
+		: (first & 0xe0) === 0xc0 ? 3
+		: (first & 0xf0) === 0xe0 ? 4
+		: 5;
+	if (offset + size > buf.length) return null;
+	let length = size === 5 ? 0 : first & (0xff >> size);
+	for (let i = 1; i < size; i++) length = length * 256 + (buf[offset + i] ?? 0);
+	return { length, size };
+}
+
+/** Every complete sentence in `buf`; a trailing partial sentence is left out. */
+export function parseApiSentences(buf: Uint8Array): string[][] {
+	const decoder = new TextDecoder();
+	const sentences: string[][] = [];
+	let words: string[] = [];
+	let offset = 0;
+	while (offset < buf.length) {
+		const prefix = decodeApiLength(buf, offset);
+		if (!prefix || offset + prefix.size + prefix.length > buf.length) break;
+		offset += prefix.size;
+		if (prefix.length === 0) {
+			sentences.push(words);
+			words = [];
+			continue;
+		}
+		words.push(decoder.decode(buf.subarray(offset, offset + prefix.length)));
+		offset += prefix.length;
+	}
+	return sentences;
+}
+
+export type ApiLoginResult =
+	/** `!done` with no `!trap` — logged in. */
+	| { outcome: "done" }
+	/** `!trap` then `!done` — the service answered and refused the credentials. */
+	| { outcome: "trap"; message: string }
+	/** `!fatal` — the service answered and closed the session (e.g. too many sessions). */
+	| { outcome: "fatal"; message: string };
+
+/** What the reply sentences say, once a `!done` or `!fatal` has arrived. `null` while
+ *  the login is still unanswered. */
+export function classifyLoginReply(sentences: string[][]): ApiLoginResult | null {
+	const messageOf = (sentence: string[]) =>
+		sentence.find((w) => w.startsWith("=message="))?.slice("=message=".length) ?? sentence.slice(1).join(" ");
+	const fatal = sentences.find((s) => s[0] === "!fatal");
+	if (fatal) return { outcome: "fatal", message: messageOf(fatal) };
+	if (!sentences.some((s) => s[0] === "!done")) return null;
+	const trap = sentences.find((s) => s[0] === "!trap");
+	return trap ? { outcome: "trap", message: messageOf(trap) } : { outcome: "done" };
+}
+
+/** One `/login` round trip on `127.0.0.1:<port>`. Rejects on a socket error, on a close
+ *  before the reply completes ("closed before reply"), and on the deadline
+ *  ("apiLogin timeout") — the shapes `classifyProbeError()` sorts into outcomes. */
+export function apiLogin(port: number, user: string, password: string, timeoutMs = 3000): Promise<ApiLoginResult> {
+	return new Promise((resolve, reject) => {
+		const socket = connect(port, "127.0.0.1");
+		let received = new Uint8Array(0);
+		let settled = false;
+		const finish = (fn: () => void) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			socket.destroy();
+			fn();
+		};
+		const timer = setTimeout(() => finish(() => reject(new Error("apiLogin timeout"))), timeoutMs);
+		socket.on("connect", () => {
+			socket.write(encodeApiSentence(["/login", `=name=${user}`, `=password=${password}`]));
+		});
+		socket.on("data", (chunk: Uint8Array) => {
+			const next = new Uint8Array(received.length + chunk.length);
+			next.set(received);
+			next.set(chunk, received.length);
+			received = next;
+			const result = classifyLoginReply(parseApiSentences(received));
+			if (result) finish(() => resolve(result));
+		});
+		socket.on("error", (err) => finish(() => reject(err)));
+		socket.on("close", () => finish(() => reject(new Error("closed before reply"))));
+	});
+}

package/src/lib/cache-api.ts

@@ -0,0 +1,146 @@
+/** Public cache operations for CI consumers and the quickchr CLI. */
+
+import { join } from "node:path";
+import { ensureCachedImage, isUsableCachedImage } from "./images.ts";
+import type { ProgressLogger } from "./log.ts";
+import { getCacheDir } from "./state.ts";
+import { ARCHES, CHANNELS, QuickCHRError, type Arch, type Channel } from "./types.ts";
+import { chrImageBasename, isValidVersion, resolveVersion } from "./versions.ts";
+
+export const CACHE_VERSION_UNRESOLVED = "unresolved";
+const CACHE_VERSION_MAX_LENGTH = 32;
+
+export interface CacheTargetOptions {
+	/** Resolve this RouterOS channel. Mutually exclusive with `version`. */
+	channel?: Channel;
+	/** Use this concrete RouterOS version without a network resolution request. */
+	version?: string;
+	/** Override the cache directory. Defaults to quickchr's platform-correct cache. */
+	cacheDir?: string;
+	/** CHR architecture. `auto` and omission select the Bun process architecture. */
+	arch?: Arch | "auto";
+}
+
+export interface CacheKeyResult {
+	dir: string;
+	/** Concrete RouterOS version, or `unresolved` when channel resolution is offline. */
+	version: string;
+	arch: Arch;
+}
+
+export interface CacheAddOptions extends CacheTargetOptions {
+	logger?: ProgressLogger;
+}
+
+export interface CacheAddResult extends CacheKeyResult {
+	path: string;
+	cacheHit: boolean;
+}
+
+export type CacheVersionResolver = (channel: Channel) => Promise<string>;
+
+function validateTarget(options: CacheTargetOptions): { channel?: Channel; version?: string } {
+	if (options.channel !== undefined && options.version !== undefined) {
+		throw new QuickCHRError("INVALID_VERSION", "Choose either a RouterOS channel or a concrete version, not both");
+	}
+	if (options.channel !== undefined && !(CHANNELS as readonly string[]).includes(options.channel)) {
+		throw new QuickCHRError(
+			"INVALID_VERSION",
+			`Invalid RouterOS channel "${options.channel}" — expected one of ${CHANNELS.join(", ")}`,
+		);
+	}
+	if (options.version !== undefined && !isValidVersion(options.version)) {
+		throw new QuickCHRError("INVALID_VERSION", `Invalid RouterOS version: ${options.version}`);
+	}
+	return { channel: options.channel, version: options.version };
+}
+
+async function concreteVersion(
+	options: CacheTargetOptions,
+	resolver: CacheVersionResolver,
+): Promise<{ channel?: Channel; version: string }> {
+	const target = validateTarget(options);
+	if (target.version !== undefined) return { version: target.version };
+	const channel = target.channel ?? "stable";
+	const version = await resolver(channel);
+	if (!isValidVersion(version)) {
+		throw new QuickCHRError(
+			"INVALID_VERSION",
+			`Unexpected version "${version}" resolved for channel "${channel}"`,
+		);
+	}
+	return { channel, version };
+}
+
+function concreteArch(arch: Arch | "auto" | undefined): Arch {
+	if (arch === undefined || arch === "auto") return process.arch === "arm64" ? "arm64" : "x86";
+	if (!(ARCHES as readonly string[]).includes(arch)) {
+		throw new QuickCHRError("INVALID_ARCH", `Invalid architecture "${arch}" — expected one of ${ARCHES.join(", ")}, auto`);
+	}
+	return arch;
+}
+
+/**
+ * Return quickchr's cache directory and the concrete version for a CI key.
+ *
+ * An explicit version is validated and returned without a network call. A
+ * channel resolution failure degrades to the stable `unresolved` sentinel so
+ * cache lookup cannot make an otherwise useful offline job fail.
+ */
+export async function cacheKey(
+	options: CacheTargetOptions = {},
+	resolver: CacheVersionResolver = resolveVersion,
+): Promise<CacheKeyResult> {
+	const target = validateTarget(options);
+	const dir = options.cacheDir ?? getCacheDir();
+	const arch = concreteArch(options.arch);
+	if (target.version !== undefined) {
+		return {
+			dir,
+			version: target.version.length <= CACHE_VERSION_MAX_LENGTH ? target.version : CACHE_VERSION_UNRESOLVED,
+			arch,
+		};
+	}
+	try {
+		const resolved = await concreteVersion(options, resolver);
+		return {
+			dir,
+			version: resolved.version.length <= CACHE_VERSION_MAX_LENGTH ? resolved.version : CACHE_VERSION_UNRESOLVED,
+			arch,
+		};
+	} catch (error) {
+		if (error instanceof QuickCHRError && error.code === "DOWNLOAD_FAILED") {
+			return { dir, version: CACHE_VERSION_UNRESOLVED, arch };
+		}
+		throw error;
+	}
+}
+
+/** Resolve and cache one CHR image without creating or booting a machine. */
+export async function cacheAdd(
+	options: CacheAddOptions = {},
+	resolver: CacheVersionResolver = resolveVersion,
+): Promise<CacheAddResult> {
+	const resolved = await concreteVersion(options, resolver);
+	if (resolved.version.length > CACHE_VERSION_MAX_LENGTH) {
+		throw new QuickCHRError("INVALID_VERSION", `RouterOS version is too long: ${resolved.version}`);
+	}
+	const arch = concreteArch(options.arch);
+	const dir = options.cacheDir ?? getCacheDir();
+	const expectedPath = join(dir, `${chrImageBasename(resolved.version, arch)}.img`);
+	const cacheHit = await isUsableCachedImage(expectedPath);
+
+	try {
+		const path = await ensureCachedImage(resolved.version, arch, dir, options.logger);
+		return { dir, version: resolved.version, arch, path, cacheHit };
+	} catch (error) {
+		if (resolved.channel && error instanceof QuickCHRError) {
+			throw new QuickCHRError(
+				error.code,
+				`Failed to cache channel "${resolved.channel}" -> ${resolved.version} (${arch}): ${error.message}`,
+				error.installHint,
+			);
+		}
+		throw error;
+	}
+}

package/src/lib/completions.ts

@@ -328,7 +328,7 @@ _quickchr() {
         cword=${D}COMP_CWORD
     }
 
-    local commands="add start stop list ls status inspect env remove rm clean console exec qga license disk snapshot snap networks net doctor settings setup completions version help"
+    local commands="add start stop shutdown list ls status inspect env get set remove rm clean console exec qga license disk snapshot snap networks net cache doctor settings setup completions version help"
 
     if [[ ${D}cword -eq 1 ]]; then
         COMPREPLY=( $(compgen -W "${D}commands" -- "${D}cur") )
@@ -337,12 +337,12 @@ _quickchr() {
 
     local cmd="${D}{words[1]}"
     case "${D}cmd" in
-        start|remove|rm|clean|console|exec|qga|license|disk|snapshot|snap|status|inspect|env)
+        start|remove|rm|clean|console|exec|qga|license|disk|snapshot|snap|status|inspect|env|get|set)
             local machines
             machines=$(quickchr completions --machines 2>/dev/null)
             COMPREPLY=( $(compgen -W "${D}machines" -- "${D}cur") )
             ;;
-        stop)
+        stop|shutdown)
             local machines
             machines=$(quickchr completions --running 2>/dev/null)
             [[ -z "${D}machines" ]] && machines=$(quickchr completions --machines 2>/dev/null)
@@ -352,6 +352,10 @@ _quickchr() {
             local opts="--install --uninstall --status --dry-run --shell"
             COMPREPLY=( $(compgen -W "${D}opts" -- "${D}cur") )
             ;;
+        cache)
+            local opts="add key list prune clear"
+            COMPREPLY=( $(compgen -W "${D}opts" -- "${D}cur") )
+            ;;
         help)
             COMPREPLY=( $(compgen -W "${D}commands" -- "${D}cur") )
             ;;
@@ -383,12 +387,15 @@ _quickchr() {
             local commands=(
                 'add:Create a new CHR machine (without starting)'
                 'start:Start or restart a CHR instance'
-                'stop:Stop instance(s)'
+                'stop:Power cut instance(s)'
+                'shutdown:Request guest shutdown'
                 'list:List all instances'
                 'ls:List all instances (alias)'
                 'status:Detailed status'
                 'inspect:Print running machine descriptor'
                 'env:Print subprocess environment'
+                'get:Show live machine config (license, device-mode, admin)'
+                'set:Change a booted machine (license, device-mode)'
                 'remove:Remove instance(s) and disk'
                 'rm:Remove instance(s) (alias)'
                 'clean:Reset instance disk to fresh image'
@@ -401,6 +408,7 @@ _quickchr() {
                 'snap:Manage snapshots (alias)'
                 'networks:Network discovery and socket management'
                 'net:Network discovery (alias)'
+                'cache:Prefetch and manage downloaded CHR images'
                 'doctor:Check prerequisites'
                 'settings:Manage global quickchr settings'
                 'setup:Interactive setup wizard'
@@ -413,12 +421,12 @@ _quickchr() {
         args)
             local cmd="${D}{words[2]}"
             case ${D}cmd in
-                start|remove|rm|clean|console|exec|qga|license|disk|snapshot|snap|status|inspect|env)
+                start|remove|rm|clean|console|exec|qga|license|disk|snapshot|snap|status|inspect|env|get|set)
                     local machines
                     machines=(${D}{(f)"${D}(quickchr completions --machines 2>/dev/null)"})
                     _describe 'machine' machines
                     ;;
-                stop)
+                stop|shutdown)
                     local machines
                     machines=(${D}{(f)"${D}(quickchr completions --running 2>/dev/null)"})
                     (( ${D}{#machines} == 0 )) && machines=(${D}{(f)"${D}(quickchr completions --machines 2>/dev/null)"})
@@ -434,8 +442,12 @@ _quickchr() {
                     )
                     _describe 'option' opts
                     ;;
+                cache)
+                    local subcommands=(add key list prune clear)
+                    _describe 'cache subcommand' subcommands
+                    ;;
                 help)
-                    local commands=(add start stop list status inspect env remove clean console exec qga license disk snapshot networks doctor settings setup completions version)
+                    local commands=(add start stop shutdown list status inspect env get set remove clean console exec qga license disk snapshot networks cache doctor settings setup completions version)
                     _describe 'command' commands
                     ;;
             esac
@@ -451,7 +463,7 @@ function generateFishCompletion(): string {
 	return `# quickchr fish completion
 # Generated by quickchr. Fish auto-loads files from ~/.config/fish/completions/.
 
-set -l quickchr_commands add start stop list ls status inspect env remove rm clean console exec qga license disk snapshot snap networks net doctor settings setup completions version help
+set -l quickchr_commands add start stop shutdown list ls status inspect env get set remove rm clean console exec qga license disk snapshot snap networks net cache doctor settings setup completions version help
 
 # Disable file completions globally for quickchr
 complete -c quickchr -f
@@ -462,7 +474,9 @@ complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
     -a "start"       -d "Start or restart a CHR instance"
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
-    -a "stop"        -d "Stop instance(s)"
+    -a "stop"        -d "Power cut instance(s)"
+complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
+    -a "shutdown"    -d "Request guest shutdown"
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
     -a "list ls"     -d "List all instances"
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
@@ -482,6 +496,10 @@ complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
     -a "qga"         -d "Guest agent command"
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
+    -a "get"         -d "Show live machine config (license, device-mode, admin)"
+complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \
+    -a "set"         -d "Change a booted machine (license, device-mode)"
+complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \
     -a "license"     -d "Apply/renew CHR trial license"
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
     -a "disk"        -d "Show disk details"
@@ -489,6 +507,8 @@ complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
     -a "snapshot snap" -d "Manage snapshots"
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
     -a "networks net" -d "Network discovery and socket management"
+complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
+    -a "cache"       -d "Prefetch and manage downloaded CHR images"
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
     -a "doctor"      -d "Check prerequisites"
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
@@ -503,12 +523,12 @@ complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
     -a "help"        -d "Show help"
 
 # Machine name completions for commands that take a running machine
-complete -c quickchr -n "__fish_seen_subcommand_from stop" \\
+complete -c quickchr -n "__fish_seen_subcommand_from stop shutdown" \\
     -a "(quickchr completions --running 2>/dev/null; or quickchr completions --machines 2>/dev/null)" \\
     -d "machine"
 
 # Machine name completions for commands that take any machine
-complete -c quickchr -n "__fish_seen_subcommand_from start remove rm clean console exec qga license disk snapshot snap status inspect env" \\
+complete -c quickchr -n "__fish_seen_subcommand_from start remove rm clean console exec qga license disk snapshot snap status inspect env get set" \\
     -a "(quickchr completions --machines 2>/dev/null)" \\
     -d "machine"
 
@@ -518,5 +538,8 @@ complete -c quickchr -n "__fish_seen_subcommand_from completions" -l uninstall -
 complete -c quickchr -n "__fish_seen_subcommand_from completions" -l status    -d "Show install status"
 complete -c quickchr -n "__fish_seen_subcommand_from completions" -l dry-run   -d "Show what would happen"
 complete -c quickchr -n "__fish_seen_subcommand_from completions" -l shell     -d "Specify shell" -a "bash zsh fish"
+
+# cache subcommands
+complete -c quickchr -n "__fish_seen_subcommand_from cache" -a "add key list prune clear" -d "cache subcommand"
 `;
 }