CLI
Build, validate, migrate, test, inspect, and automate CalmUI projects from the command line.
This section is for terminal and build automation. For interactive editing, use Studio. Check the installed tool version first:
calmui --versionAdd --json to any of --version or inspect css-profile for a
machine-readable object instead of the human-readable lines.
Run these commands from a project containing MainMenu.calmui. Replace that
filename and the output path with your own:
calmui validate .\MainMenu.calmui --project-root .
calmui format . --check
calmui generate types --project .
calmui build .\MainMenu.calmui --output .\dist\MainMenu.cuipack --configuration shipping
calmui inspect .\dist\MainMenu.cuipackUse calmui dev . for live Development packages, calmui screenshot for a
saved preview image, and calmui migrate --check before applying
a project schema migration. Commands return 0 on success, 1 for an
operation failure, and 2 for invalid arguments unless noted below.
calmui dev localization
Read a batch of project translations for a culture without changing Unreal culture.
calmui dev localization [project] --query <json|-> [--process-id <pid>] [--timeout-ms <milliseconds>]
--query <json|->(required): requestId, culture, optional sourceCulture/refresh, and entries containing key/defaultValue. Use - to stream JSON from stdin (up to 1 MiB).--process-id <pid>: Target the selected Unreal process; omission selects an available runtime.--timeout-ms <milliseconds>: Bound the wait for the Unreal response.
Exit codes: 0 for a received reply, 1 for a connection/timeout error, 2 for invalid arguments. Inspect reply.ok for lookup validation.
Requires localization.query.v1. Does not modify game language or translation assets.
calmui --version [--json]
Print CLI, Core, Compiler, .cuipack, and Development protocol versions from CalmUIVersion.json.
calmui --version [--json]
-V: Same as --version.--json: Print core/paint/cuipack/dev/css versions, the git SHA, and the combined fingerprint as one JSON object instead of the human-readable lines.
Exit codes: 0 on success, 2 if the command line is not recognized.
calmui validate <entry.calmui>
Compile the component graph and report diagnostics without writing a package.
calmui validate <entry.calmui> [--project-root <dir>] [--style <file>]
entry.calmui(required): Root component file.--project-root <dir>: Project root. Defaults to the entry parent directory.--style <file>: Global CSS file, repeatable. Paths are relative to the project root.
Exit codes: 0 if the graph is valid, 1 on compiler errors, 2 on invalid arguments.
calmui validate <file.html>
Validate a static HTML/CSS document against CSS Profile v0.4.
calmui validate <file.html> --css <file.css> [--font <family=file.ttf>] [--fallback-font <family=file.ttf>] [--asset <asset://uri=file.png>] [--viewport <width>x<height>] [--scale <number>]
--css <file.css>(required): Stylesheet to validate.--font <family=file.ttf>: Optional project font mapping. Inter 4.1 is built in.--fallback-font <family=file.ttf>: Ordered fallback font mapping.--asset <asset://uri=file.png>: Mapped PNG resource.--viewport <width>x<height>: Logical viewport. Default 1280x720.--scale <number>: UI scale. Default 1.
Exit codes: 0 if layout succeeds, 1 on validation/layout errors, 2 on invalid arguments.
calmui typecheck [entry.calmui]
Type-check component TypeScript and print Store/action schema hashes.
calmui typecheck [entry.calmui] [--project-root <dir>] [--style <file>]
entry.calmui: Optional. With no arguments, typechecks the Showcase MainMenu with tokens.css and global.css.--project-root <dir>: Project root.--style <file>: Global CSS file, repeatable.
Exit codes: 0 if typecheck succeeds, 1 on compiler/script errors, 2 on invalid arguments.
calmui build <entry.calmui>
Compile a versioned .cuipack. Shipping omits source maps and does not need .calmui files at runtime.
calmui build <entry.calmui> --output <file.cuipack> [--configuration development|shipping] [--project-root <dir>] [--style <file>] [--package-name <name>] [--screen name|entry|layer|input|retention|cursor[|enterClass|enterMs|exitClass|exitMs]] [--theme <name>] [--variable <name=value>]
entry.calmui(required): Root component.--output <file.cuipack>(required): Output path.--configuration development|shipping: Package configuration. Default development.--project-root <dir>: Project root.--style <file>: Global CSS file, repeatable.--package-name <name>: Stable package name used to derive package identity.--theme <name>: Resolve the named [data-calmui-theme] CSS-variable layer into the package.--variable <name=value>: Repeatable final CSS-variable override for authoring and automation.--screen name|entry|layer|input|retention|cursor[|enterClass|enterMs|exitClass|exitMs]: Repeatable screen descriptor. The optional transition fields name ordinary CSS classes and deterministic lifecycle durations in milliseconds. Layers: hud, screen, overlay, modal, tooltip; input: passthrough, game-and-ui, ui-only, block-below; retention: destroy or keep-alive.
Exit codes: 0 on success, 1 on compile/encode errors, 2 if --output is missing or arguments are invalid.
calmui inspect <file.cuipack>
Print package format, component counts, script metadata, schema hashes, and source-map presence.
calmui inspect <file.cuipack>
file.cuipack(required): Package to inspect.
Exit codes: 0 if the package loads, 1 if it is invalid.
calmui inspect css-profile
Print the CSS Profile version and the supported, engine-internal, and future property counts (or the full property lists with --json).
calmui inspect css-profile [--json]
--json: Print { version, supported, engineInternal, future } with the full property-name arrays instead of counts.
Exit codes: 0 on success, 2 on invalid arguments.
Reads the same CSS Profile source the CSS support matrix (/docs/styling/css-reference) documents.
calmui screenshot [project]
Render the real Studio Core WASM/WebGL preview to a deterministic PNG without opening the Studio window.
calmui screenshot [project] --output <file.png> [--entry <file.calmui>] [--viewport <width>x<height>] [--time-ms <milliseconds>] [--state default|hover|active|focus|gamepad-focus|disabled|holding] [--target <id|test-id|class>]
project: CalmUI project path. Defaults to the current directory.--output <file.png>(required): PNG output path.--entry <file.calmui>: Entry component. Defaults to the project entry.--viewport <width>x<height>: Logical preview size. Default 1280x720.--time-ms <milliseconds>: Deterministic animation and transition time.--state <state>: Optional forced interaction state.--target <id|test-id|class>: Element used with a non-default state.
Exit codes: 0 when the PNG is written, 1 on project, build, render, or write failure, 2 on invalid arguments.
calmui graph <entry.calmui>
Print the deterministic component dependency graph.
calmui graph <entry.calmui> [--project-root <dir>] [--style <file>]
entry.calmui(required): Root component.--project-root <dir>: Project root.--style <file>: Global CSS file, repeatable.
Exit codes: 0 on success, 1 on compiler errors, 2 on invalid arguments.
calmui format <file-or-directory>...
Format .calmui, CSS, and JSON sources with the same canonical formatter used by Studio.
calmui format <file-or-directory>... [--check]
file-or-directory(required): One or more source files or directories. Directories are scanned recursively.--check: Do not write files; fail when any supported source needs formatting.
Exit codes: 0 when sources are formatted or already clean, 1 on malformed input or a --check mismatch, 2 when no target is provided.
Scans .calmui, .css, and .json while ignoring .git, node_modules, build, Binaries, Intermediate, and Saved directories.
calmui generate unreal-schema
Generate the current project C++ Store/action IDs and reflection manifest.
calmui generate unreal-schema [--project <path>]
--project <path>: Project path. Defaults to the current directory and searches upward for calmui.config.json.
Exit codes: 0 if generation succeeds, 1 if the Node generator fails, 2 on invalid arguments.
calmui generate types
Generate TypeScript types, runtime metadata, C++ IDs, and the manifest from the project Store schema.
calmui generate types [--project <path>]
--project <path>: Project path. Defaults to the current directory and searches upward for calmui.config.json.
Exit codes: 0 if generation succeeds, 1 if the Node generator fails, 2 on invalid arguments.
Both commands synchronize every generated contract. Breaking schema changes require a higher schema version.
calmui dev [project]
Run the loopback compiler daemon, watcher, LastKnownGood cache, and Unreal Dev Protocol server.
calmui dev [project] [--port <port>] [--verbose]
project: Project directory or a path below it. The CLI searches upward for calmui.config.json.--port <port>: Loopback TCP port. Use 0 to request an ephemeral port.--verbose: Show detailed watcher and patch events.
Exit codes: 0 after a clean stop, 1 on configuration, initial compilation, or server failure, 2 on invalid arguments.
calmui dev status
Query the live daemon for its port, revision, project, and connected Unreal runtime count.
calmui dev status [project]
project: Path used to find calmui.config.json.
Exit codes: 0 when the daemon answers, 1 when it is offline or does not answer.
calmui dev shutdown
Request authenticated graceful shutdown of the daemon session owned by a workspace.
calmui dev shutdown [project] [--timeout-ms <milliseconds>]
project: Path used to find calmui.config.json and its active discovery session.--timeout-ms <milliseconds>: Maximum wait for the authenticated acknowledgement.
Exit codes: 0 after acknowledgement, 1 when no valid owned session answers, 2 on invalid arguments.
Studio uses this before forcing termination of an older same-workspace daemon.
calmui dev inspect
Request and validate one or every active Unreal runtime inspector snapshot through the Dev Protocol.
calmui dev inspect [project] [--json] [--all]
project: Path used to find calmui.config.json.--json: Write the complete snapshot as JSON, including Store and Action Log.--all: Collect all active engine/world/Local Player/view targets. JSON output becomes an array.
Exit codes: 0 for a complete snapshot, 1 on connection, timeout, or incomplete inspector data.
calmui dev reload
Force an authoritative Development package sync without restarting PIE.
calmui dev reload [project]
project: Path used to find calmui.config.json.
Exit codes: 0 when the request is sent, 1 when the daemon is offline.
calmui dev project-info
Read structured Unreal project, package registry, capabilities, and available cultures.
calmui dev project-info [project] [--timeout-ms <milliseconds>]
project: Path used to find calmui.config.json.--timeout-ms <milliseconds>: Bound the Unreal response wait from 1 to 300000 ms. Default 30000.
Exit codes: 0 with JSON output, 1 when Unreal/daemon is unavailable or returns invalid data.
calmui dev import-package
Ask the connected Unreal Editor to import or refresh a CalmUI Package Asset.
calmui dev import-package [project] --source <file> --asset-path </Game/...>
--source <file>(required): Built Development .cuipack.--asset-path </Game/...>(required): Destination UCalmUiPackageAsset path.
Exit codes: 0 when Unreal imports and saves the asset, 1 on timeout/import failure, 2 on missing arguments.
calmui dev select-asset
Open the connected Unreal Content Browser picker for a supported host asset.
calmui dev select-asset [project] --kind image|font --uri <asset://...>
--kind image|font(required): Select UTexture2D or UFontFace.--uri <asset://...>(required): Neutral manifest URI receiving the soft object path.
Exit codes: 0 with JSON selection data, 1 on timeout, 2 on invalid arguments.
calmui dev culture
Switch the connected Unreal Development preview culture and trigger localized relayout.
calmui dev culture [project] --culture <name>
--culture <name>(required): Unreal culture name such as en or pl.
Exit codes: 0 with the selected culture, 1 on timeout/rejection, 2 when --culture is missing.
calmui studio [project]
Open the installed CalmUI Studio desktop app for a project.
calmui studio [project]
project: Project directory. Defaults to the current directory.
Exit codes: 0 after Studio exits cleanly, 1 if Studio cannot be launched, 2 on invalid arguments.
The release CLI resolves Studio beside the installed or portable artifact; PATH is not required.
calmui test dev-reload
Run the Unreal live-reload, reconnect, inspector, and LastKnownGood test suite.
calmui test dev-reload [--engine-root <path>] [--timeout <seconds>] [--skip-build]
--engine-root <path>: Unreal Engine 5.7 root.--timeout <seconds>: Fixture timeout.--skip-build: Reuse a current native SDK and Unreal plugin build.
Exit codes: 0 when every assertion passes; non-zero on build, timeout, protocol, runtime, or cleanup failure.
calmui test script
Run CalmUiScriptTests and CalmUiTypeScriptPipelineTests through CTest.
calmui test script
Exit codes: 0 if CTest succeeds, 1 otherwise.
calmui test ue
Run headless Unreal fixture manifests against the production runtime.
calmui test ue (--fixture <name> | --all) [--resolution <width>x<height>] [--screenshot] [--update-golden] [--tolerance <0..1>] [--engine-root <path>] [--timeout <seconds>] [--skip-build] [--reporter studio-json]
--fixture <name>: One fixture name. Mutually exclusive with --all.--all: Run every fixture. Mutually exclusive with --fixture.--resolution <width>x<height>: Override screenshot resolution.--screenshot: Capture screenshots.--update-golden: Write current screenshots as declared goldens.--tolerance <0..1>: Mean pixel tolerance override.--engine-root <path>: Unreal Engine 5.7 root. Also CALMUI_UNREAL_ENGINE_ROOT or UE_ROOT.--timeout <seconds>: External process timeout.--skip-build: Skip Core SDK and sandbox rebuild. Use only after a current-source build.--reporter studio-json: Emit versioned, prefix-delimited JSON progress events while preserving normal CLI output.
Exit codes: Non-zero on timeout, crash, failed assertion, missing screenshot, golden mismatch, or invalid options (2 when both/neither --fixture and --all are set).
Win64 sandbox only.
calmui migrate [project]
Preview or apply an atomic project-schema migration with a source backup.
calmui migrate [project] [--check|--dry-run] [--from <version>] [--to <version>]
--check: Print the migration plan without writing.--dry-run: Print the plan without writing.--from <version>: Require the detected source schema to match.--to <version>: Target schema. Current target is 1.
Exit codes: 0 for a valid plan or completed migration; 1 on unsupported schema, backup, parse, or write failure.
calmui doctor [--project
Run environment/consistency checks (versions, WASM fingerprint, Studio debug Vite, MSVC toolset, dev-server.json health, plugin drift, disk space, input mode) and print a verdict for each.
calmui doctor [--project <uproject dir>] [--json]
--project <uproject dir>: Scope the dev-server, plugin-drift, and input-mode checks to this Unreal project.--json: Print a JSON array of {id, status, detail, fix} instead of the table.
Exit codes: 0 when every check passes, 1 when at least one check fails, 2 for invalid arguments.
Studio's Diagnose action (command palette and Unreal dashboard) runs this command.
calmui support bundle
Create a local sanitized diagnostics bundle without project source, assets, secrets, or environment values.
calmui support bundle [project] [--output <directory>]
--output <directory>: Bundle output directory.
Exit codes: 0 on success, 1 when output or configuration cannot be read.
calmui release build|unreal-plugin|validate-marketplace
Build local release-candidate artifacts from a CalmUI source checkout.
calmui release build|unreal-plugin|validate-marketplace
Exit codes: 0 when packaging and validation pass; 1 on any failed release gate.
Contributor command. It requires a clean committed worktree and does not publish a release.
calmui validate unreal-plugin
Check a release plugin for required modules, shaders, libraries, notices, versions, and forbidden local paths.
calmui validate unreal-plugin <path>
path(required): Standalone CalmUI plugin directory.
Exit codes: 0 when validation passes; 1 for an incomplete or non-portable package.
calmui debug paint-frame
Write a deterministic diagnostic PaintFrame. This is not a shipping .cuipack.
calmui debug paint-frame --output <file.cuipaint> [--dump]
--output <file.cuipaint>(required): Output path.--dump: Print commands to stdout.
Exit codes: 0 on success, 1 on encode/write errors, 2 if --output is missing.
calmui inspect-paint-frame <file.cuipaint>
Decode and dump a diagnostic .cuipaint file.
calmui inspect-paint-frame <file.cuipaint>
file.cuipaint(required): PaintFrame file.
Exit codes: 0 on success, 1 on decode errors.
calmui screenshot finds CalmUI Studio itself: it checks
CALMUI_STUDIO_EXECUTABLE, then every known target/release and
target/debug build under the repository (newest file wins when more than
one exists), then the per-user install under %LOCALAPPDATA%. It prints
which one it picked, its kind (debug/release), and when it was built -
for example Using Studio C:\...\target\release\calmui-studio.exe (release, built 2026-09-21T10:03:00Z). A resolved debug build only proceeds if either
Vite is reachable on localhost:1420 or the build embeds its own frontend;
otherwise the command fails fast with the fix instead of hanging until the
Studio process's own timeout.
Before rendering, the command also compares this CLI's build fingerprint
against the WASM core Studio will render with (from
apps/studio/public/wasm/calmui-core-manifest.json in a repository build, or
<exe dir>/resources/wasm/calmui-core-manifest.json for an installed one). A
mismatch on any versioned field (paint frame, .cuipack, dev protocol, or CSS
profile - the git commit is informational only) fails with run pnpm wasm:build; pass --allow-stale-wasm to capture anyway when that skew is
expected, such as while bisecting a WASM regression. A manifest with no
fingerprint field at all (an older build) only warns. On success, the
command prints the WASM revision and fingerprint the capture actually used,
for example Rendered by Studio ...\calmui-studio.exe / WASM a1b2c3.../ core core=1;paint=1.8;... - reported by the Studio process itself
via write_preview_screenshot, not guessed from the manifest on disk, so it
reflects what was actually loaded even if it does not match the file (for
example after --allow-stale-wasm).
--time-ms seeks the UI clock to an absolute instant: every running animation
is placed at that time from the document's start, not from the moment its own
element appeared. A screen whose element is added later (a badge behind
ui:if, a row a script inserts) therefore renders at the keyframe the absolute
instant lands on, which for a short animation asked for late is its end state.
That is the point for a golden, but it makes a transient animation look broken
when it is not: to judge one, step the clock instead of seeking it, or ask for
an instant measured from the moment the element appears.
For UI tests, use a fixture name from your own project or calmui test ue --all
for all configured tests. See UI tests for the Studio workflow.
Each fixture run writes its own Unreal.log under
artifacts\tests\unreal\<fixture>\Unreal.log, alongside report.json and any
screenshots. The runner caps that log at 256 MB by default; set the
CALMUI_UE_MAX_LOG_MB environment variable to raise or lower the cap for every
run, or pass -MaxLogMB <n> when invoking
tools\testing\run-unreal-tests.ps1 directly for a single run. A fixture that
crosses the cap is stopped immediately: report.json records
"status": "aborted-log-cap" and the console prints an [ERROR] Unreal.log exceeded <n> MB line naming the cap. Treat a hit as a sign the fixture (or a
recent LogCalmUI change) is logging per frame rather than per event; the full,
uncapped log for the run stays at the path above for diagnosis.