@dotgui/cli · toolchain
The command-line toolchain for .gui files
gui reads, writes, lints, renders, and packages .gui files — and installs the dotgui skill into the AI agents you already use. The CLI itself contains no AI: it is a fast, deterministic tool, and the design generation happens in your own agent.
Install
Two commands to a working setup — install the CLI, then point it at your agents.
npm install -g @dotgui/cliThen set up your agents
gui setup
gui setup detects your installed agents — Claude Code, Gemini CLI, and others — installs the dotgui skill into each one, and allowlists the gui command so agents run it without permission prompts. After that, asking any of those tools for a UI “in gui” just works.
Mental model
Your agent designs. gui keeps it valid.
You ──ask──▶ your agent ──uses──▶ dotgui skill ──calls──▶ gui
└─ lint · autofix · render · package A real agent — warm session, your best model, full tool-calling and vision — produces better UIs than anything a CLI could wrap around a model. So the CLI doesn't try. It owns the one thing only it can do perfectly: keeping every .gui file valid. Invalid markup never gets packaged — gui write lints first and exits non-zero with structured errors.
Commands
The full surface — every command is deterministic and package-aware.
| Command | What it does |
|---|---|
gui read home.gui | Print the markup; --assets lists assets, --preview / --asset name extract images to a viewable path. |
gui write home.gui | Save from stdin: lint → repack → regenerate preview.webp. Nothing is written if the markup is invalid. |
gui lint home.gui | Validate; --fix applies deterministic autofix and writes back. |
gui render home.gui -o out.png | Rasterize to PNG/WEBP/JPEG using a Chromium already on your machine. |
gui add · gui rm | Add or remove an asset inside the package — no manual unzipping, ever. |
gui set-preview home.gui shot.webp | Replace the embedded preview.webp with your own image. |
gui open home.gui | Open the file in the dotgui viewer. |
gui info home.gui | Name, root canvas, asset list, preview. |
gui pack · gui unpack | Folder ⇄ .gui conversion for hand-editing. |
gui setup | Install the dotgui skill into detected agents and allowlist gui. |
gui skill where · update | Manage the installed dotgui skill — print its location, or update it. |
For agents
A machine-friendly contract.
Agents are a first-class audience: read, write, lint, and info accept --json for machine-readable output and errors. Commands exit 0 on success and non-zero on failure — a lint or validation error exits 1 and writes nothing. All package operations run in an ephemeral shadow directory that is created and deleted within each command, so nothing is left on disk.
Frequently asked
Does the gui CLI generate designs?
No. The CLI contains zero AI — it lints, autofixes, renders, and packages. Design generation happens in your own agent (Claude Code, Gemini CLI, Cursor), which gui setup teaches the format via the dotgui skill.
What happens if my agent writes invalid markup?
gui write refuses to save it. The command lints first, exits non-zero with structured errors, and writes nothing — so a broken file can never become a .gui package. With --fix, deterministic autofix repairs common issues.
Does gui render need a bundled browser?
No download is bundled. Rendering drives a Chromium-based browser already installed on your machine — Chrome, Edge, Brave, or Chromium — via puppeteer-core. If none is found, gui write simply skips the preview instead of blocking the save.
Do I need to unzip .gui files to edit them?
Never. gui treats the package like a folder — read markup, list assets, add or remove files — and does the unzip/rezip in an ephemeral cache that cleans itself up.