init reference

specui new <path> is specui init --flat with a required target name. All flags below apply to init; new accepts the subset --preset, --themes, --platforms, --agents-md, --git, and --force (defaults for a flat repo: no AGENTS.md, no git).

---

Presets (--preset)

Preset	Description
web-app	Default SaaS / product UI scaffolding
mobile-app	Mobile-first scope in front matter
marketing-site	Marketing / landing patterns
dashboard-data-dense	Dense data UI
design-system-library	Large catalog starter
blank	Minimal lists; you define components/patterns

---

Target and layout

Flag	Description
--target <dir>	Write the contract here (default: cwd)
--flat	No .specui/ wrapper — contract at target root (new sets this)
--force	Overwrite an existing .specui or flat SPEC.md
--dry-run	Print the plan only; no writes

---

Product metadata

Flag	Description
--name <string>	Product name in SPEC.md
--category <string>	e.g. web-app, marketing-site
--audience <string>	Primary users

---

Scope

Flag	Values
--themes	light, dark, high-contrast (comma-separated)
--platforms	web, ios, android, flutter, desktop, other
--density	comfortable, compact, dense
--components	Comma list of required kebab component ids
--patterns	Comma list of required kebab pattern ids
--imagery	photo, illustration, ai-allowed
--rtl	Enable RTL requirement
--no-rtl	Disable RTL
--data-viz	Charts / data visualization in scope
--no-data-viz	Disable data viz

---

Agents and editor files

Flag	Description
--agents-md	Inject SpecUI block into AGENTS.md (default)
--no-agents-md	Skip AGENTS.md
--agent-tools <list>	cursor, claude, codex, copilot, gemini, windsurf
--no-agent-tools	Skip per-tool stub files
--starter-kit	Seed 2 bundled rules + 2 skills
--seed-rules / --no-seed-rules	Bundled rules templates
--seed-skills / --no-seed-skills	Bundled skills templates

If --agents-md is set and the tools list is empty, the default is cursor.

---

CI and git

Flag	Description
--ci github	Add GitHub Actions validate workflow (default when CI enabled)
--no-ci	Skip the CI template
--git	git init + initial commit in target
--no-git	Skip git (default)

---

Examples

Minimal blank project:

specui init --preset blank --target ./my-app --no-ci --no-git

Full agent + CI setup:

specui init \
  --name "Acme" \
  --preset web-app \
  --themes light,dark \
  --platforms web \
  --agents-md \
  --agent-tools cursor,claude,copilot \
  --starter-kit \
  --ci github

Publishable design system:

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

Preview the plan before committing to anything:

specui init --dry-run --preset web-app --target /tmp/preview

---

Exit codes

Code	Cause
0	Success or dry-run
2	Invalid flags, missing preset, existing contract without --force

---

Next steps

• Quick start
• CLI reference — all commands
• Agents & MCP