Emulsify CLI
Build and use component systems in Drupal, WordPress, or standalone front ends.
Requirements
Emulsify CLI requires Node.js 24 or newer.
Installation
Install Emulsify CLI globally from npm:
npm install -g @emulsify/cli
Run the current command help at any time:
emulsify
emulsify --help
Quick Start
Create a Drupal starter project, install a system, and add components:
emulsify init "My Theme" ./web/themes/custom --platform drupal
cd ./web/themes/custom/my_theme
emulsify system install
emulsify component list
emulsify component install card
emulsify component create promo-card --directory molecules --type twig
Built-in platforms are drupal, wordpress, and none. For WordPress child themes, use the WordPress platform and starter:
emulsify init "My Theme" ./wp-content/themes --platform wordpress
When WordPress is auto-detected, Emulsify initializes child themes into the detected themes directory, such as wp-content/themes/my-theme or web/app/themes/my-theme for Bedrock.
To author a standalone, distributable component system, run system create
outside or inside any project. The target directory is created beneath the
selected parent directory:
emulsify system create "My System" --directory ./systems --platform "drupal || wordpress" --git
This creates ./systems/my-system with valid system and variant configuration,
an installable example-card component, repository documentation, a
.gitignore, and a license placeholder to replace before distribution.
Unless overridden, its required URL metadata uses obvious, schema-valid
https://TODO.invalid/... placeholders that must also be replaced before
publishing.
Add --dry-run to preview the normalized target, every generated file, and
whether Git would be initialized without changing the filesystem.
When components installed from another system have evolved into the basis of your own, detach the configured system before authoring a replacement:
emulsify system detach
Detaching removes only the system and variant entries from
project.emulsify.json. Components, project assets, and the cached system
repository stay in place. Run system create to scaffold a new system
repository, then move or copy the preserved components into that scaffold and
update system.emulsify.json; system create does not import them
automatically.
Interactive terminals can run emulsify component create with no arguments to
walk through the component name, type, and directory prompts. The type picker
always offers Twig, offers Twig SDC in Drupal projects, and offers React and Web
Component scaffolds when the project's package.json declares
@emulsify/core. When a choice is unavailable, the wizard explains why; when
Twig is the only suitable choice, it skips the one-item prompt. Likewise,
emulsify component install with no name presents the components available in
the installed system variant plus an explicit choice to install all components.
To customize component scaffolds, copy the CLI's built-in templates into the
project, then edit the resulting files under .cli/templates/:
emulsify component eject-templates twig
Run the command without a type in an interactive terminal to select one or more
component types. Use --all to eject every type non-interactively. Existing
overrides are protected unless --force is passed.
Prompts only run when standard input is a TTY. In CI, scripts, and commands with piped or redirected input, provide every required positional argument and flag; the CLI exits with an actionable error instead of waiting for input:
emulsify init "My Theme" ./web/themes/custom --platform drupal --yes
emulsify system create my-system --directory ./systems --platform none --git
emulsify system create my-system --directory ./systems --platform none --git --dry-run
emulsify system install compound
emulsify component install card --force
# Or install every available component:
emulsify component install --all
emulsify component create promo-card --directory molecules --type twig --force
emulsify component create card --directory molecules --type web-component --tag-name acme-card
emulsify component eject-templates --all
emulsify system detach --yes
For component installation, provide either a component name or --all, and use
--force when an existing destination should be replaced. For component
creation, provide the positional name plus --type and --directory, and use
--force when an existing generated component should be replaced. The existing
-y, --yes form remains available as a compatibility alias. Explicit
--type values are honored even when project detection would hide that choice
from the wizard. The deprecated --format default and --format sdc forms
remain available as aliases for --type twig and --type twig-sdc,
respectively, and print a deprecation warning. Web Components derive their tag
name from the component and project names; pass --tag-name to override it,
including when the derived value would be invalid in a non-interactive run.
For template ejection, provide the component type or --all outside a TTY; use
--dry-run to preview paths and --force only when existing customizations
should be replaced.
Documentation
Detailed documentation lives in docs.
| Topic | Use This When |
|---|---|
| CLI Reference | Looking up commands, aliases, options, and examples. |
| Project Initialization | Creating a new Emulsify project from a starter. |
| Systems | Listing, installing, detaching, or authoring component systems. |
| Components | Listing, installing, dry-running, or creating components. |
| Project Configuration | Understanding project.emulsify.json, variants, and structure mappings. |
| Component Template Overrides | Ejecting and customizing files used by emulsify component create. |
| Hooks And Cache | Understanding starter hooks, system hooks, and local repository cache behavior. |
| Development | Setting up this repository and running local checks. |
| Release | Understanding CI, semantic-release, and npm publishing. |
Command Overview
| Command | Alias | Description |
|---|---|---|
emulsify init [name] [path] | Initializes an Emulsify project from a starter. | |
emulsify audit [...args] | Runs the project-installed Emulsify Core audit. | |
emulsify system list | emulsify system ls | Lists built-in systems available for installation. |
emulsify system create [name] | Creates a standalone component-system repository. | |
emulsify system install [name] | Installs a system in the current Emulsify project. | |
emulsify system detach | Detaches the system and keeps project components. | |
emulsify component list | emulsify component ls | Lists components available from the installed system and variant. |
emulsify component install [name] | emulsify component i [name] | Installs one component from the installed system and variant. |
emulsify component create [name] | emulsify component c [name] | Creates a local component in the current Emulsify project. |
emulsify component eject-templates [type] | Writes editable built-in templates into the current project. | |
emulsify cache clear | Clears locally cached system repositories. |
emulsify audit is a convenience façade. The project-installed
@emulsify/core package remains the owner of the canonical emulsify-audit
machine interface, checks, findings, JSON schema, output, and exit behavior.
See the CLI reference and
Core audit documentation.
Contributors
See Contributors.