axiom ui

axiom ui holds the advanced frontend tooling for authored Acore UI: target hosts, starters, compiler checks, AI context, tests and .axiomapp builds. This page covers Axiom CLI 0.149.1. For everyday development, axiom run main.acore is the usual entry point; it uses the same compiler and hosts.

Diagram source

flowchart LR
  Init[ui init] --> Check[ui check]
  Host[ui host install] --> Run[axiom run or ui run]
  Check --> Run
  Run --> Test[ui test]
  Test --> Build[ui build]
  Build --> App[.axiomapp artifact]
  App --> Inspect[axiom inspect]
  App --> Install[axiom install]
  App --> Package[axiom package]
  App --> RunApp[axiom run artifact]

You create a starter with ui init, check it with ui check, and develop it with axiom run (or ui run) on a host installed by ui host install. Before release, ui test runs session or interaction tests and ui build writes a target-specific .axiomapp. You then inspect, install, combine or run that artifact with the top-level commands.

axiom ui

Groups the advanced frontend commands.

axiom ui <COMMAND>

No options other than --help.

Shared behavior:

• --target accepts web, android or ios and defaults to ios on every ui subcommand. Any other value fails with UI target must be `ios`, `android`, or `web` . axiom run also defaults Acore source to ios.
• --lock selects the UI contract lock and defaults to .axiom/axiom.ui.lock.json. A module that imports a backend contract with use contract needs that lock; a missing lock reports AUI010. Create it with axiom contract resolve. A module without contract imports checks without a lock.
• axiom run maintains a development lock automatically, so --lock is an advanced override that the normal source-first workflow does not need. Use axiom run --frozen when a run must consume reviewed locks and signed extension workflows without development regeneration.
• No command writes generated UI source to your workspace. IR, the contract facade and bundles stay in memory or in a private cache.
• The commands run locally and need no Cloud login. ui host install, ui host status, and a first axiom run that installs a host contact the public AxiomCore release service.

These environment variables adjust host sessions:

Set up a target host

axiom ui host

Manages the UI Host, the prebuilt application that renders your UI on a target: a browser host for web, and a development app for the Android Emulator or iOS Simulator. Hosts are installed outside your application workspace.

axiom ui host <COMMAND>

No options other than --help. The subcommands are install, status, recover, rollback and quarantine.

axiom ui host install

Downloads, verifies and installs a signed UI Host release for one target. It needs network access to the public AxiomCore releases unless you pass --offline or --release-manifest. Without --version, it selects the newest stable signed release compatible with this CLI's compiler and skips quarantined releases. The iOS Simulator host supports Apple Silicon Macs only. axiom run offers to install the latest verified host when none is installed.

axiom ui host install [OPTIONS]

axiom ui host install --target web
axiom ui host install --target web --version 0.6.12
axiom ui host install --target android

axiom ui host status

Shows whether a host is installed for a target, its release and variant, its renderer toolchain, the number of retained compatible releases, and whether bundle delivery is ready. It also checks the public releases for a newer compatible host; when that check fails, it reports updates as unavailable and still succeeds.

axiom ui host status [OPTIONS]

axiom ui host status --target web

axiom ui host recover

Restarts the installed development host and discards only stale delivery control records. Use it when an interrupted session leaves the host waiting on an old acknowledgement. It never deletes a verified host archive, your Acore source, the compiler cache or the last good bundle. For ios it restarts the host on the selected Simulator, for android on the emulator, and for web it asks you to restart axiom run --target web. It requires an installed, current host.

axiom ui host recover [OPTIONS]

axiom ui host rollback

Reinstalls a retained signed host, offline. Without --version it restores the previous verified host; with --version it selects the retained verified release of that exact version. It refuses a host that does not support this CLI's renderer, IR and helper contract.

axiom ui host rollback [OPTIONS]

axiom ui host quarantine

Marks a host release as a known rendering regression on this machine, so local installation and automatic selection skip it. Retained signed files and application data are preserved. Follow it with axiom ui host rollback to select a compatible retained release.

axiom ui host quarantine [OPTIONS] --version <VERSION> --incident <INCIDENT>

Create and check source

axiom ui init

Creates a small authored Acore UI starter: axiom.app.toml, src/main.acore, tests/smoke.acore and README.md. The directory must be empty or absent; the command refuses a non-empty directory.

axiom ui init [OPTIONS] <DIRECTORY>

axiom ui init my-app --target web
cd my-app
axiom run src/main.acore --target web

axiom ui check

Parses, validates and lowers a UI module in memory without writing generated source. Use it in CI or before a commit; it exits non-zero on an error diagnostic. Target-specific lowering can add warnings, for example a SafeArea container fallback on android.

axiom ui check [OPTIONS] <SOURCE>

axiom ui check src/main.acore --target web

For the ui init starter module, the output names the module, the number of in-memory files and the graph revision:

Checked UI module starter.app.ui (17 virtual read-only file(s), graph 7b94158907ee4d05cd0473e5cefeb00c332c46666a05b235e11cfab13a4aeb65).

Run and inspect

axiom ui run

Starts a compiler and watch session for one UI module with an explicit lock. For normal development prefer axiom run SOURCE, which also builds stale local contracts, maintains the development lock and prepares registered sandbox extensions.

• web: serves the app from the installed web host on 127.0.0.1 and reloads on change. --launch opens the default browser.
• ios and android: without --launch, runs the compiler watch loop only. With --launch, delivers each good bundle to the UI Host on a booted iOS Simulator or Android Emulator, and offers to install a missing host. Native bundle compilation needs Node.js 20.19+ or 22.12+.
• --once: compiles once and exits, without a host. Use it in CI.

axiom ui run [OPTIONS] <SOURCE>

axiom ui run src/main.acore --target web --launch

axiom ui inspect

Prints one read-only compiler view, tied to the current graph revision, as JSON. Use it to debug compiler output or to feed tooling.

axiom ui inspect [OPTIONS] <VIEW> <SOURCE>

axiom ui inspect ir src/main.acore --target web

AI tooling

axiom ui context

Returns compiler-checked, compact and redacted semantic context for AI tooling as JSON. Give an assistant this context instead of generated files.

axiom ui context [OPTIONS] <SOURCE>

axiom ui ai-check

Validates an AI-proposed replacement for a UI module without writing it to the workspace. It prints a JSON validation result and exits non-zero when the proposal fails compiler postconditions or was based on a stale graph revision. The current source must compile.

axiom ui ai-check [OPTIONS] --base <BASE> <SOURCE> <PROPOSED>

Diagnose

axiom ui doctor

Diagnoses UI compiler and target-host prerequisites without modifying the workspace. It reports compiler, graph and host state with a diagnostic code (AXIOM_UI_HOST_READY, AXIOM_UI_HOST_UPGRADE_REQUIRED or AXIOM_UI_HOST_MISSING) and a remediation. Read the code rather than the exit status: the command reports readiness and succeeds either way. --json emits an axiom-ui-doctor/v1 report.

axiom ui doctor [OPTIONS]

axiom ui doctor --target web --json

axiom ui capabilities

Lists the versioned Lynx/Acore capability registry for a target: the elements, components, properties, at-rules, data types and selectors Acore supports, with their status.

axiom ui capabilities [OPTIONS]

Test and build

axiom ui test

Without --suite, runs a compiler-session smoke check without launching a host: a compatible update must preserve state and an invalid update must keep the last good graph. With --suite, runs a versioned acore-application-test/v1 JSON interaction suite. See Frontend tests.

axiom ui test [OPTIONS] <SOURCE>

axiom ui test src/main.acore --target web

axiom ui build

Builds a deterministic, target-specific .axiomapp application artifact. It requires the current verified UI Host for that target, and native targets compile a bundle with Node.js 20.19+ or 22.12+. The default release mode rejects unsigned local contract dependencies (AXIOM_UI_UNSIGNED_RELEASE_INPUT); publish them or pass --development, which permits them and marks the artifact development-only in its manifest. Physical-device certification and store publishing are not part of this command.

axiom ui build [OPTIONS] <SOURCE>

axiom ui build main.acore --target web --development
axiom inspect dist/my-app-web.axiomapp
axiom install dist/my-app-web.axiomapp
axiom run dist/my-app-web.axiomapp --target web

axiom install FILE.axiomapp verifies and copies the intact artifact to the local content-addressed application cache. axiom package combines compatible target artifacts into one multi-target artifact, and axiom run runs a packaged artifact. See App lifecycle and targets for the full flow.