Get Started

Get a running XMLUI app, an AI assistant (Claude Code or Codex) that knows the XMLUI docs, and a built-in Inspector for debugging — in under 5 minutes.

Choose your platform

macOS / Linux

Install the CLI

curl -fsSL https://github.com/xmlui-org/xmlui-cli/releases/latest/download/install.sh | sh

The script does exactly this:

Detects your OS and CPU architecture and chooses the matching release artifact.
Downloads that archive plus the published SHA256SUMS file.
Verifies the archive's SHA256 before installing anything.
Extracts the archive into a temporary directory.
Finds the bundled xmlui binary and runs xmlui install.
xmlui install copies the binary to /usr/local/bin if that directory is writable, otherwise to ~/.local/bin.
On macOS, xmlui install also removes the quarantine attribute from the installed binary.
If the install directory is not already on PATH, xmlui install prints the shell line to add, or you can re-run with xmlui install --add-to-path.

Confirm the install:

xmlui --version

Audit-friendly alternative

If you'd rather not run a remote shell script:

curl -fsSLO https://github.com/xmlui-org/xmlui-cli/releases/latest/download/SHA256SUMS
curl -fsSLO https://github.com/xmlui-org/xmlui-cli/releases/latest/download/xmlui-macos-arm64.tar.gz   # or your platform
shasum -a 256 -c SHA256SUMS --ignore-missing
tar -xzf xmlui-*.tar.gz
./xmlui install

Other platforms: replace xmlui-macos-arm64.tar.gz with xmlui-macos-intel.tar.gz, xmlui-linux-amd64.tar.gz, or xmlui-windows-amd64.zip.

Register the MCP server

For Claude Code:

claude mcp add --scope user xmlui xmlui mcp

This adds an xmlui server entry to ~/.claude.json at user scope, so Claude Code can call the XMLUI MCP tools in any project. Restart Claude Code so it picks up the new server.

For Codex:

codex mcp add xmlui -- xmlui mcp

This adds an [mcp_servers.xmlui] entry to ~/.codex/config.toml at user scope, so Codex can call the XMLUI MCP tools in any project. Restart Codex so it picks up the new server.

To confirm, ask your assistant: "What XMLUI MCP tools do you have?" You should see a list of about a dozen xmlui_* tools.

Troubleshooting

Your assistant doesn't see XMLUI tools. Run xmlui doctor. It lists every place an xmlui MCP server is registered (across both Claude and Codex), validates the binary path, and runs --version. If it reports duplicates within one assistant's scopes, remove all but one.
Update. Re-run the install command.
Uninstall. Remove the xmlui MCP server entry (claude mcp remove xmlui and/or codex mcp remove xmlui), then delete the binary from /usr/local/bin/xmlui or ~/.local/bin/xmlui.

Windows

Install the CLI

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://github.com/xmlui-org/xmlui-cli/releases/latest/download/install.ps1 | iex"

The PowerShell installer downloads xmlui-windows-amd64.zip, verifies its SHA256 against the published SHA256SUMS, extracts xmlui.exe, installs it to ~/bin, and adds that directory to your user PATH.

Confirm the install in a new PowerShell window:

xmlui --version

Audit-friendly alternative

If you'd rather not run a remote PowerShell script:

Invoke-WebRequest https://github.com/xmlui-org/xmlui-cli/releases/latest/download/SHA256SUMS -OutFile SHA256SUMS
Invoke-WebRequest https://github.com/xmlui-org/xmlui-cli/releases/latest/download/xmlui-windows-amd64.zip -OutFile xmlui-windows-amd64.zip
Get-FileHash .\xmlui-windows-amd64.zip -Algorithm SHA256
Expand-Archive .\xmlui-windows-amd64.zip -DestinationPath .\xmlui-expand -Force
.\xmlui-expand\xmlui.exe install --add-to-path

Register the MCP server

For Claude Code:

claude mcp add --scope user xmlui xmlui mcp

This writes the xmlui MCP server entry into ~/.claude.json. Restart Claude Code so it picks up the new server.

For Codex:

codex mcp add xmlui -- xmlui mcp

This writes the [mcp_servers.xmlui] entry into ~/.codex/config.toml. Restart Codex so it picks up the new server.

To confirm, ask your assistant: "What XMLUI MCP tools do you have?" You should see a list of about a dozen xmlui_* tools.

Troubleshooting

Your assistant doesn't see XMLUI tools. Run xmlui doctor. It lists every place an xmlui MCP server is registered (across both Claude and Codex), validates the binary path, and runs --version. If it reports duplicates within one assistant's scopes, remove all but one.
Update. Re-run the install command.
Uninstall. Remove the xmlui MCP server entry (claude mcp remove xmlui and/or codex mcp remove xmlui), then delete the binary from ~/bin/xmlui.exe.

Create and run the weather app

xmlui new xmlui-weather
cd xmlui-weather
xmlui run

The dev server opens the app in your default browser. The app includes the Inspector (magnifying-glass icon, top right), which records traces of everything your app does so you and your assistant can see what's going on.

Before you start asking your assistant (Claude Code or Codex) for help with the app, make sure it's working in the xmlui-weather directory. If needed, ask it to switch to that directory.

Install, trace, fix, and extend the xmlui-weather app

Verify your assistant can see the MCP tools

In Claude Code or Codex:

What XMLUI MCP tools are available to you?

The assistant should enumerate xmlui_search, xmlui_component_docs, xmlui_examples, xmlui_list_howto, xmlui_distill_trace, and others. If it doesn't, run xmlui doctor to diagnose.

Drive the app, capture a trace, distill and analyze

The app loads with weather for Santa Rosa, CA. Open the Inspector and expand the Startup phase to see the distilled view of what happened.

Now switch to a different city, then open the Inspector again, click Export, and tell your assistant:

Distill and analyze the trace.

Your assistant calls the xmlui_distill_trace tool, which returns a structured per-step summary of every interaction, API call, and value change. The assistant narrates the result back to you.

Fix the layout

The default layout isn't great. Ask your assistant:

Center the input box and button as a group, and center the radio group on a new row.

Expect it to use the MCP tools, especially xmlui_search_howto, with xmlui_search as a general fallback, to find a documented how-to that provably works, edit Main.xmlui, and tell you to refresh. Don't be afraid to challenge it to cite evidence. If the answer is wrong, screenshot the broken layout, paste it into the chat, and ask it to look harder.

Add a feature

Ask your assistant:

Add three tables that report hourly temperatures for three user-specifiable cities.

Same pattern: the assistant searches the docs via the MCP tools, edits the app, you refresh. If something breaks, export a trace and ask it to distill it.

General troubleshooting

xmlui not found on PATH. Re-run xmlui install --add-to-path, or follow the instructions printed by the original install.sh.

More demo apps

xmlui-hello-world: A minimal XMLUI app. Try it in the online playground.
xmlui-invoice: A complete database-backed app. Run it with xmlui run https://github.com/xmlui-org/xmlui-invoice/releases/latest/download/xmlui-invoice.zip.