Teo — the agent reads this page so you do not have to.

CLI reference

The ui-craft binary detects your AI coding harness and wires the full system — skill, commands, MCP gates, review agents, and design memory — in a single interactive pass.

Updated 2026-07-03

ui-craft is a static Go binary distributed via Homebrew and Scoop. It detects the AI coding harnesses you have installed (Claude Code, Cursor, Codex, Gemini, OpenCode) and wires the full system into each one’s native config in a single pass — no Node required at install time.

Install the binary

macOS:

brew install --cask educlopez/tap/ui-craft

Windows (Scoop):

scoop bucket add educlopez https://github.com/educlopez/scoop-bucket
scoop install educlopez/ui-craft

Direct download — grab the archive for your platform from the GitHub Releases page, extract, and place ui-craft on your PATH.

Interactive hub

Run ui-craft with no subcommand and it opens a full-screen menu instead of printing help:

> Start installation
  Install (this project)
  Upgrade
  Manage backups
  Managed uninstall
  Quit

• Start installation — the global installer described below (ui-craft install), writing to each harness’s home-directory config (~/.claude/, ~/.cursor/, etc).
• Install (this project) — a completely separate installer, scoped to the current working directory. See Project-scoped install.
• Upgrade — binary self-update (same as ui-craft self-update).
• Manage backups / Managed uninstall — same operations as the backup/uninstall subcommands, driven interactively.

Non-interactive contexts (no TTY, --yes, --json) skip the hub and print help or run the requested subcommand directly — the hub is purely the friendly entry point for a terminal session.

ui-craft install

Detects harnesses, presents an interactive Bubble Tea TUI for component selection, then wires each harness’s native config.

ui-craft install

Flags:

Examples:

ui-craft install --yes                         # non-interactive, all harnesses
ui-craft install --harness cursor              # target Cursor only, interactive
ui-craft install --yes --json                  # machine-readable JSON output
ui-craft install --yes --force                 # bypass plugin coexistence warning

What gets installed

Every install run snapshots the current harness configs first (see backup / rollback). If any step fails mid-plan, the whole plan rolls back automatically.

Choices are persisted

After a successful install, your selections are saved to ~/.ui-craft/state.json. The update command replays them at the new embedded version.

Project-scoped install

Reachable only from the interactive hub (“Install (this project)”) — a separate installer from ui-craft install, scoped to the current directory instead of your home folder. Same component menu, same harness detection, but everything lands project-local:

Project installs get their own backup/state tracking, entirely separate from the global installer: .ui-craft-backups/ and .ui-craft/state.json inside the project directory. Nothing is written to or read from $HOME.

Set up CI scanning at the same time. If the project’s git remote points at github.com, the hub offers to also run ui-craft-detect’s ci install right after the install finishes — wiring the anti-slop GitHub Action into the same repo in one flow. Not offered at all on non-GitHub remotes (GitLab, Bitbucket, no remote) — there’s nothing to gate to a fresh yes/no prompt if it can’t work.

ui-craft update

Re-applies all installed components for one or all harnesses at the version embedded in the current binary.

ui-craft update <harness>                         # update all components for a harness
ui-craft update <harness> --component mcp-gates   # update one component only

Use this after ui-craft self-update to propagate a new binary version to your harness configs.

ui-craft uninstall

Removes ui-craft components from a harness config. Existing snapshots remain for rollback.

ui-craft uninstall <harness>

ui-craft doctor

Health check, in two layers: is the CLI’s own install state sane, and — for every detected harness — is the skill actually correctly installed on disk.

ui-craft doctor
ui-craft doctor --json    # JSON output: { "ok": true, "checks": [...] }

Install-level checks: harness binaries detected, state.json parses, disk space at the backup root.

Per-harness skill-layer checks, run for every detected harness’s every installed skill file:

This diagnoses “is the skill correctly installed and well-formed” — it can’t tell you whether your AI agent is actually choosing to use it, since that’s the agent’s own runtime routing decision, not something readable from disk.

backup / rollback

Every install or update run snapshots harness configs before making changes. Snapshots are tar.gz archives with SHA-256 deduplication and a configurable retention policy.

ui-craft backup              # create a snapshot now, without installing
ui-craft backup list         # list all snapshots
ui-craft backup list --json  # list snapshots as JSON
ui-craft rollback <harness>  # restore the latest snapshot for a harness

Directory rollback never deletes other skills or agents you have installed — it only restores the ui-craft-managed entries.

ui-craft self-update

Upgrades the binary to the latest GitHub release.

ui-craft self-update
ui-craft self-update --json
# {"updated":true,"from":"v0.35.0","to":"v1.0.0","method":"direct"}

• If installed via Homebrew, prints brew upgrade ui-craft and exits — self-replacing a package-managed binary corrupts Homebrew’s state.
• If installed via Scoop, prints scoop update ui-craft and exits.
• For direct-download installs: fetches the latest release, verifies the sha256 against checksums.txt, and atomically replaces the binary.

ui-craft version

ui-craft version              # print binary + embedded mirror version
ui-craft version --json       # {"version":"v1.0.0","mirror":"v1.0.0"}
ui-craft version --check-parity  # verify Claude Code install matches expected surface

The version and mirror fields should match on an official release. If they differ, the binary was built with stale mirrors.

Global flags

These flags work with any subcommand:

Shell completions

ui-craft completion zsh   >> ~/.zshrc
ui-craft completion bash  >> ~/.bashrc
ui-craft completion fish  > ~/.config/fish/completions/ui-craft.fish
ui-craft completion powershell  # paste output into $PROFILE

Design memory

After install, the CLI creates .ui-craft/ in your project root — a typed directory of plain Markdown files that persist design decisions across sessions:

The files are plain Markdown, project-local, and committable. The skill’s load contract is documented in the repo’s SKILL.md.

Scripting / CI

The --yes --json combination is designed for CI pipelines:

ui-craft install --yes --json | jq '.installed[]'
ui-craft doctor --json | jq 'if .ok then empty else error("ui-craft health check failed") end'

Exit codes: 0 success, 1 user-aborted, 2 internal error.

Architecture

The binary embeds pre-built harness mirrors at build time via Go embed. goreleaser produces cross-platform archives for macOS, Linux, and Windows across amd64 and arm64. The binary version is the single coordinated semver documented in VERSIONS.md — one tag, three release artifacts (CLI binary, Claude Code plugin, ui-craft-mcp npm package).

Source

github.com/educlopez/ui-craft/tree/main/cli

Spotted something out of date? Open an issue on GitHub →