CLI Commands

Complete reference for all grimorio CLI commands.

init

Scaffolds the configuration file, specs directory, and an example tokens file.

grimorio init

Creates:

• grimorio.config.ts -- project configuration
• specs/ -- directory for component specs
• tokens.json -- default token set (13 W3C DTCG categories)

---

spec:infer

Analyzes a component file and generates a JSON spec from it using static analysis.

grimorio spec:infer <file>

Examples:

grimorio spec:infer src/components/Button.tsx
grimorio spec:infer src/components/Modal.vue -o specs/modal.json

Extracts: props, variants (cva), accessibility attributes, Tailwind classes, and dependencies.

Option	Description
--output, -o	Output path for the spec file

---

add

Creates a component spec. If the name matches a built-in preset, generates a complete spec. Otherwise, creates an improved skeleton with accessibility defaults.

grimorio add <name>

Examples:

grimorio add Button                         # uses built-in preset
grimorio add Select -d "Country picker"     # preset + custom description
grimorio add CustomWidget                   # improved skeleton
grimorio add Dialog -p dialog               # explicit preset
grimorio add --list-presets                  # list available presets

Built-in presets: button, input, select, checkbox, dialog, card, avatar, badge, tabs, textarea.

Option	Description
--preset, -p	Use a specific preset
--description, -d	Component description
--category, -c	Component category
--list-presets	List available presets and exit

---

validate

Validates all components against their specs and design tokens.

grimorio validate

Examples:

grimorio validate
grimorio validate --level strict
grimorio validate --watch
grimorio validate --watch --level strict

Option	Description
--level	Validation level: basic, standard (default), or strict
--watch	Re-validate on file changes (300ms debounce)

Validation levels:

Level	Checks
basic	Required props
standard	+ variants, hardcoded token values, ARIA attributes
strict	+ extra props/variants, anatomy parts, all keyboard interactions

Exits with code 1 if any validation errors are found.

---

figma:import

Imports component specs from Figma. Maps Figma component properties to props, variants, slots, token mappings, anatomy, states, and events deterministically.

grimorio figma:import <url>

Examples:

grimorio figma:import "https://figma.com/design/ABC/..." --component Button
grimorio figma:import "https://figma.com/design/ABC/..."
grimorio figma:import "https://figma.com/design/ABC/...?node-id=1-234"

Option	Description
--component	Component name to find in the file
--token	Figma API token (or set FIGMA_TOKEN env var)
--output, -o	Output path for the spec

Mapping rules:

Figma property	Spec field
VARIANT	variants + props
BOOLEAN	props (boolean)
TEXT	props (string)
INSTANCE_SWAP	slots
Bound variables	tokenMapping

---

figma:validate

Validates a Figma component against an existing spec. Reports differences in props, variants, token mappings, slots, anatomy, states, and events.

grimorio figma:validate <url>

Examples:

grimorio figma:validate "https://figma.com/design/ABC/..." --component Button
grimorio figma:validate "https://figma.com/design/ABC/..." --component Button --json

Option	Description
--component	Component name to validate
--token	Figma API token (or set FIGMA_TOKEN env var)
--json	Output as JSON

Exits with code 1 if differences are found.

---

tokens:list

Lists design tokens from your tokens file.

grimorio tokens:list

Examples:

grimorio tokens:list                    # tree view (default)
grimorio tokens:list --flat             # flat list with full paths
grimorio tokens:list --type color       # filter by $type
grimorio tokens:list --json             # output as JSON
grimorio tokens:list --json --flat      # flat JSON
grimorio tokens:list --theme dark       # list a specific theme

Option	Description
--flat	Show flat list instead of tree
--type	Filter by $type (e.g., color, dimension)
--json	Output as JSON
--theme	Theme to list (multi-theme configs)

---

tokens:validate

Validates tokens against the W3C DTCG schema and cross-references with component specs.

grimorio tokens:validate

Examples:

grimorio tokens:validate
grimorio tokens:validate --watch

Option	Description
--watch	Re-validate on file changes (300ms debounce)

Checks performed:

1. Schema validation -- validates against TokenFileSchema
2. Statistics -- counts tokens by $type, reports deprecated tokens
3. Cross-reference -- missing (error), deprecated used (warning), orphans (info)

Exits with code 1 if schema errors or missing tokens are found. Multi-theme configs validate all themes.

---

tokens:export

Exports design tokens to CSS, SCSS, JS, or Tailwind format.

grimorio tokens:export <format>

Examples:

grimorio tokens:export css
grimorio tokens:export scss --prefix ds
grimorio tokens:export js --no-descriptions
grimorio tokens:export tailwind -o tailwind.tokens.js
grimorio tokens:export css --theme dark

Option	Description
--output, -o	Output file path (default: stdout)
--prefix	Prefix for CSS/SCSS variable names
--no-descriptions	Omit description comments
--theme	Export a specific theme

Formats:

Format	Output	Example
css	CSS custom properties in :root {}	--color-primary: #3b82f6;
scss	SCSS variables	$color-primary: #3b82f6;
js	ES module exports	export const colorPrimary = "...";
tailwind	Tailwind theme.extend config	colors: { primary: "..." }

---

mcp:serve

Starts an MCP server over stdio for AI assistant integration.

grimorio mcp:serve

Exposes 16 tools, 4 prompts, and 2 resources. See MCP Server for details and client configuration.