routeros-quickchr-cli

CHR from the shell: quickchr CLI + centrs

quickchr (@tikoci/quickchr, CLI + Bun/TS library) downloads a MikroTik CHR image, boots it under QEMU, and hands you a router. This skill is the shell-first path: you have a terminal, you want a router to interrogate, and the answer will be quoted as shell + RouterOS commands (e.g. in a forum.mikrotik.com reply). If you are writing a bun:test harness that imports QuickCHR, use the routeros-quickchr skill instead — one scheme per task, never both.[^split]

Behavior below is pinned to quickchr 0.4.8. Several of these are 0.4.8 changes, called out inline; on 0.4.7 and earlier the answer differs.[^pin]

One limit to keep in view: a CHR booted this way runs the free license (quickchr get <name> shows Level: free), which MikroTik caps at 1 Mbps upload per interface — every other RouterOS feature is unrestricted. Config, API and CLI grounding are unaffected; a throughput or queue number measured here is the license talking, not the feature.[^license]

Lifecycle: add is not start

quickchr add --name lab-a --version 7.24.4 --arch x86 --add-network user
quickchr start lab-a --bg
quickchr exec lab-a "/system/resource/print"
quickchr stop lab-a
quickchr remove lab-a

• add only writes config (0s on a warm cache) and prints quickchr start <name> as its tip. It never boots — the single most common wrong assumption about this CLI.[^ground-add]
• start --bg blocks until the guest is REST-ready, then prints the REST/SSH/WinBox endpoints (≈22s first boot, ≈11s restart, warm-cache HVF). Under TCG software emulation expect minutes, not seconds — a sandboxed field lab saw ~4 min boots and a real BOOT_TIMEOUT at 480s. Size harness timeouts from the slow end.[^ground-timings]
• exec <name> <command…> runs one RouterOS command over REST. --via is auto|rest|qga here, and qga is narrower than it looks: RouterOS only starts its guest agent for an x86 CHR under Linux KVM. Under macOS HVF or TCG the port is presented but the guest never opens it, and ARM64 CHR has no QGA at all — both time out. Stay on REST unless you are on Linux/KVM with an x86 guest. (The library's ExecTransport type also lists ssh and console; those are not CLI surface.) stop is instant; remove deletes the machine. list shows state and PIDs.[^ground-exec]
• Version selection: --version 7.24.4 pins; --channel stable|long-term|testing|development resolves the newest of a channel. Bare quickchr --version prints what each channel currently resolves to.[^ground-channel]
• Ports are auto-allocated from 9100 in per-machine blocks of ten (9140, 9150, 9160 …), so parallel machines do not collide and you need no port bookkeeping. --port-base overrides; --forward name:host:guest/proto adds extras, ranges included.[^ground-ports]
• Pre-warm without booting: quickchr cache add --version 7.24.4 --arch x86 resolves and downloads one image, no QEMU and no machine required. cache key prints dir=/version=/arch= for CI. (Both new in 0.4.8 — before it, cache was list|prune|clear only and the only way to warm the cache was to boot something.)[^ground-cache]
• Never hand-edit machine.json to change networks or options — it breaks boot. Everything is reachable through add flags.[^field]