1. Docs
2. CLI & Extend
3. CLI

CLI 1.2.2

Build custom CSS, manage icons, print HTML blueprints, compile design tokens, and scan your project for security and accessibility issues — all from the command line. Deutsch: CLI

When to use

• Build custom CSS, scan HTML, audit performance, and generate docs / search indexes.
• Use plan → scaffold → review for experimental prompt→HTML workflows (beta).

When not

• Do not treat plan/review/meta as a finished AI design system or Studio product.
• Do not invent Utility Engine CLI commands that are still planned.

Installation

Install VelinStyle globally or run it on-demand with npx:

# Install the published package
npm install -D @birdapi/velinstyle

# Or run without installing
npx @birdapi/velinstyle
# binary name: velinstyle

Commands Overview

All available commands at a glance:

Init

Creates a velinstyle.config.js file in the current directory. The interactive prompt lets you select which CSS layers to include:

velinstyle init

This generates a config file with your chosen layers, theme, output path, and scan settings.

Build

Builds a custom CSS bundle based on the layers defined in your config file.

# Build using velinstyle.config.js
velinstyle build

# Specify output file
velinstyle build --output dist/styles.css
velinstyle build -o dist/styles.css

# Minify the output
velinstyle build --minify

# Marketing lite layers
velinstyle build --preset lite -o ./velinstyle-lite.css --minify

# Production Builder (content-aware — preferred for go-live)
velinstyle build --production --explain
velinstyle production . -o ./dist/velin-production

Production

Alias command for the Production Builder. See Production Builder guide.

velinstyle production [path] --out ./dist/velin-production --explain --watch --report ./report.json

Velin Experience

Velin Experience is the product layer behind the velinstyle entrypoint — Output Contract, Event Bus, Registry-driven Help, Themes/Modes. The full CLI surface renders through Experience; the binary is only the door. Raw stdout stays for pipes / CI (--json, --sarif, blueprint without -o).

• Modes: compact · standard · dashboard · verbose · debug · json · sarif · markdown
• velinstyle dashboard — project overview
• --record + velinstyle replay <record.json> — capture and replay
• Config: velinstyle-cli.json (theme, output, analytics, record)

velinstyle doctor .
velinstyle themes
velinstyle skills list
velinstyle dashboard
velinstyle doctor . --record
velinstyle replay .velin/records/doctor-….json --output markdown

Guide: Velin Experience. Production Content Scanner treats .blade.php as first-class (scan your project, not only HTML).

Velin Security Suite

Velin Security Suite is the CLI surface; Velin Security Engine (core/security/) holds the Registry and rules. Auto-detect repo vs consumer; focused subcommands for CI, deps, secrets, and publish gates.

• doctor · scan · audit · publish · ci · deps · secrets · report
• Scores: Security Score · Dependency Health · Release Health · Timeline
• Flags: --repo · --consumer · --json · --strict

velinstyle security doctor .
velinstyle security deps .
velinstyle security publish
velinstyle security report --out ./.velin/security/report

Guide: Velin Security Suite · since 1.2.3.

Velin Motion

Page Motion is the Motion Design System — full Registry (presets, timelines, transitions, physics stubs, composers, triggers, policies, blueprints) plus a first-class Trigger Engine. Studio-ready data model; Studio UI later.

• 1.2.6: list · presets · doctor · scan · policy · demo
• 1.2.7: analyze · review · report · optimize · blueprint
• Attrs: velin-motion + velin-trigger (+ timeline / sequence)

velinstyle motion list
velinstyle motion doctor .
velinstyle motion analyze .
velinstyle motion blueprint landing -o motion.html
velinstyle motion demo

Clip Motion (1.3.0) — image→clip via package @birdapi/velinstyle-motion (local HTML/CSS or optional PixVerse AI). Separate from Page Motion.

AI animations are produced by external providers. PixVerse is a supported provider.

• Create / wizard: motion create · shortcuts zoom · pan · rotate · particles
• Batch / compose: atelier · transition · sequence · export · usage
• Providers: motion providers · setup: motion setup pixverse
• Presets: motion presets --clips
• Flags: --ai · --style ai · --yes · --provider

velinstyle motion providers
velinstyle motion setup pixverse
velinstyle motion create hero.png --preset cinematic --yes
velinstyle motion create logo.png --ai --yes
velinstyle motion atelier ./assets --count 10 --yes
velinstyle motion presets --clips
velinstyle motion usage

Guides: Velin Motion · Motion Clips.

Windows notes

On Windows, velinstyle build loads velinstyle.config.js via pathToFileURL so drive-letter paths do not throw ERR_UNSUPPORTED_ESM_URL_SCHEME. Run velinstyle doctor to smoke-test the config import. Prefer relative vendor paths (vendor/velinstyle/) over absolute /dist/... sprite URLs.

Unknown CLI verbs print Unknown command '…' with suggestions and exit 1 (they no longer dump full help with a success-looking exit).

create landing copies vendor into the target directory and aims for a zero-warning scan (no inline styles; proper label for/id). Prefer bootFromDOM / runtime tree-shake in production; the scaffold falls back to the vendor components bundle offline.

Icons

Manage icon providers and generate optimized icon bundles.

Subcommands

# List all available icon providers
velinstyle icons list

# Add icons from several providers (downloads into icons/svg/ in the package)
velinstyle icons add lucide --icons menu,search,check
velinstyle icons add heroicons --icons arrow-left --variant outline

# Rebuild the combined sprite used by the framework
velinstyle icons build

# Remove every SVG that was downloaded from one provider, then rebuild
velinstyle icons remove heroicons
velinstyle icons build

Run these commands from the root of a VelinStyle clone (or ensure icons/svg/ resolves to your project). After icons build, referenced sprites are updated for local development.

Blueprint

Print copy-paste HTML wired for VelinStyle classes and tokens. Run velinstyle blueprint list for the machine-readable list, then emit one fragment with blueprint <id> (stdout or -o).

velinstyle blueprint list
# Example output shape (IDs only — exact order may vary):
#   alert-stack
#   breadcrumb-bar
#   card-grid
#   footer-simple
#   form-contact
#   form-login
#   hero-section
#   layout-dashboard
#   modal
#   navbar-header
#   pagination-bar
#   search-field
#   sidebar-layout
#   table-responsive
#   bottom-nav-mobile
#   cookie-consent
#   empty-state
#   filter-bar
#   notification-center
#   onboarding
#   pricing-table
#   settings-panel

velinstyle blueprint hero-section -o snippets/hero.html
velinstyle blueprint sidebar-layout -o snippets/sidebar.html

Tokens build

Reads JSON with a tokens map (keys become --kebab-case custom properties) and prints CSS or writes --output.

velinstyle tokens build --input tokens.json --output src/tokens-from-json.css

Blueprint catalog

Run velinstyle blueprint list for the authoritative list. Each id prints a static HTML fragment you can paste into a page or Storybook.

Prefix

Mechanical migration of class / className attributes in HTML, Vue, JSX, and TSX. Dry-run by default; use --write to apply.

velinstyle prefix ./src
velinstyle prefix ./src --write
velinstyle prefix ./src --bootstrap-display --write
velinstyle prefix ./src --map ./velinstyle-prefix-map.json --write

See also Migration guide.

Scaffold beta

Compose blueprint HTML from a text prompt (no API key). Full pages use the page registry; fragments use recipe intents. Guide: Prompt scaffolding.

velinstyle scaffold list-intents
velinstyle scaffold "Navbar with logo and search" -o nav.html
velinstyle scaffold "Steuerberater Landingpage mit Kontaktformular" -o out.html --json
velinstyle scaffold --atelier 04,07 -o compose.html --from ./atelier/library

Atelier compose (beta): --atelier builds a page from curated Atelier Library ids (not Velin Studio — Studio stays planned). Package guide: framework docs/guides/atelier-cli.md.

Atelier pull

Pull a curated Library showcase by number or id (36 → 36-calendar). SEO variants like 3600-… are not matched.

velinstyle atelier list
velinstyle atelier 36 -o ./velin-atelier/36-calendar
velinstyle atelier 04 --format vue -o ./src/atelier/04-pricing

Plan beta

Emit structured page plan JSON (sections, constraints) without rendering HTML. Foundation for Design Intelligence — coverage still expanding. With --atelier, emits Library compose plan refs (beta).

velinstyle plan "SaaS pricing page with FAQ" --json -o plan.json
velinstyle plan --atelier 04,07 -o atelier-plan.json

Review beta

Heuristic review gate (design, a11y, SEO, performance, conversion, prompt score). Not a substitute for human WCAG or security review.

velinstyle review out.html --prompt "SaaS pricing page with FAQ" --json

Meta beta

Build agent context artifacts. Knowledge Graph embeds are a seed catalog, not a complete design system. Guide: Velin-Meta.

velinstyle meta
velinstyle meta --base-url https://velinstyle.info
velinstyle meta page docs/components/buttons.html --write
velinstyle docs generate --scope meta

Performance audit

See Performance audit guide.

velinstyle perf audit ./public
velinstyle perf suggest ./public
velinstyle perf fix ./public --write

Docs generate

Extract Markdown API tables from source (components, tokens, utilities, CLI manifest, scanner rules). Output: docs/generated/ in the framework repo — browse snapshot locally.

npm run docs:generate
velinstyle docs generate
velinstyle docs generate --scope components
velinstyle docs generate --scope tokens

Scopes: all, components, attributes, tokens, utilities, cli, rules, a11y, meta.

Search index (extension)

Build dist/search-index.json for VelinSearch. Merged with site pages via python tools/build-search-index.py.

velinstyle search index --out dist/search-index.json
velinstyle search index --extra-html ../velinstyle-site/docs

Layout audit

Static checks for flex, grid, containers, and mobile visibility. Full guide: Responsive layout.

velinstyle layout audit ./src
velinstyle layout suggest page.html
velinstyle layout fix page.html --dry-run
velinstyle layout fix page.html --write

Scan

stable tooling — complementary to beta plan/review; use in CI.

A built-in scanner that walks HTML, CSS, and JavaScript for security, accessibility, and CSS hygiene. Use --severity to set the minimum level shown (errors always fail CI when present). --fix applies a small set of safe transforms; --fix-dry-run lists candidate files without writing.

In the framework repository, npm run test:contrast verifies OKLCH token pairs (4.5:1 / 7:1) — complementary to velinstyle scan.

# Scan current directory
velinstyle scan

# Scan a specific path
velinstyle scan ./src

# Output as JSON (useful for CI/CD)
velinstyle scan --format json

# Auto-fix issues where possible
velinstyle scan --fix

# Filter by severity
velinstyle scan --only pii --fix

velinstyle scan --severity error

# Preview auto-fix targets without writing
velinstyle scan --fix-dry-run

# Default lang when fixing missing <html lang> (BCP 47)
velinstyle scan --fix --fix-lang en

Scanner rules

Severities label findings in text/JSON output. --severity sets the minimum level included (warning hides info only). Filter with --only security, --only a11y, --only pii, --only css, --only wc. Round-3 rules include a11y/duplicate-id, css/unknown-velin-class, wc/invalid-attribute, HTML document.write, and a11y/target-size-min. Performance checks run via velinstyle perf audit (see Performance table). Review remains beta / heuristic — pair with axe/Lighthouse for ship gates.

Security

PII

Accessibility

CSS

Performance

Configuration

The velinstyle.config.js file controls all CLI behaviour. Here is the full structure:

export default {
  layers: ['tokens', 'reset', 'base', 'a11y', 'layout', 'components', 'utilities', 'security', 'helpers'],
  theme: null,
  output: './velinstyle-custom.css',
  minify: true,
  scan: {
    enabled: true,
    severity: 'warning',
    fix: false,
    ignore: ['node_modules', 'dist'],
  },
};