CLI reference

The huxerui CLI owns project generation and platform workflows. It discovers the SDK, validates the current host, and delegates each build to the platform shell generated with the project.

Command map

huxerui create app <name> [--id <project-id>] [-p|--platform <platform-list>]
huxerui create library <name> [--namespace <cpp-namespace>] [--target <public-cmake-target>] [-p|--platform <platform-list>]
huxerui platform add <platform-list>
huxerui doctor [platform-list]
huxerui setup <platform-list> [--yes]
huxerui devices [platform]
huxerui build [platform-list] [--device <id>] [--profile debug|release] [--generator <name>]
huxerui run <platform> [--device <id>] [--profile debug|release] [--generator <name>]
huxerui package <platform-list> [--device <id>] [--profile debug|release] [--generator <name>]
huxerui open ios
huxerui update [--check] [--version <version>] [--yes]
huxerui mcpp build [--source <path>] [--release] [--locked] [--offline] [--verbose]
huxerui --version

A platform list is either a comma-separated list such as windows,web or the single value all. Commands still enforce host availability: a Windows host cannot build an iOS application, for example.

Create projects

Create an application with a reverse-DNS project identifier and selected platform shells:

huxerui create app notes --id dev.example.notes --platform windows,android,web

Create a reusable component library with the same shared-source model:

huxerui create library rich_text --namespace rich_text --target RichText::RichText --platform windows,android

Generated projects keep shared C++ under src/, resources under resources/, and host-specific integration under platform/<id>/. The CLI scans the shared source tree; adding a source file does not require a second list in every platform shell.

Add a platform later without replacing application-owned files:

huxerui platform add ios

Diagnose and set up tools

doctor is read-only. It reports the selected HuxerUI SDK, external tools, host restrictions, and project integration problems:

huxerui doctor
huxerui doctor android,web

setup performs supported prerequisite installation or configuration. Without --yes, it describes each planned action and asks before changing the machine:

huxerui setup android,web
huxerui setup web --yes

The SDK is resolved from HUXERUI_HOME first, then relative to the running CLI executable. Use an explicit environment variable when testing a source checkout or keeping multiple SDK versions.

Select devices

List all device-capable platforms available on the current host, or select one platform:

huxerui devices
huxerui devices android

If exactly one ready device is present, run selects it automatically. When several devices are ready, pass the stable identifier shown by devices:

huxerui run android --device emulator-5554

Build and run

build accepts one or more enabled platforms and defaults to the current host platform when it is part of the project:

huxerui build
huxerui build windows,web --profile release

run accepts exactly one platform because it launches one application instance:

huxerui run windows
huxerui run web --profile release

Windows selects an MSVC-compatible generator automatically; --generator is intended for other supported CMake workflows. Android and iOS builds are driven through their platform projects rather than a generic desktop generator.

Package artifacts

package builds first and then replaces dist/<platform> with the platform driver’s distributable artifacts. Its default profile is release:

huxerui package windows,web
huxerui package android --device emulator-5554 --profile debug

Packaging is not code signing or store submission. The produced files are the input to the platform’s signing, notarization, store, or deployment workflow.

Open the iOS project

Generate the current library integration and open the Xcode project from a macOS host:

huxerui open ios

Use Xcode for signing, capabilities, device provisioning, and archive distribution; keep shared source and library ownership in the HuxerUI project.

Update an installed SDK

huxerui update --check
huxerui update
huxerui update --version 0.2.0 --yes

The update command operates on an installed SDK, not a source checkout. –check inspects availability without installing; –version selects a release and –yes skips confirmation. Without –version it resolves the current release. Keep active builds and tools out of the destination during replacement.

On Windows the running CLI cannot replace itself directly: it starts an update worker and prints an update.log location. A successful initial exit means handoff, not completed installation. Inspect that log and rerun –version after the worker finishes. Handled publication failures restore the old SDK, but abrupt termination is not an atomic-update guarantee.

Standalone mcpp builds

huxerui mcpp build --source path/to/project --release --locked

This is a direct frontend for an installed mcpp executable and a project containing mcpp.toml. It forwards –release, –locked, –offline and –verbose to mcpp build in that directory. It does not generate platform shells, translate huxerui.toml, install mcpp, or run the CMake application workflow.

The stateless desktop example demonstrates linking public components. Composable transformation and packaged resources still need explicit mcpp integration; this frontend is not equivalent to huxerui build for a general application. Use the normal CMake/platform workflow unless this independent toolchain is intentional.

Exit behavior

Usage errors return exit code 2 and print the command synopsis hint. Environment, build, or platform failures return exit code 1. A successful command returns 0, making the CLI suitable for scripts and CI without parsing human-readable status text.