CLI: qorm

Hand-written reference for the qorm binary (implemented in cmd/qorm/). Unlike the other pages here it is not generated — update it when the CLI changes.

One binary is the whole toolchain: scaffold, run, render, measure, verify, sign, package, publish, and serve agents. Pure Go by default (cross-compiles everywhere); the default shot, measure, and check paths use the headless software canvas. A macOS -tags desktop build adds WebKit page/URL/window capture, preview, WebView-backed check flows, and HTML-path measurement.

Conventions

• Inputs. <app-dir> is an app source directory (qorm.json + scenes/ + actions/). run, render, and mcp also accept a compiled .qorm.bundle — verified before use (integrity always; authenticity with --trust; revocation with --revoked). render additionally accepts a single scene JSON file.
• Exit codes. 0 success, 1 runtime or verification failure, 2 usage error (also for an unknown command).
• Flags. -o and --out are synonyms everywhere, as are -p and --platform. Flags are parsed by hand: an unrecognized token is taken as the positional input by most commands; qorm update is the exception and rejects unknown flags.
• Environment variables.

• No arguments. Inside a packaged macOS .app, a bare qorm runs the embedded app. Anywhere else it prints usage and exits 2.
• Internal commands. __release-sign, __logwin, and __tray are internal sub-process helpers (CI release signing, the desktop log window, the system tray) — not user commands; __release-sign reads the release key from QORM_RELEASE_KEY.

new

qorm new <dir> [--name "App Name"]

Scaffolds a minimal runnable app: qorm.json (manifest; the app id is sanitized from the directory name), scenes/main.json (a counter screen), and actions/inc.json. Refuses a non-empty directory (exit 1). --name sets the display name (default: the directory base name).

run

qorm run <app-dir|bundle> [flags]

Serves the app live: the browser UI, the SSE push channel, and the agent endpoint at /mcp all share one runtime. See HTTP & SSE for the endpoint contract.

Behavior notes:

• A directory input hot-reloads: a 400 ms mtime poll re-parses the app on change and pushes the re-render to every client, preserving state/scene/viewport. A half-written file is reported and the current app kept.
• A bundle input is verified before serving and enables the OTA endpoints (/update, /rollback). Without --trust only integrity is checked — a warning on stderr says authenticity is not verified.
• The loader's static diagnostics (deprecated attributes, expression type mismatches) print to stderr and never block the run.

render

qorm render <app-dir|scene.json|bundle> [-o out.html]

Writes a static HTML snapshot (the server-side first frame; no live client). Default output: <input base name>.html. A bundle input is integrity-checked only — this command has no --trust, so a warning notes authenticity is not verified.

shot

qorm shot <app-dir> -o out.png [--width W --height H]
qorm shot --html page.html -o out.png
qorm shot --url URL -o out.png
qorm shot --live "window title" -o out.png

App-directory capture works in the default build: QORM renders one deterministic, headless pure-Go Canvas frame, settles entrance effects, and encodes the actual software pixel buffer. It needs neither a WebView nor a GUI. Default size is 440x720; default output is <dir>.png.

On the default Canvas path, the output argument is the exact path (relative paths are relative to the current working directory), must end in .png, and its parent directory must already exist. An existing regular file is replaced; symlinks, directories, and special files are rejected. Dimensions must be positive, no edge may exceed 4096 px, and the surface is capped at 16,777,216 pixels.

A macOS + -tags desktop build instead uses WebKit for app-directory/HTML/URL capture and additionally supports live operating-system windows. Those modes require a GUI session; --live also needs Screen Recording permission. CSS animations are frozen at their final state before WebKit capture. Default builds reject --html, --url, and --live explicitly rather than silently substituting Canvas.

• App directory: pure Canvas by default; WebKit in a macOS -tags desktop build (default --width 440 --height 720, default output <dir>.png).
• --html: capture a static HTML file (default output <name>.png).
• --url: capture a live URL — useful for server-backed pages like /console (default output shot.png).
• --live: capture an already-running window whose title matches (exact title match preferred, then substring), without spinning up a new WebView (default output shot.png).

measure

qorm measure <app-dir> [--width N] [--physical] [-o report.json]

The default build renders the app once with the headless pure-Go canvas and prints a JSON report joining each node's intent (type / text / binding) with the rendered result (rect + computed styles) — to stdout, or to -o. Viewport width defaults to 400; height comes from the manifest window and otherwise defaults to 820. Coordinates use logical CSS pixels; --physical keeps canvas device pixels.

A -tags desktop build measures the HTML path in a native WebView instead. WebView reports CSS pixels, so --physical is accepted for CLI parity but has no effect. Report fields and backend boundaries: Interpreting & verifying a QORM app.

check

qorm check <app-dir> (--checks checks.json | --audit) [--width N] [--physical] [-o report.json]

Measures the app like measure, then evaluates expectations against that backend's render. Static checks and --audit work on the default pure-Go canvas path and the -tags desktop WebView path.

• --checks checks.json — either an array of { "id": …, <assertion>… } static checks (visible, text, geometry, contrast, ARIA, …), or a {"steps":[…]} interaction flow. Default Canvas supports dispatch/args, setState (or state), press, type, key, scroll, and deterministic non-sleeping wait; see verification. A -tags desktop WebView flow keeps its dispatch/setState subset.
• --audit — no authored checks: generic invariants over every visible component (non-zero size, no horizontal overflow, within the window).

Exit status: 0 even when checks fail — pass/fail lives in the report's ok field. Non-zero only on runtime errors (bad checks JSON, load failure). Assertion schema and report format: verification.

build

qorm build <app-dir> [-o app.qorm.bundle] [--key priv.key] [--version V] [--require-capability camera,location]

Compiles the app into a single bundle (qorm-bundle/1 JSON): the content (manifest + scenes + actions + locales), a contentHash over its canonical encoding, and — with --key — a detached ed25519 signature. Default output: <dir base name>.qorm.bundle.

• --version V — stamp the manifest version (covered by the hash) before signing.
• --require-capability a,b — record required capabilities in the signed content; the runtime refuses to start the bundle on a platform missing any of them.
• Static diagnostics print to stderr; they do not fail the build.

keygen

qorm keygen [--out-dir .]

Generates an ed25519 keypair: qorm_key (private, mode 0600) and qorm_key.pub in --out-dir, and prints the 12-character key id. Key files are two lines of text — a header line plus base64 key bytes — easy to inspect and move.

sign

qorm sign <bundle> --key priv.key [-o out]

Signs an existing bundle — e.g. one exported from a live design session via the MCP qorm_export_bundle tool. Without -o the input file is overwritten in place.

verify

qorm verify <bundle> [--trust pub.key] [--revoked list.json]

Verifies a bundle in layers and prints the scope it proved: integrity (content hash recomputed) always, + signature with --trust, + revocation with --revoked. Also prints any required capabilities the bundle declares.

• The revocation list is a JSON array ["keyid", …] or an object {"revoked": […]}; it is checked against the actual verifying key, not the bundle's self-declared keyId.
• Failure prints VERIFY FAILED: <reason> on stderr and exits 1.

mcp

qorm mcp <app-dir|bundle> [--trust pub.key] [--revoked list.json]

Serves the app to an AI agent over MCP (stdio JSON-RPC) — the same tool set a running qorm run exposes at /mcp, but on its own private runtime (no shared browser session). Tool reference: MCP tools.

preview

qorm preview <package-dir> [--width N] [--eval JS] [-o report.json]

Verifies a packaged app, not the source: serves the static output of qorm package -p web, lets its client-side WASM runtime boot and render with no app server, and captures the app's self-measurement (stdout, or -o). --eval JS runs JavaScript in the page after the first measurement — e.g. qorm(0) to press the first action button — then re-measures, so the packaged build's interactivity is exercised too. Needs a -tags desktop build.

Not to be confused with the MCP qorm_preview_patch tool, which previews a design patch on a live session.

package

qorm package <app-dir> [-p web|ios|android|mac|miniapp] [-o out-dir] [flags]

Compiles the app into an installable, fully offline package. Default platform web; default output <app dir name>-<platform>. Before building, a capability matrix prints to stderr warning about features the target platform does not support (and about a native middle layer missing for the target).

The web/ios/android payloads compile the client runtime with go build (GOOS=js GOARCH=wasm), so the Go toolchain and the QORM module must be reachable — run it from the QORM repo, or a directory whose go.mod requires github.com/qorm/platform. The app's own Go middle layer (native/desktop.go) is injected into that build, and into the desktop binary for mac.

General flags:

Commercial gate (honour system). A custom icon.png in the app dir, or --no-branding, is commercial white-labeling: the packager prints a note and asks you to confirm a QORM Patreon membership — interactively, or via --subscribed. Non-interactive runs without --subscribed fail (exit 1). Personal / educational / open-source use (default icon, branding on) never triggers it.

Release flags — qorm package … --release produces a distributable, signed artifact:

Android release signing without --keystore uses a managed keystore at <app-dir>/.qorm/release.keystore: generated with keytool on the first release (a JDK is required), passwords stored in keystore.properties (mode 0600), the whole .qorm directory git-ignored, and reused so every update carries the same signature. A macOS --release build never falls back to ad-hoc signing — it fails instead.

docs

qorm docs [--docs docs] [-o docs-site] [--name Name]

Renders a markdown tree into a static HTML site (this documentation site is built with it). Defaults: source docs/, output docs-site/, header label = the source directory's base name. The header is stamped with the version of the qorm binary doing the render.

audit

qorm audit <audit-log.jsonl>

Verifies a hash-chained activity log written by qorm run --audit-log: each entry's hash covers the previous entry's hash plus its own sequence, timestamp, source, and detail, so any edited, dropped, reordered, or re-attributed entry breaks the chain. Success prints AUDIT OK: N entries, hash chain intact; failure prints AUDIT FAIL after N verified entries: <reason> (locating the first bad entry) and exits 1. The chain is self-anchoring from the first entry — keep an out-of-band copy of the final hash to also detect truncation.

updates

qorm updates [bundles-dir] [--port N]

The publish side of OTA: an HTTP server that hands each client the bundle it should run, honoring a staged (canary) rollout. Defaults: directory ., port 0 (a random free port, printed on startup).

• bundles-dir/rollout.json maps app id to {"stable": "app-v1.qorm.bundle", "canary": "app-v2.qorm.bundle", "canaryPercent": 10} (canary / canaryPercent optional). The file is read once at startup.
• GET /resolve?app=<id>&client=<id> returns the bundle JSON this client should run: the canary when FNV-1a(client id) % 100 < canaryPercent — deterministic per client — else the stable bundle. Unknown app ids and missing files get 404; a file that is not a well-formed bundle is never served.
• GET /bundles/<file> serves bundle files directly. All routes answer with open CORS (*) — packaged shells call cross-origin; trust comes from the client-side ed25519 verification (see qorm package --update-url), not from who may read the bundles.

update

qorm update [--insecure-skip-verify]

Self-updates the CLI from the latest GitHub release. Already current (release tag equals the running version): prints so and exits 0. Otherwise, with a Go toolchain present it runs go install github.com/qorm/platform/cmd/qorm@latest; without one it downloads the qorm-<os>-<arch>[.exe] asset, verifies it against the release's SHA256SUMS + SHA256SUMS.sig using the release public keys embedded in the build (a build without embedded keys cannot verify and refuses), then swaps the executable — the old binary is renamed to <exe>.old first and restored if the swap fails. --insecure-skip-verify installs the download without verification (prints a warning; not recommended).

version

qorm version        # aliases: --version, -v

Prints qorm <version> (<go version> <os>/<arch>). The version is stamped at build time via -ldflags -X main.version=<tag>; un-stamped builds report the in-source dev default.