CLI Reference

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Run CalmUiScriptTests and CalmUiTypeScriptPipelineTests through CTest.

calmui test script

Exit codes: 0 if CTest succeeds, 1 otherwise.

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.

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.

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.

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.

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.

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.

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.

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.