cli-reference.md

CLI Reference

Emulsify CLI installs as the emulsify binary.

emulsify
emulsify --help
emulsify <command> --help

The examples below reflect the command definitions in src/index.ts and the generated help from the built dist/index.js entry point.

Commands

Command	Alias	Description
emulsify init [name] [path]		Initialize an Emulsify project from a starter.
emulsify audit [...args]		Run the project-installed Emulsify Core audit.
emulsify system list	emulsify system ls	List built-in systems available for installation.
emulsify system create [name]		Create a standalone, distributable component system.
emulsify system install [name]		Install a system in the current Emulsify project.
emulsify system detach		Detach the system and keep project components.
emulsify component list	emulsify component ls	List components available from the installed system and variant.
emulsify component install [name]	emulsify component i [name]	Install a component from the installed system and variant.
emulsify component create [name]	emulsify component c [name]	Generate a new local component in the current project.
emulsify component eject-templates [type]		Write editable built-in component templates into the project.
emulsify cache clear		Clear locally cached system repositories.

emulsify components is an alias for the canonical emulsify component command group, and accepts the same component subcommands and options.

init

emulsify init [name] [path]

Options:

Option	Description
-m, --machineName <machineName>	Machine-friendly project folder and config name. If omitted, the CLI derives it from the project name. Drupal machine names use underscores.
-s, --starter <repository>	Starter Git repository to clone.
-c, --checkout <commit/branch/tag>	Starter commit, branch, or tag to check out after clone.
-p, --platform <platform>	Platform to use when auto-detection is unavailable or should be overridden. Built-in platforms are drupal, wordpress, and none.
-y, --yes	Accept default values for missing init options without prompting.

When --platform is not provided and the platform cannot be detected, interactive terminals prompt with drupal, wordpress, and none.

WordPress auto-detection creates child themes inside the detected themes directory:

• Standard WordPress: wp-content/themes/<machine-name>
• Bedrock: web/app/themes/<machine-name>

The built-in WordPress starter is https://github.com/emulsify-ds/emulsify-wordpress-starter.

Examples:

emulsify init "My Project" ./projects --platform none
emulsify init "My Theme" ./web/themes/custom --platform drupal
emulsify init "My Theme" ./wp-content/themes --platform wordpress
emulsify init "My Theme" ./web/themes/custom --platform drupal --machineName my_custom_theme
emulsify init "My Project" ./projects --starter https://github.com/emulsify-ds/emulsify-starter --checkout main --platform none

audit

emulsify audit [...args]

This command is a convenience façade for the emulsify-audit executable declared by the selected project's installed @emulsify/core package. It resolves Core from --root <dir> when supplied, or from the current directory, then forwards every argument plus stdin, stdout, stderr, and the Core process exit status without decoration.

emulsify audit --help
emulsify audit --json
emulsify audit --root /path/to/project --json --fail-on warn

Core must be installed in the selected project. emulsify-audit remains the canonical Core-owned machine interface; Core owns its audit checks, findings, JSON schema, documentation, output, and exit behavior. See the Emulsify Core audit documentation for the current contract and options.

cache clear

emulsify cache clear

Removes all locally cached repository entries under ~/.emulsify/cache. The command reports the number of cache buckets and entries removed, and succeeds when the cache is already empty.

Options:

Option	Description
--dry-run	Report cache contents without removing any files.

Examples:

emulsify cache clear --dry-run
emulsify cache clear

system list

emulsify system list
emulsify system ls

Lists the built-in system names and repositories known to this CLI version.

system create

emulsify system create [name]

Creates a standalone component-system repository. It does not require an Emulsify project and does not change project.emulsify.json. The supplied name is normalized to a lowercase, hyphenated machine name. The target is the normalized name beneath the parent passed to --directory; for example, "My System" --directory ./systems creates ./systems/my-system.

Options:

Option	Description
-d, --directory <directory>	Parent directory in which the normalized system directory is created.
-p, --platform <platform-expression>	Variant target: none, a concrete platform, or a compound compatibility expression.
--git	Initialize a Git repository in the generated system.
--no-git	Generate the system without initializing Git.
--homepage <url>	Replace the generated TODO.invalid homepage metadata.
--repository <url>	Replace the generated TODO.invalid repository metadata.
-y, --yes	Accept defaults for every missing prompt value.
--dry-run	Preview the target, generated files, and Git action without changing the filesystem.

In an interactive terminal, missing name, parent directory, platform expression, and Git choice are prompted. In a non-interactive environment, provide them as arguments and flags or use --yes; the command exits with an actionable error instead of waiting for input.

With --yes, missing values default to:

• Name: custom-system
• Parent directory: ./
• Platform expression: none
• Git initialization: enabled

The generated homepage and repository metadata use the schema-valid reserved placeholders https://TODO.invalid/<name> and https://TODO.invalid/<name>.git unless --homepage or --repository is provided. The TODO.invalid host is deliberately non-resolving and must be replaced before publishing.

The command refuses to overwrite an existing target. A successful scaffold contains:

my-system/
├── .gitignore
├── LICENSE
├── README.md
├── system.emulsify.json
└── components/
    └── example-card/
        ├── example-card.scss
        ├── example-card.stories.js
        ├── example-card.twig
        └── example-card.yml

The generated example-card is marked as required, so installing the system also proves that its component source layout is usable. --git additionally creates the .git/ metadata directory with main as the initial branch.

Use --dry-run to inspect the normalized target, every generated file, and whether Git would be initialized. If the target already exists, the preview reports that a real run would refuse it; no directories, files, or Git metadata are created.

Examples:

emulsify system create
emulsify system create "My System" --directory ./systems --platform none --git
emulsify system create shared-system --directory ./systems --platform "drupal || wordpress" --no-git
emulsify system create my-system --yes
emulsify system create my-system --directory ./systems --platform none --git --dry-run
emulsify system create my-system --directory ./systems --platform drupal --git \
  --homepage https://design.example.com/my-system \
  --repository https://github.com/example/my-system.git

system install

emulsify system install [name]

Run without a name or repository in an interactive terminal to start the guided installer. The built-in path covers four decisions: source, component set, installation scope, and final review.

The source picker presents human-readable system names and descriptions:

Which system?
❯ Compound              Accessible, tested components. Drupal, WordPress, plain.
  Emulsify UI Kit       Broader design-system starter kit.
  Bring your own        Install from a git repository you control.
  ────────────
  Cancel

After the selected system is downloaded and validated, the component-set picker shows each variant in plain language with its raw platform expression in parentheses. Compatible choices are ordered first, and the best match for the current project is marked Recommended and selected by default. Each choice also shows its total component count and how many are essential.

The scope picker offers:

• Essentials only — install only components marked required: true.
• Everything — install every component in the selected component set.

Both choices include their component counts. The review then shows the selected system and checkout, repository source, component set, scope, component and asset counts, and their concrete destination paths. The CLI asks for confirmation before changing project.emulsify.json, copying components or assets, or running the project install hook. The selected repository may already have been downloaded into the CLI cache so its configuration can be reviewed.

Install a component system                                Step 4 of 4

  System         Compound  ·  v2.3.1
  Source         github.com/emulsify-ds/compound
  Component set  Drupal
  Scope          Essentials only
  Will install   5 components  →  components/
                 2 asset folders  →  assets/, src/vendor/

? Install now? (Y/n)

Pass -y, --yes to display this final review and accept it without opening the confirmation prompt. It does not choose a missing source, component set, or installation scope.

Selecting Bring your own adds prompts for a repository URL or local path and a checkout (branch, tag, or commit); the displayed step total expands to include them. Selecting Cancel, or declining the final review, reports System install cancelled. and leaves the project configuration and destinations unchanged.

Supplying a built-in name or both custom-repository flags bypasses the guided installer and preserves the direct command behavior. Variant compatibility is resolved automatically unless --variant is supplied, and only essential components are installed unless --all is supplied.

Options:

Option	Description
-r, --repository <repository>	Install from a remote Git repository or a local repository path. Remote URLs must end in .git.
-c, --checkout <commit/branch/tag>	Checkout to use. This is required when --repository is used.
--variant <platform-expression>	Install the variant whose platform expression exactly matches this value. Quote compound expressions at the shell.
-a, --all	Install every component in the selected variant. Without this flag, only components marked required: true are installed during system install.
-y, --yes	Accept the final guided-install review without prompting. It does not supply any earlier wizard choice.

Prompts are never opened when standard input is not a TTY. A bare command fails immediately with this guidance:

No component system source was provided. Pass a built-in system name as the positional argument, or pass both --repository <repository> and --checkout <branch, tag, or commit>.

For scripts and CI, pass a built-in name or pass both --repository and --checkout. Supplying only one custom-repository option also fails immediately and names the missing flag. --yes does not make a bare command non-interactive: the source, component set, and scope still require choices.

Examples:

emulsify system install
# Interactive wizard with no final confirmation prompt:
emulsify system install --yes
emulsify system install compound
emulsify system install emulsify-ui-kit
emulsify system install compound --all
emulsify system install --repository https://github.com/example/example-system.git --checkout v1.0.0
emulsify system install --repository https://github.com/example/example-system.git --checkout v1.0.0 --variant wordpress
emulsify system install --repository /absolute/path/to/local-system --checkout v1.0.0

System variant compatibility is selected from each variant's platform expression. Examples:

• "platform": "wordpress" matches WordPress projects.
• "platform": "drupal || wordpress" matches Drupal and WordPress projects.
• "platform": "none" is generic and can be installed by any concrete project platform.

Project configuration uses only concrete project.platform values: drupal, wordpress, or none. Only system variants use || expressions. A project with project.platform: "none" can install any component library system; when multiple variants are equally compatible, the CLI prompts in an interactive terminal or errors in non-interactive mode.

Pass --variant to choose an exact variant platform expression instead of automatic compatibility selection. Quote a shared expression at the shell, for example --variant "drupal || wordpress".

system detach

emulsify system detach

Detaches the configured component system from the current Emulsify project. The command rewrites only project.emulsify.json, removing its top-level system and variant entries while preserving every other configuration value. Components, project assets, generated files, and the cached system repository are not edited or removed.

Options:

Option	Description
-y, --yes	Confirm detachment without opening an interactive prompt.

Interactive terminals ask for confirmation before changing the configuration. Declining reports cancellation and leaves the project unchanged. When standard input is not a TTY, omit --yes and the command fails immediately with a message naming the flag instead of prompting or proceeding silently:

emulsify system detach --yes

The command also fails when no Emulsify project can be found or when the project has no configured system; the latter is reported as a no-op rather than success. After a successful detach, emulsify system install can configure a system again. Use emulsify cache clear separately if all cached repositories should be removed.

To turn refined project components into a system, detach first, run emulsify system create to create a fresh repository, then move or copy the preserved components into that scaffold and update its system.emulsify.json. system create does not import project components automatically.

component list

emulsify component list
emulsify component ls
emulsify component list --refresh

Lists components available from the installed system and selected variant. Output uses the component structure followed by the component name, for example atoms -> buttons.

Pass --refresh to check the system's remote ref before listing. Without it, the command validates and reuses the local cache without touching the network.

component install

emulsify component install [name]
emulsify component i [name]

In an interactive terminal, omit [name] and --all to choose from the components actually available in the installed system variant. The picker also includes an explicit choice to install all available components.

Options:

Option	Description
-f, --force	Replace an existing component destination without prompting.
-a, --all	Install all available components instead of one named component.
--dry-run	Preview dependencies, destinations, overwrite behavior, and copy operations without changing files.
--refresh	Check the system's remote ref before reusing its local cache entry.

Examples:

emulsify component install card
emulsify component install card --refresh
emulsify component install card --dry-run
emulsify component i accordion --force
emulsify component install --all

When standard input is not a TTY, provide either [name] or --all; the CLI exits with an actionable error instead of opening the picker. If a named component destination already exists, the command also exits unless --force is passed to replace it without an overwrite prompt.

component eject-templates

emulsify component eject-templates [type]

Writes the CLI's built-in component templates into .cli/templates/<type>/ in the current Emulsify project. The files are the real defaults used by component create, expressed with the same supported template tokens, so they can be edited in place rather than recreated from scratch. The command reports every destination with its real project path.

Supported types are twig, twig-sdc, react, and web-component. In an interactive terminal, omitting [type] opens a multi-select prompt where one, several, or all four types can be selected. When standard input is not a TTY, provide one type or pass --all; otherwise the command exits immediately with an actionable message naming both choices. [type] and --all are mutually exclusive.

Before writing, the command checks every target in the selected set. If any target already exists, it reports all conflicts and writes nothing. Pass --force only when every conflicting file in the selection may be replaced.

Options:

Option	Description
-a, --all	Eject templates for every supported component type.
-f, --force	Replace existing template files after the selection-wide conflict check.
--dry-run	Report template destinations and conflicts without creating or changing files.

Examples:

emulsify component eject-templates
emulsify component eject-templates twig
emulsify component eject-templates --all
emulsify component eject-templates react --dry-run
emulsify component eject-templates web-component --force

The command must run inside an Emulsify project. It writes only to canonical type directories and does not add provenance headers to the templates, so an unedited ejected template renders byte-for-byte like the corresponding built-in. Deleting an override restores the usual fallback behavior: a legacy Twig alias where one exists, then the built-in template.

component create

emulsify component create [name]
emulsify component c [name]

Run without [name] in an interactive terminal to start the complete creation wizard. The CLI prompts for the component name first, explains invalid names and prompts again, then asks for any missing type and directory values. Supplying any of those values on the command line skips its corresponding prompt.

The interactive type picker always offers Twig. It offers Twig SDC only for a Drupal project, and offers React and Web Component when the project's package.json declares @emulsify/core. A hint explains omitted choices. If Twig is the only suitable type, the CLI selects it without displaying a one-choice prompt. These filters do not restrict explicit flags: --type is always honored, with a warning rather than a failure when React or Web Component is requested but Core is not detected.

Options:

Option	Description
-d, --directory <directory>	Variant structure name where the component should be created.
-t, --type <twig|twig-sdc|react|web-component>	Component renderer and packaging type.
--tag-name <tag-name>	Explicit custom element tag for --type web-component.
-f, --format <default|sdc>	Deprecated alias: default maps to twig; sdc maps to twig-sdc. Prints a deprecation warning.
--force	Replace an existing generated component without prompting.
-y, --yes	Compatibility alias for --force.
--dry-run	Preview destination and generated files without writing, removing, or creating files.
--refresh	Check the system's remote ref before reusing its local cache entry.

Examples:

emulsify component create promo-card --directory molecules --type twig
emulsify component create teaser --directory molecules --type twig-sdc
emulsify component create promo-card --directory molecules --type react
emulsify component create promo-card --directory molecules --type web-component
emulsify component create card --directory molecules --type web-component --tag-name acme-card
emulsify component create promo-card --directory molecules --type twig --dry-run

React scaffolds use Storybook's standard React support. Web Component stories use Emulsify Core's renderWebComponent helper. For Web Components, a hyphenated component filename is also the custom element tag. A single-word filename is prefixed with the project's machine name, so card in acme-theme becomes <acme-theme-card>. The wizard confirms this tag and allows an override. Pass --tag-name <tag-name> to set it explicitly, including when a project machine name cannot produce a valid derived tag in a non-interactive environment. Explicit and derived values follow the same browser-compatible validation rules. --tag-name is rejected for types other than web-component.

When standard input is not a TTY, provide the positional [name] plus both --directory and --type; otherwise the command exits with an actionable error instead of waiting for prompts that cannot be answered. If the generated component already exists, also pass --force to replace it without an overwrite prompt. Existing scripts may continue using the -y, --yes compatibility alias. The deprecated --format default and --format sdc forms also remain available and print a deprecation warning.