CLI

@loomdev-pro/cli is the command-line tool for LoomiUI Pro. Use it to scaffold production-ready starter apps, apply theme presets, add Pro block guides, and keep your codebase in sync as templates and packages change.

Unlike a typical runtime package, loomi-pro writes real source files directly into your repository. App shell files, routes, theme imports, and block guides are added as editable project files, so you own the code end to end. You can inspect every change in version control and customize freely without fighting generated output.

You’ll use the CLI during initial setup and later updates. It runs only in your terminal and is not shipped in your production app or runtime bundle.

What it does

Capability	Command	Outcome
Scaffold a new app	create	Full starter kit directory with routes, mock API wiring, and loomi.json
Configure an existing checkout	init	Writes or updates loomi.json for your template and framework
Apply a theme preset	theme, add theme:*	Updates @loomdev-pro/themes CSS import and config
Add Pro block guides	add	Writes editable block guides for your configured template
Compare with upstream	diff	Shows file diffs against the registry template
Validate setup	doctor	Checks config, dependencies, and registry auth
Upgrade paths	migrate	Runs codemods when Pro packages change conventions

Prerequisites

Before you install the CLI, make sure these are in place:

1. An active Pro license — Solo, Team, or Enterprise. See Pro licensing or browse Pro.
2. Node.js 18 or newer — @loomdev-pro/cli is a Node package. Use the same Node version you use for local development and production.
3. Pro registry access — add your account token to .npmrc so packages under @loomdev-pro/* can be installed.

 

The CLI package is @loomdev-pro/cli. Starter kits also install these Pro dependencies: @loomdev-pro/themes, @loomdev-pro/mock-data, @loomdev-pro/mock-api, and @loomdev-pro/template-core.

Installation

Configure registry auth

Before installing the CLI, make sure npm can access the Pro registry. Add these lines to either:

• ~/.npmrc (global, applies to all projects), or
• your project-level .npmrc (local to this repo).

@loomdev-pro:registry=https://registry.pro.loomiui.com
//registry.pro.loomiui.com/:_authToken=${LOOMI_PRO_TOKEN}

 

Get LOOMI_PRO_TOKEN from the customer portal after checkout. Team and Enterprise plans provide per-seat tokens, and you can rotate them in the portal anytime.

Install the CLI

You have two ways to run the CLI.

Install it globally if you want to use loomi-pro anywhere in your terminal:

pnpm add -g @loomdev-pro/cli

Or run it on demand (no global install required):

pnpm dlx @loomdev-pro/cli --help

After installing globally, confirm it works:

loomi-pro --help

You should see commands like init, create, add, theme, diff, doctor, and migrate.

Quick start

Create a new Admin Pro app (Next.js)

Use the interactive setup to choose your template, variant, and theme:

loomi-pro create acme-admin

 

For CI pipelines or automation scripts, pass flags so the command runs non-interactively (without prompts):

loomi-pro create acme-admin \
  -d \
  --template admin \
  --variant next-react \
  --theme default

cd acme-admin
pnpm install
pnpm dev

 

After you run create, Loomi Pro scaffolds your app and includes:

• A full variant source tree (src/, config files, package.json)
• Shared route content in content/ (from the template route manifest)
• A root loomi.json with your template, variant, theme, and registry details
• A theme CSS import in your layout/entry file: @loomdev-pro/themes/css/<preset>.css

Initialize a project you already have

If you already cloned or downloaded a Pro starter manually, use init to generate or refresh Loomi Pro metadata (like loomi.json) and validate your project setup:

cd my-admin-app
loomi-pro init

 

If you already know the values for your setup, you can skip the prompts and pass them directly with flags (for template, variant, and theme):

loomi-pro init -d --template saas --variant vite-lit --theme saas-admin

init tries to auto-detect Next.js vs Vite from package.json by checking common framework signals (such as dependencies and scripts), and can also infer the template from shell filenames (admin-shell.tsx, saas-shell.ts, etc.). If both checks are inconclusive, it falls back to interactive prompts so you can explicitly choose the correct template, variant, and theme for your project.

Validate before you build

loomi-pro doctor

Run doctor before every first install, CI setup, or upgrade to quickly surface missing dependencies, framework/template mismatches, invalid loomi.json values, and registry authentication issues. It gives you actionable fixes early, so you can resolve configuration problems in minutes instead of debugging a broken setup later.

Project configuration

Every Pro project managed by the CLI should have a loomi.json file at the repository root. This file is the source of truth for how Loomi Pro commands resolve your template, variant, theme, registry package, stylesheet path, and key path aliases, so keeping it present and accurate ensures init, add, diff, and doctor behave consistently across local development and CI environments:

{
  "$schema": "https://pro.loomiui.com/schema/loomi.json",
  "template": "admin",
  "variant": "next-react",
  "theme": "default",
  "registry": "@loomdev-pro/registry",
  "css": "src/app/globals.css",
  "aliases": {
    "components": "@/components",
    "pages": "@/app"
  }
}

Field	Description
template	Starter kit family: admin, saas, crm, or analytics
variant	Framework stack: vite-lit or next-react
theme	Active theme preset name (matches a file under @loomdev-pro/themes/css/)
registry	Registry package used for add and diff
css	Path to your global stylesheet (used by some theme operations)
aliases.components	Where generated components and blocks should live
aliases.pages	Where page-level additions are expected (@/app for Next.js)

 

Run loomi-pro init -f to regenerate loomi.json from scratch. The -f (--force) flag overwrites any existing configuration without preserving custom values, so only use it when you explicitly want to replace the current file. If you want to keep your current settings, run loomi-pro init without -f and update fields manually.

Commands

init

Initialize configuration for an existing project.

loomi-pro init [options]

Option	Description
-t, --template <name>	Starter kit: admin, saas, crm, analytics
-v, --variant <name>	Framework: vite-lit, next-react
--theme <name>	Theme preset (see Theme presets)
-d, --defaults	Skip interactive prompts
-f, --force	Overwrite an existing loomi.json
-c, --cwd <path>	Working directory (default: current directory)
-y, --yes	Skip confirmation prompts
-s, --silent	Mute non-error output

Examples

# Interactive — detects framework and shell when possible
loomi-pro init

# Automation-friendly
loomi-pro init -d --template admin --variant next-react --theme default

---

create

Scaffold a new project from a starter kit template.

loomi-pro create <name> [options]

Option	Description
-t, --template <name>	Starter kit
-v, --variant <name>	Framework variant
--theme <name>	Theme preset applied on first run
-d, --defaults	Skip interactive prompts
-c, --cwd <path>	Parent directory for the new project
-y, --yes	Skip confirmation prompts

Examples

loomi-pro create my-crm --template crm --variant next-react --theme fintech -d
loomi-pro create analytics-app --template analytics --variant vite-lit -d

Behavior

• Copies the variant source tree and shared content/ routes
• Rewrites workspace:* dependencies to published @loomdev-pro versions in package.json
• Writes loomi.json and sets the theme import in layout.tsx or main.ts
• Sets package.json name to the directory name you provided

During Pro monorepo development, create reads templates from disk when LOOMI_PRO_ROOT is set or auto-detected. Customer releases fetch template tarballs from the private registry.

---

add

Apply a Pro theme preset or generate Pro block guides inside your existing project.

For block names, the current CLI writes editable Markdown guides to your configured blocks directory (or a custom path passed with --path). This is useful for reviewing, editing, and iterating on block content before implementation.

loomi-pro add [items...] [options]

Option	Description
-a, --all	Add all block guides listed for the current template
-o, --overwrite	Replace existing files
--dry-run	Print planned changes without writing files
-p, --path <path>	Custom directory for generated block guides
-c, --cwd <path>	Working directory

 

Item syntax

• theme:<preset> — apply a theme (same as loomi-pro theme <preset>)
• <block-name> — write a block guide (e.g. dashboard-metrics)

Examples

loomi-pro add theme:fintech
loomi-pro add dashboard-metrics activity-feed
loomi-pro add theme:healthcare --dry-run
loomi-pro add --all

 

Available Pro block guides

Block	Description	Templates
dashboard-metrics	Four-up KPI cards with tone variants	admin, saas, crm, analytics
data-table	Sortable table wired to mock API data	admin, saas, crm, analytics
activity-feed	Timeline-style activity list	admin, crm
command-palette	Command-palette integration guide	all
filter-builder	Filter-builder integration guide	admin, analytics

Use --dry-run before --overwrite when updating files you may have customized.

---

theme

Apply or list theme presets from @loomdev-pro/themes.

loomi-pro theme [name] [options]

Option	Description
--list	Print all preset names and labels
--dry-run	Show import path changes without writing
-c, --cwd <path>	Working directory

Examples

loomi-pro theme --list
loomi-pro theme healthcare
loomi-pro theme enterprise-neutral --dry-run

 

Theme presets

Name	Label	Suggested kit
default	Loomi Default	admin
saas-admin	SaaS Admin	saas
fintech	Fintech	crm
developer-tools	Developer Tools	analytics
healthcare	Healthcare	any
education	Education	any
creator-tools	Creator Tools	any
ecommerce-admin	E-commerce Admin	any
enterprise-neutral	Enterprise Neutral	any
high-contrast	High Contrast	any
marketing-growth	Marketing Growth	any
legal-compliance	Legal Compliance	any

 

Browse live previews on Theme presets.

theme updates the CSS import in your root layout or entry file and saves the preset name to loomi.json.

---

diff

Compare local project files against the registry template for your configured kit.

loomi-pro diff [target] [options]

 

Option	Description
-c, --cwd <path>	Working directory

 

Examples

# Compare all comparable src files
loomi-pro diff

# Narrow to files matching a path fragment
loomi-pro diff admin-shell

Output is a unified diff per changed file. Use this after Pro updates to see what changed upstream before merging or re-applying blocks.

When template source is unavailable (no LOOMI_PRO_ROOT and no registry tarball), diff prints a configuration summary instead of file diffs.

---

doctor

Validate project health.

loomi-pro doctor [options]

Checks:

• loomi.json exists and parses against the schema
• Required @loomdev-pro/* packages appear in package.json
• Detected framework (Next.js vs Vite) matches loomi.json variant
• @loomdev-pro:registry auth is present in .npmrc

Exit code is non-zero when issues are found — useful in CI after scaffolding.

---

migrate

Run codemods when Pro packages introduce breaking changes.

loomi-pro migrate [migration] [path] [options]

Option	Description
-l, --list	List available migrations
-c, --cwd <path>	Working directory
-y, --yes	Skip confirmation prompts

 

Examples

loomi-pro migrate --list
loomi-pro migrate theme-imports
loomi-pro migrate mock-api src

 

Migration	Description
theme-imports	Normalize @loomdev-pro/themes CSS import paths to the current export format
mock-api	Align mock API imports with @loomdev-pro/mock-api route modules

Always commit or back up your code before running migrations.

Starter kits

Use starter kits to bootstrap common product foundations with prebuilt routes, screens, and integrations so you can start customizing immediately.

Template	Variants	What you get
admin	vite-lit, next-react, nuxt, laravel-inertia	Dashboard, users, teams, roles, billing, activity, reports
saas	vite-lit, next-react	Auth flows, onboarding, members, billing, usage, API keys
crm	vite-lit, next-react	Pipeline, leads, contacts, companies, deals, tasks, import
analytics	vite-lit, next-react	Overview, metrics, segments, cohorts, exports, alerts

 

Each variant includes:

• A client-side or App Router shell with navigation driven by content/routes.json
• Mock API routes backed by @loomdev-pro/mock-data fixtures
• Pro component registration via @loomdev-pro/template-core
• Theme CSS variables from your chosen preset

See the full catalog on Pro templates.

Framework variants

Choose a framework variant based on your existing stack and deployment model—the CLI keeps feature parity across options so teams can share the same product blueprint.

Variant	Description
next-react	Next.js App Router with a catch-all route, React bridges for web components (pro-elements.tsx), and mock API at src/app/api/[...path]/route.ts.
vite-lit	Vite SPA with Lit components, client-side routing in src/main.ts, and mock API via the @loomdev-pro/mock-api/vite plugin.
nuxt	Nuxt 3 with index and catch-all pages, Vue wrappers for Loomi web components, and mock API routes served by Nitro at server/api/[...path].ts.
laravel-inertia	aravel 11 with Inertia.js and Vue 3, a catch-all Laravel route rendering the admin shell, Vue wrappers for Loomi web components, and mock JSON endpoints defined in routes/api.php.

Pick the variant that matches your team’s stack. The CLI keeps the same routes and mock data across with only the rendering layer being different.

Workflows

CI: scaffold, validate, and build

Use this workflow in CI to generate a fresh Pro app, verify environment readiness, and ensure the project builds successfully before merging.

loomi-pro create ci-admin -d --template admin --variant next-react --theme default
cd ci-admin
loomi-pro doctor
pnpm install --frozen-lockfile
pnpm build

Add loomi-pro doctor to catch missing registry auth or dependency gaps before install.

Switch brand theme in an existing app

Use this workflow when you want to apply a different brand theme to an app you have already scaffolded, without regenerating the project.

loomi-pro theme fintech --dry-run   # preview
loomi-pro theme fintech
loomi-pro doctor

Restart your dev server so layout imports reload.

Review upstream template changes

After a Pro release:

loomi-pro diff
loomi-pro add dashboard-metrics --dry-run

Merge intentional customizations manually, or use --overwrite when you want the registry version to replace local files.

Upgrade import paths after a package release

Use this workflow to update legacy theme and mock API import paths after upgrading to a newer package version.

git commit -am "checkpoint before migration"
loomi-pro migrate theme-imports
loomi-pro migrate mock-api
loomi-pro doctor

Environment variables

Use these optional environment variables to control how the CLI resolves local template sources and registry authentication.

Variable	Description
LOOMI_PRO_ROOT	Absolute path to the Pro monorepo. Used by create and diff when developing templates locally. Auto-detected when the CLI runs inside the monorepo.
LOOMI_PRO_TOKEN	Common name for the registry auth token referenced in .npmrc examples

Troubleshooting

 

doctor reports missing registry auth

Confirm @loomdev-pro:registry and your auth token line exist in either ~/.npmrc or the project .npmrc, and that both point to the same registry host. If both files exist, ensure there is no conflicting duplicate config and that the active token is scoped to @loomdev-pro. You can quickly validate with npm config get @loomdev-pro:registry and retry after npm whoami --registry <registry-url>. Tokens expire when seats rotate — generate a new one from the customer portal, update .npmrc, and rerun loomi-pro doctor.

create cannot find template source

Set LOOMI_PRO_ROOT to the absolute path of your local Pro monorepo root (the directory containing the template packages). You can export it in your shell profile and verify with echo $LOOMI_PRO_ROOT, then rerun the command from the same terminal session. If you are a customer and not developing templates locally, use a published CLI release so templates are resolved from registry tarballs instead.

Framework mismatch in doctor

Your loomi.json variant does not match the framework/tooling detected in your project. Re-run loomi-pro init -f -v <variant> with the correct variant for your stack (for example, Next.js vs Vite), then reinstall dependencies. If the issue persists, compare your package.json and lockfile against the expected dependencies for that variant and remove stale packages before running doctor again.

Theme import did not update

Ensure your layout file imports @loomdev-pro/themes/css/<preset>.css (for example, @loomdev-pro/themes/css/indigo.css). The CLI updates known entry files only, so verify the import exists in src/app/layout.tsx (Next.js) or src/main.ts (Vite). If your project uses a custom entry path, add the import manually and place it before app styles so preset variables are available everywhere. After saving, restart your dev server to confirm the updated theme is applied.

Related

• MCP Server → — give AI assistants access to LoomiUI component docs while you build.
• Pro templates → — browse starter kits before running create.
• Theme presets → — preview presets before loomi-pro theme.
• Theme tokens → — understand the design tokens every preset exports.
• Pro → — licensing, catalog, and what’s included with Pro.