Skip to content

cli

Jump to bottom
github-actions[bot] edited this page Jul 4, 2026 · 1 revision

Run specui --help for the in-terminal summary. This page documents every command, for both consumer projects (.specui/) and flat design-system repos.

Path convention: [path] defaults to ./.specui, or the flat root where SPEC.md exists.

Global

Command Description
specui --version Package version
specui --help Command list

Create & scaffold

specui init

Scaffold the consumer layout: target/.specui/, optional AGENTS.md, CI, rules/skills.

See the init reference for all flags.

specui new <name>

Create a flat publishable repo (SPEC.md at root). A wrapper around init --flat.

specui new ./acme-ds --preset design-system-library

Register design (specui add)

Register before you write application code — that's the whole point of the contract.

specui add component <kebab-name>

specui add component primary-button --variants default,destructive --states default,hover,disabled

Creates .specui/components/<name>/ with a manifest and spec stubs.

specui add asset <type> <name>

Types: icon, illustration, photo, logo.

specui add asset logo acme-mark --link component:brand-mark

specui add token <group.path> <value>

specui add token color.text.primary "#111111" --theme light
specui add token color.text.primary "#eeeeee" --theme dark

specui add pattern <kebab-name>

specui add pattern empty-state

Quality gate

specui validate [path]

Validation — schema, registry, contrast, AGENTS.md.

specui validate .specui --strict --json

specui sync [path]

Rebuild manifests/registry.json; report broken links.

specui doctor [path]

Readiness report + validate. Exits 1 if validate fails.

Inspect

specui list [kind]

Kind Shows
all (default) Components, assets, patterns summary
components Component registry
assets Asset registry
patterns Pattern files
sources .specui-sources.yml entries
registries Built-in registry ids (e.g. shadcn)

Registries

specui get

Registries — shadcn and custom JSON URLs.

specui get --list
specui get button card
specui get --from https://example.com/r/item.json

Distribution

See Distribution for the full guide.

Command Summary
load <source> [--as name] Copy git/npm/dir into .specui
link <source> [--as name] Symlink source
unlink [--name name] Remove link
push [--remote origin] Commit + push flat DS repo
pull [--remote origin] Fetch flat DS repo
import <tarball|dir> Import into .specui
export [--format …] [--to path] Interop
update [--name source] Re-fetch source + validate
diff --from A --to B [--json] Token diff

Agents

Agents & MCP

specui rules

templates · add <name> [--from template] · list · show <name> · remove <name>

specui skills

templates · add <name> [--from template] · list · show <name> · remove <name>

specui spec

Print the normative SpecUI standard (docs/SPEC.md from the package).

specui spec --json

specui mcp

start · config · install-hook <cursor|claude|codeium|windsurf|continue>

Export formats (specui export)

--format Output
tarball (default) .tgz archive
dir Directory tree
designmd DESIGN.md-style front matter
dtcg DTCG JSON (--theme)
tailwind JS theme extend (--theme)
css CSS custom properties (--theme)
json Flat JSON tokens 
specui export --format tailwind --theme light --to ./tw.js --from .specui

Exit codes (common)

Code Typical cause
0 Success
1 validate / doctor / update validation failure
2 Usage error, missing path, die() messages

Environment

  • Node 18+
  • Network required for get (unless you use file:// / local JSON)
  • Git required for load/push/pull from remotes

Next steps

Getting started

How-to guides

Reference

Community

Clone this wiki locally