Skill — sigil-cli
All ten CLI commands in one place. Stop hunting through AGENTS.md,
SPEC.md, and the package README to figure out which command to run.
Quick reference
| Command |
Purpose |
npx create-sigil-app |
Scaffold a brand-new app: deps, token CSS, base preset, components, agent instructions. Interactive. |
npx @sigil-ui/cli init |
Set up Sigil inside an existing project. Detects framework, asks about use case, recommends presets, configures everything. |
npx @sigil-ui/cli convert |
End-to-end conversion of an existing project: deps, tokens, CSS import, agent instructions. Heavier than init. |
npx @sigil-ui/cli add <name...> |
Copy components into your project's components/ folder. They still consume var(--s-*). |
npx @sigil-ui/cli preset list |
Browse all 46 presets by category (44 named + default + template). |
npx @sigil-ui/cli preset <name> |
Switch the active preset — regenerates the project's token CSS file. |
npx @sigil-ui/cli preset create |
Scaffold a custom preset with base preset, color, and font prompts. |
npx @sigil-ui/cli design generate |
Create a DESIGN.md from the current preset + any token overrides. |
npx @sigil-ui/cli design compile |
Parse DESIGN.md → emit CSS + Tailwind v4 @theme + W3C JSON. |
npx @sigil-ui/cli design sync |
Update the compile sections inside DESIGN.md from the current token tables. |
npx @sigil-ui/cli design extract <url> |
Crawl a reference URL and produce a full DESIGN.md from the inferred tokens. |
npx @sigil-ui/cli inspire <url-or-file> |
Draft token CSS, a custom preset, and a preview page from a reference (color palette, font pairing, etc.). |
npx @sigil-ui/cli docs |
Generate local custom-library docs and llms.txt from the project's tokens + components. |
npx @sigil-ui/cli adapter <name> |
Add a CSS bridge so shadcn, Bootstrap, or Material variables inherit your Sigil tokens. |
npx @sigil-ui/cli diff |
Show token CSS changes since the last sigil write. Run before commits to verify intent. |
npx @sigil-ui/cli doctor |
Validate project health: config, tokens, components, deps, CSS imports, preset selection. Run after any change. |
Picking between commands
New project from scratch:
npx create-sigil-app
# Interactive: name, preset, framework. Drops you into a working app.
Existing project, never used Sigil:
npx @sigil-ui/cli init # lighter — just wires Sigil in
# OR
npx @sigil-ui/cli convert # heavier — also rewrites consumer files
Existing Sigil project, want a different look:
npx @sigil-ui/cli preset list
npx @sigil-ui/cli preset basalt
npx @sigil-ui/cli doctor
Existing Sigil project, want a CUSTOM preset:
npx @sigil-ui/cli preset create
# OR fully custom:
npx @sigil-ui/cli inspire https://stripe.com
npx @sigil-ui/cli design extract https://stripe.com
Pulling shadcn/Bootstrap/Material into Sigil tokens:
npx @sigil-ui/cli adapter shadcn
# Adds a CSS layer so the existing classes inherit --s-* values.
Adding components to an existing app:
npx @sigil-ui/cli add Button Card Hero Footer
# Copies the source files; they still read from var(--s-*).
Validating after any change:
npx @sigil-ui/cli doctor # exits non-zero if anything is broken
npx @sigil-ui/cli diff # show token CSS deltas before committing
What doctor checks
The doctor walks every layer of the system and reports the first problem it
finds. Expected configuration after init / convert:
package.json — @sigil-ui/components, @sigil-ui/tokens, @sigil-ui/presets deps presentapp/globals.css (or equivalent) — @import "@sigil-ui/tokens/css" present- Tailwind v4 —
@source rules cover the components directory
- A preset is selected (i.e. token CSS exists and matches a known preset)
- No
--sigil-* references (the legacy prefix; current is --s-*)
- No unmigrated demo-style
--r-* references (parallel token system)
- Hardcoded hex / px in component files (warning, not failure)
If any check fails, the output points at the file/line and the fix.
Programmatic equivalents
Every CLI command maps to a public function in @sigil-ui/tokens or
@sigil-ui/cli:
compile design → compileDesignMd(doc) from @sigil-ui/tokenspreset <name> → import("@sigil-ui/presets").presets[name]() then
compileToCss(preset.tokens) to emit CSSdesign extract → parseDesignMarkdown(markdown) from @sigil-ui/tokensdoctor → set of validators in @sigil-ui/cli/src/commands/doctor.ts
Use these when scripting CI checks or automation that doesn't want to spawn
the CLI binary.
See also
skills/sigil-design/SKILL.md — DESIGN.md format details, what each
section parses to, generator template.skills/sigil-preset/SKILL.md — preset rules: every preset must populate
all 33 categories.skills/sigil-tokens/SKILL.md — extending the token type system itself.skills/sigil-audit/SKILL.md — Playwright + static auditors that
complement doctor.
1---2name: sigil-cli3description: Consolidated reference for the @sigil-ui/cli command surface (init, convert, add, preset, design, inspire, adapter, docs, diff, doctor). Use when looking up what a CLI command does, picking between `sigil init` and `sigil convert`, scaffolding a new project, switching presets, generating DESIGN.md, validating a project, or any task that reaches for `npx @sigil-ui/cli`. Triggers on "sigil cli", "sigil init", "sigil convert", "sigil add", "sigil preset", "sigil design", "sigil doctor", "sigil diff", "sigil inspire", "sigil adapter", "sigil docs", "create-sigil-app", or "what does X do".4---56# Skill — sigil-cli78> All ten CLI commands in one place. Stop hunting through `AGENTS.md`,9> `SPEC.md`, and the package README to figure out which command to run.1011## Quick reference1213| Command | Purpose |14|---------|---------|15| `npx create-sigil-app` | Scaffold a brand-new app: deps, token CSS, base preset, components, agent instructions. Interactive. |16| `npx @sigil-ui/cli init` | Set up Sigil inside an existing project. Detects framework, asks about use case, recommends presets, configures everything. |17| `npx @sigil-ui/cli convert` | End-to-end conversion of an existing project: deps, tokens, CSS import, agent instructions. Heavier than `init`. |18| `npx @sigil-ui/cli add <name...>` | Copy components into your project's `components/` folder. They still consume `var(--s-*)`. |19| `npx @sigil-ui/cli preset list` | Browse all 46 presets by category (44 named + default + template). |20| `npx @sigil-ui/cli preset <name>` | Switch the active preset — regenerates the project's token CSS file. |21| `npx @sigil-ui/cli preset create` | Scaffold a custom preset with base preset, color, and font prompts. |22| `npx @sigil-ui/cli design generate` | Create a `DESIGN.md` from the current preset + any token overrides. |23| `npx @sigil-ui/cli design compile` | Parse `DESIGN.md` → emit CSS + Tailwind v4 `@theme` + W3C JSON. |24| `npx @sigil-ui/cli design sync` | Update the compile sections inside `DESIGN.md` from the current token tables. |25| `npx @sigil-ui/cli design extract <url>` | Crawl a reference URL and produce a full `DESIGN.md` from the inferred tokens. |26| `npx @sigil-ui/cli inspire <url-or-file>` | Draft token CSS, a custom preset, and a preview page from a reference (color palette, font pairing, etc.). |27| `npx @sigil-ui/cli docs` | Generate local custom-library docs and `llms.txt` from the project's tokens + components. |28| `npx @sigil-ui/cli adapter <name>` | Add a CSS bridge so shadcn, Bootstrap, or Material variables inherit your Sigil tokens. |29| `npx @sigil-ui/cli diff` | Show token CSS changes since the last `sigil` write. Run before commits to verify intent. |30| `npx @sigil-ui/cli doctor` | Validate project health: config, tokens, components, deps, CSS imports, preset selection. Run after any change. |3132## Picking between commands3334**New project from scratch:**35```36npx create-sigil-app37# Interactive: name, preset, framework. Drops you into a working app.38```3940**Existing project, never used Sigil:**41```42npx @sigil-ui/cli init # lighter — just wires Sigil in43# OR44npx @sigil-ui/cli convert # heavier — also rewrites consumer files45```4647**Existing Sigil project, want a different look:**48```49npx @sigil-ui/cli preset list50npx @sigil-ui/cli preset basalt51npx @sigil-ui/cli doctor52```5354**Existing Sigil project, want a CUSTOM preset:**55```56npx @sigil-ui/cli preset create57# OR fully custom:58npx @sigil-ui/cli inspire https://stripe.com59npx @sigil-ui/cli design extract https://stripe.com60```6162**Pulling shadcn/Bootstrap/Material into Sigil tokens:**63```64npx @sigil-ui/cli adapter shadcn65# Adds a CSS layer so the existing classes inherit --s-* values.66```6768**Adding components to an existing app:**69```70npx @sigil-ui/cli add Button Card Hero Footer71# Copies the source files; they still read from var(--s-*).72```7374**Validating after any change:**75```76npx @sigil-ui/cli doctor # exits non-zero if anything is broken77npx @sigil-ui/cli diff # show token CSS deltas before committing78```7980## What `doctor` checks8182The doctor walks every layer of the system and reports the first problem it83finds. Expected configuration after `init` / `convert`:8485- `package.json` — `@sigil-ui/components`, `@sigil-ui/tokens`, `@sigil-ui/presets` deps present86- `app/globals.css` (or equivalent) — `@import "@sigil-ui/tokens/css"` present87- Tailwind v4 — `@source` rules cover the components directory88- A preset is selected (i.e. token CSS exists and matches a known preset)89- No `--sigil-*` references (the legacy prefix; current is `--s-*`)90- No unmigrated demo-style `--r-*` references (parallel token system)91- Hardcoded hex / px in component files (warning, not failure)9293If any check fails, the output points at the file/line and the fix.9495## Programmatic equivalents9697Every CLI command maps to a public function in `@sigil-ui/tokens` or98`@sigil-ui/cli`:99100- `compile design` → `compileDesignMd(doc)` from `@sigil-ui/tokens`101- `preset <name>` → `import("@sigil-ui/presets").presets[name]()` then102 `compileToCss(preset.tokens)` to emit CSS103- `design extract` → `parseDesignMarkdown(markdown)` from `@sigil-ui/tokens`104- `doctor` → set of validators in `@sigil-ui/cli/src/commands/doctor.ts`105106Use these when scripting CI checks or automation that doesn't want to spawn107the CLI binary.108109## See also110111- `skills/sigil-design/SKILL.md` — DESIGN.md format details, what each112 section parses to, generator template.113- `skills/sigil-preset/SKILL.md` — preset rules: every preset must populate114 all 33 categories.115- `skills/sigil-tokens/SKILL.md` — extending the token type system itself.116- `skills/sigil-audit/SKILL.md` — Playwright + static auditors that117 complement `doctor`.
kevin-liu-01