Search…
Emulsify CLI Usage
This project is a command line interface for working with Emulsify. It has a few primary responsibilities:
  • Make initializing Emulsify projects very simple.
  • Allow developers to select an Emulsify system (such as Compound).
  • Give developers the ability to pull in components from the system they're using, when/if they need them.

Projects, Systems and Variants

You will see the terms "Projects", "Systems" and "Variants" used throughout this documentation, so it's important for you to understand what they mean.
  • Project: an implementation of an Emulsify starter, such as emulsify-drupal.
  • System: a design system that defines components, and assets. Emulsify projects opt into using systems using cli commands. Once a system has been selected for a project, the system will mandate how components are organized and how required components/assets are installed. It also gives developers the ability to find and install non-required components.
  • Variant: a system might have a Drupal variant, a WordPress variant, and a React variant. The system is the same (imagine Material-UI is a system), but each variant may define different types of components, or have different organization patterns that are compatible with different platforms. Systems may have as many variants as they want.

Using the CLI

Init

The cli exposes an init command that allows developers to easily create an Emulsify project.

When the init command is run, it will attempt to detect the platform you're using, and use that to choose a starter (such as emulsify-drupal). However, you can use the command options to specify any platform, starter, and starter version/branch/tag. If the cli cannot determine the platform you're using, it will instruct you to provide those details yourself.
1
emulsify init --help
2
Usage: emulsify init [options] <name> [path]
3
4
Initialize an Emulsify project
5
6
Arguments:
7
name Name of the Emulsify project you are initializing. This should be a proper name, such as "Carmen Sandiego".
8
path Path to the folder in which you would like to to create your Emulsify project. For example, "./themes" will
9
result in the Emulsify project being placed in ./themes/{name}
10
11
Options:
12
-m --machineName <machineName> Machine-friendly name of the project you are initializing. If not provided, this will be automatically
13
generated.
14
-s --starter <repository> Git repository of the Emulsify starter you would like to use, such as the Emulsify Drupal theme:
15
https://github.com/emulsify-ds/emulsify-drupal.git
16
-c --checkout <commit/branch/tag> Commit, branch or tag of the base repository that should be checked out
17
-p --platform <drupal/wordpress/etc> Name of the platform Emulsify is being within. In some cases, Emulsify is able to automatically detect this. If
18
it is not, Emulsify will prompt you to specify.
19
-h, --help display help for command
Copied!
Example usage:
1
cd ~/projects/my-drupal-codebase
2
emulsify init "Theme Name"
3
4
# If you are not relying on the cli to detect the platform, and use a starter:
5
emulsify init "Theme Name" ./web/themes/custom/theme-name --starter https://github.com/emulsify-ds/emulsify-drupal.git --checkout 2.x --platform drupal
Copied!

System

Once you have initialized a project, you can use system commands available within the cli to list the out-of-the-box systems, and install a system into your current project.
1
emulsify system --help
2
Usage: emulsify system [options] [command]
3
4
Parent command that contains sub-commands pertaining to systems
5
6
Options:
7
-h, --help display help for command
8
9
Commands:
10
list|ls Lists all of the available systems that Emulsify supports out-of-the-box
11
install [options] [name] Install a system within an Emulsify project. You must specify either the name of an out-of-the-box system (such as
12
compound), or a link to a git repository containing the system you want to install
13
help [command] display help for command
Copied!
The emulsify system list|ls command lists all of the out-of-the-box systems Emulsify supports at the moment.
Example usage:
1
emulsify system list
2
compound - https://github.com/emulsify-ds/compound.git
Copied!
The emulsify system install command, when run within an Emulsify project, will install a system within the given project. You can pass the name of an out-of-the-box system, like compound, or you can pass a repository, and commit/branch/tag of any system you'd like to use.
1
emulsify system install --help
2
Usage: emulsify system install [options] [name]
3
4
Install a system within an Emulsify project. You must specify either the name of an out-of-the-box system (such as compound), or a link to a git repository containing the system you want to install
5
6
Arguments:
7
name Name of the out-of-the-box system you would like to install
8
9
Options:
10
-r --repository <repository> Git repository containing the system you would like to install
11
-c --checkout <commit/branch/tag> Commit, branch or tag of the base repository that should be checked out. MUST be provided if you are passing along
12
a repository (-r or --repository). Tags or commit hashes are strongly preferable, because you want to ensure that
13
you are using the same version of the system every time you install components, etc
14
-a --all Use this to install all available components within the specified system. Without this flag, only the required system components will be installed.
15
-h, --help display help for command
Copied!
Example usage:
1
cd ~/projects/my-drupal-codebase/web/themes/custom/my-theme
2
emulsify system install compound
3
> Successfully installed the compound system using the drupal variant.
4
5
6
# If you are pasing in your own repo/checkout
7
emulsify system install --repository https://github.com/your-org/your-custom-system.git --checkout 3.x
Copied!

Components

In your project, once you have selected a system, you may use the components commands within the cli to find, and install components that are available within your system.
1
emulsify component --help
2
Usage: emulsify component [options] [command]
3
4
Parent command that contains sub-commands pertaining to components
5
6
Options:
7
-h, --help display help for command
8
9
Commands:
10
list|ls Lists all of the components that are available for installation within your project based on the system and variant you selected
11
install|i [name] [options] Install a component from within the current project's system and variant
12
help [command] display help for command
Copied!
Listing components
The emulsify component list|ls will return a list of components available within the system you selected for your project.
Example usage:
1
cd ~/projects/my-drupal-codebase/web/themes/custom/my-theme
2
emulsify component list
3
4
base -> 01-colors
5
base -> 02-motion
6
base -> 03-site
7
atoms -> buttons
8
atoms -> forms
9
atoms -> images
10
atoms -> links
11
atoms -> lists
12
atoms -> tables
13
atoms -> text
14
atoms -> video
15
molecules -> card
16
molecules -> cta
17
molecules -> menus
18
molecules -> pager
19
molecules -> status
20
molecules -> tabs
21
organisms -> grid
22
organisms -> site
23
templates -> placeholder
24
pages -> content-types
25
pages -> landing-pages
Copied!
Installing components
Once you've found a component you want to install, you can use the emulsify component install command to fetch it into your project.
Example usage:
1
cd ~/projects/my-drupal-codebase/web/themes/custom/my-theme
2
emulsify component install card
3
> Success! The card component has been added to your project.
Copied!
Force installing components
If you attempt to install a component that already exists within your project, you the installation process will throw an error. However, if you wish to overwrite the existing component, pass the --force flag.
Example usage:
1
emulsify component install card
2
> Error: The component "card" already exists, and force was not passed (--force).
3
4
emulsify component install card --force
5
> Success! The card component has been added to your project.
Copied!
Installing all available components
If you would like to simply install all components available within the system you've selected, use the --all flag.
Example usage:
1
emulsify component install --all
2
> Success! The 01-colors component has been added to your project.
3
> ...
Copied!
That's pretty much it. Have fun, and please feel free to open issues if you discover a bug, or have an improvement to suggest!