Docs/align cli usage

README.md

@@ -1,25 +1,129 @@
 [![Emulsify Design System](https://user-images.githubusercontent.com/409903/170579210-327abcdd-2c98-4922-87bb-36446a4cc013.svg)](https://www.emulsify.info/)
 ![npm](https://img.shields.io/npm/dm/@emulsify/cli?style=flat-square)
 
-# emulsify-cli
+# Emulsify CLI
 
-Command line interface for Emulsify.
+Command line interface for Emulsify projects.
 
 ## Installation
 
-This project is deployed to [npm](https://www.npmjs.com/package/@emulsify/cli). In order to use this CLI, install it as a global dependency:
+Emulsify CLI requires Node 24 or newer.
+
+Install Emulsify CLI globally from [npm](https://www.npmjs.com/package/@emulsify/cli):
 
 ```bash
 npm install -g @emulsify/cli
 ```
 
 ## Usage
 
-For more information on how to use emulsify-cli, please see the [usage documentation](https://www.emulsify.info/docs/supporting-projects/emulsify-cli/emulsify-cli-usage).
+Run `emulsify --help` for the current command list.
+
+### Commands
+
+| Command                             | Alias                         | Description                                                       |
+| ----------------------------------- | ----------------------------- | ----------------------------------------------------------------- |
+| `emulsify init [name] [path]`       |                               | Initializes an Emulsify project from a starter.                   |
+| `emulsify system list`              | `emulsify system ls`          | Lists built-in systems available for installation.                |
+| `emulsify system install [name]`    |                               | Installs a system in the current Emulsify project.                |
+| `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.        |
+
+### Initialize A Project
+
+`emulsify init [name] [path]` clones a starter, writes the project configuration, installs dependencies, runs the starter init hook when present, and removes the starter Git history.
+
+Options:
+
+- `--machineName <machineName>`: Sets the machine-friendly project name. When omitted, Emulsify CLI derives it from the project name.
+- `--starter <repository>`: Uses a specific starter repository.
+- `--checkout <commit/branch/tag>`: Checks out a specific starter commit, branch, or tag.
+- `--platform <platform>`: Sets the project platform when auto-detection is unavailable or should be overridden. For Drupal projects, pass `drupal`.
+- `--yes`: Accepts default init values for missing options without prompting.
+
+Current starter repositories:
+
+- `https://github.com/emulsify-ds/emulsify-starter`
+- `https://github.com/emulsify-ds/emulsify-drupal-starter`
+
+Examples:
+
+```bash
+emulsify init "My Project" ./projects
+emulsify init "My Theme" ./web/themes/custom --platform drupal --yes
+emulsify init "My Project" ./projects --starter https://github.com/emulsify-ds/emulsify-starter --checkout main
+```
+
+### Systems
+
+`emulsify system list` lists the built-in systems that Emulsify CLI can install. `emulsify system ls` is the same command.
+
+```bash
+emulsify system list
+emulsify system ls
+```
+
+`emulsify system install [name]` installs a system in the current Emulsify project. Use `compound` to install the built-in Compound system. The command installs required components by default.
+
+Options:
+
+- `--repository <repository>`: Installs a system from a specific Git repository.
+- `--checkout <commit/branch/tag>`: Checks out a specific system commit, branch, or tag. This is required when `--repository` is used.
+- `--all`: Installs all available components from the system instead of only required components.
 
-### Customizing component templates
+Examples:
+
+```bash
+emulsify system install compound
+emulsify system install compound --all
+emulsify system install --repository https://github.com/example/example-system.git --checkout v1.0.0
+```
 
-Projects can override the built-in `component create` templates by adding files under `.cli/templates/` at the Emulsify project root. Overrides replace only the known artifacts that the CLI already generates; they do not add extra files or change which files are created.
+### Components
+
+`emulsify component list` lists components available from the installed system and variant. `emulsify component ls` is the same command.
+
+```bash
+emulsify component list
+emulsify component ls
+```
+
+`emulsify component install [name]` installs one component from the installed system and variant. `emulsify component i [name]` is the same command.
+
+Options:
+
+- `--force`: Replaces an installed component.
+- `--all`: Installs all available components instead of one named component.
+
+Examples:
+
+```bash
+emulsify component install button
+emulsify component i card --force
+emulsify component install --all
+```
+
+`emulsify component create [name]` creates a local component in the current Emulsify project. `emulsify component c [name]` is the same command.
+
+Options:
+
+- `--directory <directory>`: Sets the variant structure directory where the component is created.
+- `--format <format>`: Sets the component format. Supported values are `default` and `sdc`.
+- `--yes`: Replaces an existing component without an overwrite confirmation prompt.
+
+In non-interactive environments, pass both `--directory` and `--format`.
+
+Examples:
+
+```bash
+emulsify component create card --directory base --format default
+emulsify component create teaser --directory molecules --format sdc --yes
+```
+
+### Component Template Overrides
+
+Projects can override the built-in `component create` templates by adding component template override files under `.cli/templates/` at the Emulsify project root. Overrides replace only the known artifacts that Emulsify CLI already generates; they do not add extra files or change which files are created.
 
 Default component overrides:
 
@@ -36,13 +140,23 @@ SDC component overrides:
 - `.cli/templates/sdc/component.js`
 - `.cli/templates/sdc/component.stories.js`
 
-Override files can use double-brace tokens. Supported tokens are `{{ filename }}`, `{{ className }}`, `{{ camelName }}`, `{{ snakeName }}`, `{{ humanName }}`, `{{ directory }}`, and `{{ format }}`. Unknown tokens are left unchanged and logged as warnings.
+Override files can use double-brace tokens:
+
+- `{{ filename }}`
+- `{{ className }}`
+- `{{ camelName }}`
+- `{{ snakeName }}`
+- `{{ humanName }}`
+- `{{ directory }}`
+- `{{ format }}`
+
+For each generated artifact, Emulsify CLI first checks for the matching override file. If the override is missing, the built-in template is used. If the override exists but is empty, the built-in template is used and a warning is logged. Unknown tokens are left unchanged and logged as warnings. Partial override sets are supported, so a project can override only `component.twig` and keep the built-in SCSS, data, and story templates. Extra arbitrary files are not generated by component template overrides.
 
-For each generated artifact, the CLI first checks for the matching override file. If the override is missing or empty, the built-in template is used. Partial override sets are supported, so a project can override only `component.twig` and keep the built-in SCSS, data, and story templates. Arbitrary extra files and template ejection helpers are future work.
+For more documentation, see the [Emulsify CLI usage documentation](https://www.emulsify.info/docs/supporting-projects/emulsify-cli/emulsify-cli-usage).
 
 ## Development
 
-Emulsify-cli is developed using TypeScript. You can find all of the source files in the `src` directory, which is organized in the following manner:
+Emulsify CLI is developed using TypeScript. You can find all of the source files in the `src` directory, which is organized in the following manner:
 
 - `src/index.ts` - uses Commander to compose the CLI.
 - `src/handlers` - contains all functions that handle CLI commands, such as `emulsify init`.
@@ -54,7 +168,7 @@ Emulsify-cli is developed using TypeScript. You can find all of the source files
 
 ### Setup
 
-- Install the version of node as specified in this project's `.nvmrc` file. If you are using nvm, simply run `nvm use`.
+- Install the version of Node specified in this project's `.nvmrc` file. If you are using nvm, run `nvm use`.
 - Clone this repository into a directory of your choosing.
 - In the directory, run `npm install`.
 - Build the project: `npm run build`, or watch: `npm run watch`.
@@ -63,7 +177,7 @@ Emulsify-cli is developed using TypeScript. You can find all of the source files
 ### Scripts
 
 - `npm run build`: builds the project based on the configuration in `tsconfig.dist.json`.
-- `npm run build-schema-types`: Compiles the json-schema definitions within this project into ts types.
+- `npm run build-schema-types`: Compiles the JSON Schema definitions within this project into TypeScript types.
 - `npm run watch`: watches the codebase, and re-compiles every time a change is made.
 - `npm run format`: uses prettier to format all ts files within the codebase.
 - `npm run lint`: runs the Jest test suite via the `test` script.
@@ -74,7 +188,7 @@ Emulsify-cli is developed using TypeScript. You can find all of the source files
 
 ## Deployment
 
-This project is automatically built and deployed to NPM via the release GitHub Actions workflow. Pushes to `main` run `npm run build` and then `npm run semantic-release`.
+This project is automatically built and deployed to npm via the release GitHub Actions workflow. Pushes to `main` run `npm run build` and then `npm run semantic-release`.
 
 ### Contributors
 

docs/emulsify-info-cli-updates.md

@@ -0,0 +1,146 @@
+# Emulsify CLI Website Updates
+
+Copy-ready updates for the emulsify.info Emulsify CLI usage page.
+
+## Installation
+
+Emulsify CLI requires Node 24 or newer.
+
+Install Emulsify CLI globally with npm:
+
+```bash
+npm install -g @emulsify/cli
+```
+
+## Commands
+
+| Command                             | Alias                         | Description                                                       |
+| ----------------------------------- | ----------------------------- | ----------------------------------------------------------------- |
+| `emulsify init [name] [path]`       |                               | Initializes an Emulsify project from a starter.                   |
+| `emulsify system list`              | `emulsify system ls`          | Lists built-in systems available for installation.                |
+| `emulsify system install [name]`    |                               | Installs a system in the current Emulsify project.                |
+| `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.        |
+
+## Initialize A Project
+
+`emulsify init [name] [path]` clones a starter, writes the project configuration, installs dependencies, runs the starter init hook when present, and removes the starter Git history.
+
+Options:
+
+- `--machineName <machineName>`: Sets the machine-friendly project name. When omitted, Emulsify CLI derives it from the project name.
+- `--starter <repository>`: Uses a specific starter repository.
+- `--checkout <commit/branch/tag>`: Checks out a specific starter commit, branch, or tag.
+- `--platform <platform>`: Sets the project platform when auto-detection is unavailable or should be overridden. For Drupal projects, pass `drupal`.
+- `--yes`: Accepts default init values for missing options without prompting.
+
+Current starter repositories:
+
+- `https://github.com/emulsify-ds/emulsify-starter`
+- `https://github.com/emulsify-ds/emulsify-drupal-starter`
+
+Examples:
+
+```bash
+emulsify init "My Project" ./projects
+emulsify init "My Theme" ./web/themes/custom --platform drupal --yes
+emulsify init "My Project" ./projects --starter https://github.com/emulsify-ds/emulsify-starter --checkout main
+```
+
+## Systems
+
+`emulsify system list` lists the built-in systems that Emulsify CLI can install. `emulsify system ls` is the same command.
+
+```bash
+emulsify system list
+emulsify system ls
+```
+
+`emulsify system install [name]` installs a system in the current Emulsify project. Use `compound` to install the built-in Compound system. The command installs required components by default.
+
+Options:
+
+- `--repository <repository>`: Installs a system from a specific Git repository.
+- `--checkout <commit/branch/tag>`: Checks out a specific system commit, branch, or tag. This is required when `--repository` is used.
+- `--all`: Installs all available components from the system instead of only required components.
+
+Examples:
+
+```bash
+emulsify system install compound
+emulsify system install compound --all
+emulsify system install --repository https://github.com/example/example-system.git --checkout v1.0.0
+```
+
+## Components
+
+`emulsify component list` lists components available from the installed system and variant. `emulsify component ls` is the same command.
+
+```bash
+emulsify component list
+emulsify component ls
+```
+
+`emulsify component install [name]` installs one component from the installed system and variant. `emulsify component i [name]` is the same command.
+
+Options:
+
+- `--force`: Replaces an installed component.
+- `--all`: Installs all available components instead of one named component.
+
+Examples:
+
+```bash
+emulsify component install button
+emulsify component i card --force
+emulsify component install --all
+```
+
+`emulsify component create [name]` creates a local component in the current Emulsify project. `emulsify component c [name]` is the same command.
+
+Options:
+
+- `--directory <directory>`: Sets the variant structure directory where the component is created.
+- `--format <format>`: Sets the component format. Supported values are `default` and `sdc`.
+- `--yes`: Replaces an existing component without an overwrite confirmation prompt.
+
+In non-interactive environments, pass both `--directory` and `--format`.
+
+Examples:
+
+```bash
+emulsify component create card --directory base --format default
+emulsify component create teaser --directory molecules --format sdc --yes
+```
+
+## Component Template Overrides
+
+Projects can override the built-in `component create` templates by adding component template override files under `.cli/templates/` at the Emulsify project root. Overrides replace only the known artifacts that Emulsify CLI already generates; they do not add extra files or change which files are created.
+
+Default component overrides:
+
+- `.cli/templates/default/component.twig`
+- `.cli/templates/default/component.scss`
+- `.cli/templates/default/component.yml`
+- `.cli/templates/default/component.stories.js`
+
+SDC component overrides:
+
+- `.cli/templates/sdc/component.twig`
+- `.cli/templates/sdc/component.scss`
+- `.cli/templates/sdc/component.component.yml`
+- `.cli/templates/sdc/component.js`
+- `.cli/templates/sdc/component.stories.js`
+
+Override files can use double-brace tokens:
+
+- `{{ filename }}`
+- `{{ className }}`
+- `{{ camelName }}`
+- `{{ snakeName }}`
+- `{{ humanName }}`
+- `{{ directory }}`
+- `{{ format }}`
+
+For each generated artifact, Emulsify CLI first checks for the matching override file. If the override is missing, the built-in template is used. If the override exists but is empty, the built-in template is used and a warning is logged. Unknown tokens are left unchanged and logged as warnings. Partial override sets are supported, so a project can override only `component.twig` and keep the built-in SCSS, data, and story templates. Extra arbitrary files are not generated by component template overrides.