From 494d350190c931b82a9649cb0d3643cdcf5b3a48 Mon Sep 17 00:00:00 2001 From: Donald Labaj Date: Mon, 30 Mar 2026 21:58:54 -0400 Subject: [PATCH 1/8] feat: Added documenation for patternfly cli. --- .../content/get-started/develop.md | 2 +- .../content/get-started/patternfly-cli.md | 100 ++++++++++++++++++ .../site/src/content/get-started/develop.mdx | 2 +- .../content/get-started/patternfly-cli.mdx | 100 ++++++++++++++++++ 4 files changed, 202 insertions(+), 2 deletions(-) create mode 100644 packages/documentation-site/patternfly-docs/content/get-started/patternfly-cli.md create mode 100644 packages/site/src/content/get-started/patternfly-cli.mdx diff --git a/packages/documentation-site/patternfly-docs/content/get-started/develop.md b/packages/documentation-site/patternfly-docs/content/get-started/develop.md index 14f69b5e67..5479765ad5 100644 --- a/packages/documentation-site/patternfly-docs/content/get-started/develop.md +++ b/packages/documentation-site/patternfly-docs/content/get-started/develop.md @@ -46,7 +46,7 @@ We support the following configurations: #### New projects -If you'd like to start using PatternFly via a sample project, you can use the [PatternFly React seed](https://github.com/patternfly/patternfly-react-seed). We created this open-source build scaffolding utility to help developers jump start new PatternFly projects. +If you'd like to start using PatternFly via a sample project, you can use the [PatternFly React seed](https://github.com/patternfly/patternfly-react-seed). We created this open-source build scaffolding utility to help developers jump start new PatternFly projects. You can also scaffold projects from the command line with the [PatternFly CLI](/get-started/patternfly-cli). To get started: diff --git a/packages/documentation-site/patternfly-docs/content/get-started/patternfly-cli.md b/packages/documentation-site/patternfly-docs/content/get-started/patternfly-cli.md new file mode 100644 index 0000000000..ca76b3c414 --- /dev/null +++ b/packages/documentation-site/patternfly-docs/content/get-started/patternfly-cli.md @@ -0,0 +1,100 @@ +--- +id: PatternFly CLI +title: PatternFly CLI +section: get-started +--- + +import './get-started.css'; +import { Alert } from '@patternfly/react-core'; + +The [PatternFly CLI](https://github.com/patternfly/patternfly-cli) is a command-line tool for scaffolding projects, applying code changes, and running common project tasks. It is published as [`@patternfly/patternfly-cli` on npm](https://www.npmjs.com/package/@patternfly/patternfly-cli). + +## What you can do + +- **Scaffold projects** from built-in or custom templates. +- **Automate code updates** for repetitive changes. +- **Run workflows** such as init, sync with GitHub, updates, and deploys to GitHub Pages. + +## Prerequisites + +Before you install the CLI, set up: + +1. **[Node.js and npm](https://nodejs.org/)** (supported versions **20–24**). +1. **[Corepack](https://nodejs.org/api/corepack.html)** — included with Node.js; enable it with `corepack enable` after installing Node. +1. **[GitHub CLI](https://cli.github.com/)** (`gh`) — required for commands that talk to GitHub. + +## Install + +Install the CLI globally: + +```sh +npm install -g @patternfly/patternfly-cli +``` + +## Check your setup + +Run the doctor command to verify prerequisites: + +```sh +patternfly-cli doctor +``` + +To try to fix missing pieces automatically (Corepack and GitHub CLI only): + +```sh +patternfly-cli doctor --fix +``` + + +The `doctor --fix` option does not install or upgrade Node.js. If Node.js is missing or below version 20, install the current **LTS** release from [nodejs.org](https://nodejs.org/). + + +## Commands + +After installation, run: + +```sh +patternfly-cli [command] +``` + +| Command | Description | +| --- | --- | +| `doctor` | Check requirements; use `--fix` to enable Corepack and install `gh` where supported. | +| `create` | Create a new project from a template. | +| `list` | List available templates (built-in and custom). | +| `update` | Update the project to a newer PatternFly-oriented version where applicable. | +| `init` | Initialize a git repository and optionally create a GitHub repo. | +| `save` | Commit and push changes on the current branch. | +| `load` | Pull the latest changes from GitHub. | +| `deploy` | Build and deploy the app to GitHub Pages. | + +For the most up-to-date flags and behavior, see the [PatternFly CLI README](https://github.com/patternfly/patternfly-cli/blob/main/README.md) on GitHub. + +## Custom templates + +You can merge your own templates with the built-ins by passing a JSON file with `--template-file` (or `-t`): + +```sh +patternfly-cli create my-app --template-file ./my-templates.json +patternfly-cli list --template-file ./my-templates.json +``` + +Each entry is an object with at least `name`, `description`, and `repo` (clone URL). Optional fields include `options` (extra `git clone` arguments) and `packageManager` (`npm`, `yarn`, or `pnpm`; default is `npm`). If a custom template uses the same `name` as a built-in one, the custom definition wins. + +Example: + +```json +[ + { + "name": "my-template", + "description": "My custom project template", + "repo": "https://github.com/org/repo.git", + "options": ["--single-branch", "--branch", "main"], + "packageManager": "npm" + } +] +``` + +## Source and releases + +The CLI is developed in the open at [github.com/patternfly/patternfly-cli](https://github.com/patternfly/patternfly-cli). Report issues or contribute there; release notes and tags are published on the repository’s [Releases](https://github.com/patternfly/patternfly-cli/releases) page. diff --git a/packages/site/src/content/get-started/develop.mdx b/packages/site/src/content/get-started/develop.mdx index 3bced63390..64be7ec33c 100644 --- a/packages/site/src/content/get-started/develop.mdx +++ b/packages/site/src/content/get-started/develop.mdx @@ -46,7 +46,7 @@ We support the following configurations: #### New projects -If you'd like to start using PatternFly via a sample project, you can use the [PatternFly React seed](https://github.com/patternfly/patternfly-react-seed). We created this open-source build scaffolding utility to help developers jump start new PatternFly projects. +If you'd like to start using PatternFly via a sample project, you can use the [PatternFly React seed](https://github.com/patternfly/patternfly-react-seed). We created this open-source build scaffolding utility to help developers jump start new PatternFly projects. You can also scaffold projects from the command line with the [PatternFly CLI](/get-started/patternfly-cli). To get started: diff --git a/packages/site/src/content/get-started/patternfly-cli.mdx b/packages/site/src/content/get-started/patternfly-cli.mdx new file mode 100644 index 0000000000..ca76b3c414 --- /dev/null +++ b/packages/site/src/content/get-started/patternfly-cli.mdx @@ -0,0 +1,100 @@ +--- +id: PatternFly CLI +title: PatternFly CLI +section: get-started +--- + +import './get-started.css'; +import { Alert } from '@patternfly/react-core'; + +The [PatternFly CLI](https://github.com/patternfly/patternfly-cli) is a command-line tool for scaffolding projects, applying code changes, and running common project tasks. It is published as [`@patternfly/patternfly-cli` on npm](https://www.npmjs.com/package/@patternfly/patternfly-cli). + +## What you can do + +- **Scaffold projects** from built-in or custom templates. +- **Automate code updates** for repetitive changes. +- **Run workflows** such as init, sync with GitHub, updates, and deploys to GitHub Pages. + +## Prerequisites + +Before you install the CLI, set up: + +1. **[Node.js and npm](https://nodejs.org/)** (supported versions **20–24**). +1. **[Corepack](https://nodejs.org/api/corepack.html)** — included with Node.js; enable it with `corepack enable` after installing Node. +1. **[GitHub CLI](https://cli.github.com/)** (`gh`) — required for commands that talk to GitHub. + +## Install + +Install the CLI globally: + +```sh +npm install -g @patternfly/patternfly-cli +``` + +## Check your setup + +Run the doctor command to verify prerequisites: + +```sh +patternfly-cli doctor +``` + +To try to fix missing pieces automatically (Corepack and GitHub CLI only): + +```sh +patternfly-cli doctor --fix +``` + + +The `doctor --fix` option does not install or upgrade Node.js. If Node.js is missing or below version 20, install the current **LTS** release from [nodejs.org](https://nodejs.org/). + + +## Commands + +After installation, run: + +```sh +patternfly-cli [command] +``` + +| Command | Description | +| --- | --- | +| `doctor` | Check requirements; use `--fix` to enable Corepack and install `gh` where supported. | +| `create` | Create a new project from a template. | +| `list` | List available templates (built-in and custom). | +| `update` | Update the project to a newer PatternFly-oriented version where applicable. | +| `init` | Initialize a git repository and optionally create a GitHub repo. | +| `save` | Commit and push changes on the current branch. | +| `load` | Pull the latest changes from GitHub. | +| `deploy` | Build and deploy the app to GitHub Pages. | + +For the most up-to-date flags and behavior, see the [PatternFly CLI README](https://github.com/patternfly/patternfly-cli/blob/main/README.md) on GitHub. + +## Custom templates + +You can merge your own templates with the built-ins by passing a JSON file with `--template-file` (or `-t`): + +```sh +patternfly-cli create my-app --template-file ./my-templates.json +patternfly-cli list --template-file ./my-templates.json +``` + +Each entry is an object with at least `name`, `description`, and `repo` (clone URL). Optional fields include `options` (extra `git clone` arguments) and `packageManager` (`npm`, `yarn`, or `pnpm`; default is `npm`). If a custom template uses the same `name` as a built-in one, the custom definition wins. + +Example: + +```json +[ + { + "name": "my-template", + "description": "My custom project template", + "repo": "https://github.com/org/repo.git", + "options": ["--single-branch", "--branch", "main"], + "packageManager": "npm" + } +] +``` + +## Source and releases + +The CLI is developed in the open at [github.com/patternfly/patternfly-cli](https://github.com/patternfly/patternfly-cli). Report issues or contribute there; release notes and tags are published on the repository’s [Releases](https://github.com/patternfly/patternfly-cli/releases) page. From 311103c2d59f2c9a35844ff644167acf9a3b1b9a Mon Sep 17 00:00:00 2001 From: Donald Labaj Date: Thu, 2 Apr 2026 19:45:42 -0400 Subject: [PATCH 2/8] chore: Update with comments from usability testing. --- .../content/get-started/patternfly-cli.md | 102 +++++++++++------ .../content/get-started/patternfly-cli.mdx | 104 ++++++++++++------ 2 files changed, 138 insertions(+), 68 deletions(-) diff --git a/packages/documentation-site/patternfly-docs/content/get-started/patternfly-cli.md b/packages/documentation-site/patternfly-docs/content/get-started/patternfly-cli.md index ca76b3c414..c78adf8238 100644 --- a/packages/documentation-site/patternfly-docs/content/get-started/patternfly-cli.md +++ b/packages/documentation-site/patternfly-docs/content/get-started/patternfly-cli.md @@ -5,83 +5,109 @@ section: get-started --- import './get-started.css'; -import { Alert } from '@patternfly/react-core'; -The [PatternFly CLI](https://github.com/patternfly/patternfly-cli) is a command-line tool for scaffolding projects, applying code changes, and running common project tasks. It is published as [`@patternfly/patternfly-cli` on npm](https://www.npmjs.com/package/@patternfly/patternfly-cli). +The [PatternFly CLI](https://github.com/patternfly/patternfly-cli) is a command-line tool for scaffolding projects, performing code modifications, and running project-related tasks. It aims to streamline development workflows and improve productivity. The published package is [`@patternfly/patternfly-cli` on npm](https://www.npmjs.com/package/@patternfly/patternfly-cli). -## What you can do +## Features + +- **Project scaffolding:** Quickly set up new PatternFly based projects for development, and prototyping. This is done using predefined templates. +- **Code modifications:** Automate repetitive code changes that helps users upgrade to the latest version of PatternFly. +- **Task runner:** Execute project-related tasks efficiently, such as source code management and task running. -- **Scaffold projects** from built-in or custom templates. -- **Automate code updates** for repetitive changes. -- **Run workflows** such as init, sync with GitHub, updates, and deploys to GitHub Pages. ## Prerequisites -Before you install the CLI, set up: +Prerequistes can be found below. For macOS, WSL, and Linux it is recommended that you use [install script](#install-script-macos-and-linux), it covers the items below (you may still need administrator access for system packages). Window based system you will need to install the following yourself before using the CLI: + +- **[Node.js and npm](https://nodejs.org/)** (supported versions **20–24**) — also see [npm](https://www.npmjs.com/). +- **[Corepack](https://nodejs.org/api/corepack.html)** — included with Node.js; enable with `corepack enable` after installing npm. +- **[GitHub CLI](https://cli.github.com/)** (`gh`) -1. **[Node.js and npm](https://nodejs.org/)** (supported versions **20–24**). -1. **[Corepack](https://nodejs.org/api/corepack.html)** — included with Node.js; enable it with `corepack enable` after installing Node. -1. **[GitHub CLI](https://cli.github.com/)** (`gh`) — required for commands that talk to GitHub. +## Installation -## Install +### Install script (macOS and Linux) -Install the CLI globally: +You can pipe the repository install script into `bash`. It installs Node.js with [nvm](https://github.com/nvm-sh/nvm) when `node` is not available, enables Corepack, installs GitHub CLI when it is missing, then installs the CLI globally from npm: + +```sh +curl -fsSL https://raw.githubusercontent.com/patternfly/patternfly-cli/main/scripts/install.sh | bash +``` + +The script may prompt for `sudo` when your system package manager installs GitHub CLI. + +### Windows Install + + After installing the [prerequisites](#prerequisites) on your machine, install the published package globally: ```sh npm install -g @patternfly/patternfly-cli ``` -## Check your setup +## Uninstall + +### Uninstall script (macOS and Linux) -Run the doctor command to verify prerequisites: +If you ever wish to uninstall PatternFly Cli, you can do the following. Pipe the repository uninstall script into `bash`. It removes the globally installed `@patternfly/patternfly-cli` package with npm. It does **not** remove Node.js, nvm, Corepack, or GitHub CLI. ```sh -patternfly-cli doctor +curl -fsSL https://raw.githubusercontent.com/patternfly/patternfly-cli/main/scripts/uninstall.sh | bash ``` -To try to fix missing pieces automatically (Corepack and GitHub CLI only): +Swap `main` for another branch or tag if you need a specific revision. To save the script and inspect it before running: ```sh -patternfly-cli doctor --fix +curl -fsSL https://raw.githubusercontent.com/patternfly/patternfly-cli/main/scripts/uninstall.sh -o uninstall-patternfly-cli.sh +bash uninstall-patternfly-cli.sh ``` - -The `doctor --fix` option does not install or upgrade Node.js. If Node.js is missing or below version 20, install the current **LTS** release from [nodejs.org](https://nodejs.org/). - +### Windows npm package uninstall -## Commands +If you installed the CLI on Windows, you can remove the CLI with: -After installation, run: +```sh +npm uninstall -g @patternfly/patternfly-cli +``` + +## Usage + +After installation, you can verify the latest version of the CLI has been installed by running the following in the termianl: ```sh -patternfly-cli [command] +patternfly-cli -v ``` +### Available CLI commands + | Command | Description | | --- | --- | -| `doctor` | Check requirements; use `--fix` to enable Corepack and install `gh` where supported. | -| `create` | Create a new project from a template. | -| `list` | List available templates (built-in and custom). | -| `update` | Update the project to a newer PatternFly-oriented version where applicable. | -| `init` | Initialize a git repository and optionally create a GitHub repo. | -| `save` | Commit and push changes on the current branch. | -| `load` | Pull the latest changes from GitHub. | -| `deploy` | Build and deploy the app to GitHub Pages. | +| `create` | Create a new project from the available templates. | +| `list` | List all available templates (built-in and optional custom). | +| `update` | Update your project to a newer version. | +| `cli-upgrade` | Upgrade the globally installed CLI to the latest npm release. It runs `npm install -g @patternfly/patternfly-cli@latest`; use your package manager’s equivalent if you did not install with npm. | +| `init` | Initialize a git repository and optionally create a GitHub repository. | +| `save` | Commit and push changes to the current branch. | +| `load` | Pull the latest updates from GitHub. | +| `deploy` | Build and deploy your app to GitHub Pages. | For the most up-to-date flags and behavior, see the [PatternFly CLI README](https://github.com/patternfly/patternfly-cli/blob/main/README.md) on GitHub. ## Custom templates -You can merge your own templates with the built-ins by passing a JSON file with `--template-file` (or `-t`): +You can add your own templates in addition to the built-in ones by passing a JSON file with `--template-file` (or `-t`). Custom templates are merged with the built-in list; if a custom template has the same `name` as a built-in one, the custom definition is used. + +**Create with custom templates:** ```sh patternfly-cli create my-app --template-file ./my-templates.json -patternfly-cli list --template-file ./my-templates.json ``` -Each entry is an object with at least `name`, `description`, and `repo` (clone URL). Optional fields include `options` (extra `git clone` arguments) and `packageManager` (`npm`, `yarn`, or `pnpm`; default is `npm`). If a custom template uses the same `name` as a built-in one, the custom definition wins. +**List templates including custom file:** -Example: +```sh +patternfly-cli list --template-file ./my-templates.json +``` + +**JSON format** (array of template objects, same shape as the built-in templates): ```json [ @@ -95,6 +121,12 @@ Example: ] ``` +- **`name`** (required): Template identifier. +- **`description`** (required): Short description shown in prompts and `list`. +- **`repo`** (required): Git clone URL. +- **`options`** (optional): Array of extra arguments for `git clone` (e.g. `["--single-branch", "--branch", "main"]`). +- **`packageManager`** (optional): `npm`, `yarn`, or `pnpm`; defaults to `npm` if omitted. + ## Source and releases The CLI is developed in the open at [github.com/patternfly/patternfly-cli](https://github.com/patternfly/patternfly-cli). Report issues or contribute there; release notes and tags are published on the repository’s [Releases](https://github.com/patternfly/patternfly-cli/releases) page. diff --git a/packages/site/src/content/get-started/patternfly-cli.mdx b/packages/site/src/content/get-started/patternfly-cli.mdx index ca76b3c414..642532d9e2 100644 --- a/packages/site/src/content/get-started/patternfly-cli.mdx +++ b/packages/site/src/content/get-started/patternfly-cli.mdx @@ -5,51 +5,76 @@ section: get-started --- import './get-started.css'; -import { Alert } from '@patternfly/react-core'; -The [PatternFly CLI](https://github.com/patternfly/patternfly-cli) is a command-line tool for scaffolding projects, applying code changes, and running common project tasks. It is published as [`@patternfly/patternfly-cli` on npm](https://www.npmjs.com/package/@patternfly/patternfly-cli). +The [PatternFly CLI](https://github.com/patternfly/patternfly-cli) is a command-line tool for scaffolding projects, performing code modifications, and running project-related tasks. It aims to streamline development workflows and improve productivity. The published package is [`@patternfly/patternfly-cli` on npm](https://www.npmjs.com/package/@patternfly/patternfly-cli). -## What you can do +## Features -- **Scaffold projects** from built-in or custom templates. -- **Automate code updates** for repetitive changes. -- **Run workflows** such as init, sync with GitHub, updates, and deploys to GitHub Pages. +- **Project scaffolding:** Quickly set up new projects with predefined templates. +- **Code modifications:** Automate repetitive code changes. +- **Task runner:** Execute project-related tasks efficiently. ## Prerequisites -Before you install the CLI, set up: +If you use the [install script](#install-script-macos-and-linux) on macOS or Linux, it covers the items below (you may still need administrator access for system packages). Otherwise, install the following yourself before using the CLI: -1. **[Node.js and npm](https://nodejs.org/)** (supported versions **20–24**). -1. **[Corepack](https://nodejs.org/api/corepack.html)** — included with Node.js; enable it with `corepack enable` after installing Node. -1. **[GitHub CLI](https://cli.github.com/)** (`gh`) — required for commands that talk to GitHub. +- **[Node.js and npm](https://nodejs.org/)** (supported versions **20–24**) — also see [npm](https://www.npmjs.com/). +- **[Corepack](https://nodejs.org/api/corepack.html)** — included with Node.js; enable with `corepack enable` after installing npm. +- **[GitHub CLI](https://cli.github.com/)** (`gh`) -## Install +## Installation -Install the CLI globally: +### Install script (macOS and Linux) + +You can pipe the repository install script into `bash`. It installs Node.js with [nvm](https://github.com/nvm-sh/nvm) when `node` is not available, enables Corepack, installs GitHub CLI when it is missing, then installs the CLI globally from npm: + +```sh +curl -fsSL https://raw.githubusercontent.com/patternfly/patternfly-cli/main/scripts/install.sh | bash +``` + +Swap `main` for another branch or tag if you need a specific revision. To save the script and inspect it before running: + +```sh +curl -fsSL https://raw.githubusercontent.com/patternfly/patternfly-cli/main/scripts/install.sh -o install-patternfly-cli.sh +bash install-patternfly-cli.sh +``` + +The script may prompt for `sudo` when your system package manager installs GitHub CLI. + +### npm + +If you already have the [prerequisites](#prerequisites) on your machine, install the published package globally: ```sh npm install -g @patternfly/patternfly-cli ``` -## Check your setup +## Uninstall + +### Uninstall script (macOS and Linux) -Run the doctor command to verify prerequisites: +Pipe the repository uninstall script into `bash`. It removes the globally installed `@patternfly/patternfly-cli` package with npm. It does **not** remove Node.js, nvm, Corepack, or GitHub CLI. ```sh -patternfly-cli doctor +curl -fsSL https://raw.githubusercontent.com/patternfly/patternfly-cli/main/scripts/uninstall.sh | bash ``` -To try to fix missing pieces automatically (Corepack and GitHub CLI only): +Swap `main` for another branch or tag if you need a specific revision. To save the script and inspect it before running: ```sh -patternfly-cli doctor --fix +curl -fsSL https://raw.githubusercontent.com/patternfly/patternfly-cli/main/scripts/uninstall.sh -o uninstall-patternfly-cli.sh +bash uninstall-patternfly-cli.sh ``` - -The `doctor --fix` option does not install or upgrade Node.js. If Node.js is missing or below version 20, install the current **LTS** release from [nodejs.org](https://nodejs.org/). - +### npm -## Commands +If you installed with npm globally, remove the package with: + +```sh +npm uninstall -g @patternfly/patternfly-cli +``` + +## Usage After installation, run: @@ -57,31 +82,38 @@ After installation, run: patternfly-cli [command] ``` +### Available commands + | Command | Description | | --- | --- | -| `doctor` | Check requirements; use `--fix` to enable Corepack and install `gh` where supported. | -| `create` | Create a new project from a template. | -| `list` | List available templates (built-in and custom). | -| `update` | Update the project to a newer PatternFly-oriented version where applicable. | -| `init` | Initialize a git repository and optionally create a GitHub repo. | -| `save` | Commit and push changes on the current branch. | -| `load` | Pull the latest changes from GitHub. | -| `deploy` | Build and deploy the app to GitHub Pages. | +| `create` | Create a new project from the available templates. | +| `list` | List all available templates (built-in and optional custom). | +| `update` | Update your project to a newer version. | +| `cli-upgrade` | Upgrade the globally installed CLI to the latest npm release. It runs `npm install -g @patternfly/patternfly-cli@latest`; use your package manager’s equivalent if you did not install with npm. | +| `init` | Initialize a git repository and optionally create a GitHub repository. | +| `save` | Commit and push changes to the current branch. | +| `load` | Pull the latest updates from GitHub. | +| `deploy` | Build and deploy your app to GitHub Pages. | For the most up-to-date flags and behavior, see the [PatternFly CLI README](https://github.com/patternfly/patternfly-cli/blob/main/README.md) on GitHub. ## Custom templates -You can merge your own templates with the built-ins by passing a JSON file with `--template-file` (or `-t`): +You can add your own templates in addition to the built-in ones by passing a JSON file with `--template-file` (or `-t`). Custom templates are merged with the built-in list; if a custom template has the same `name` as a built-in one, the custom definition is used. + +**Create with custom templates:** ```sh patternfly-cli create my-app --template-file ./my-templates.json -patternfly-cli list --template-file ./my-templates.json ``` -Each entry is an object with at least `name`, `description`, and `repo` (clone URL). Optional fields include `options` (extra `git clone` arguments) and `packageManager` (`npm`, `yarn`, or `pnpm`; default is `npm`). If a custom template uses the same `name` as a built-in one, the custom definition wins. +**List templates including custom file:** + +```sh +patternfly-cli list --template-file ./my-templates.json +``` -Example: +**JSON format** (array of template objects, same shape as the built-in templates): ```json [ @@ -95,6 +127,12 @@ Example: ] ``` +- **`name`** (required): Template identifier. +- **`description`** (required): Short description shown in prompts and `list`. +- **`repo`** (required): Git clone URL. +- **`options`** (optional): Array of extra arguments for `git clone` (e.g. `["--single-branch", "--branch", "main"]`). +- **`packageManager`** (optional): `npm`, `yarn`, or `pnpm`; defaults to `npm` if omitted. + ## Source and releases The CLI is developed in the open at [github.com/patternfly/patternfly-cli](https://github.com/patternfly/patternfly-cli). Report issues or contribute there; release notes and tags are published on the repository’s [Releases](https://github.com/patternfly/patternfly-cli/releases) page. From 47ec8f3dfc6733d82aa0719fe042a411d0187fa0 Mon Sep 17 00:00:00 2001 From: Donald Labaj Date: Thu, 2 Apr 2026 20:13:07 -0400 Subject: [PATCH 3/8] chore: Added review comments. --- .../content/get-started/patternfly-cli.md | 38 +++---------------- 1 file changed, 5 insertions(+), 33 deletions(-) diff --git a/packages/documentation-site/patternfly-docs/content/get-started/patternfly-cli.md b/packages/documentation-site/patternfly-docs/content/get-started/patternfly-cli.md index c78adf8238..6db306ba0c 100644 --- a/packages/documentation-site/patternfly-docs/content/get-started/patternfly-cli.md +++ b/packages/documentation-site/patternfly-docs/content/get-started/patternfly-cli.md @@ -15,8 +15,9 @@ The [PatternFly CLI](https://github.com/patternfly/patternfly-cli) is a command- - **Task runner:** Execute project-related tasks efficiently, such as source code management and task running. -## Prerequisites +## How do I setup PatternFly CLI? +### Prerequisites Prerequistes can be found below. For macOS, WSL, and Linux it is recommended that you use [install script](#install-script-macos-and-linux), it covers the items below (you may still need administrator access for system packages). Window based system you will need to install the following yourself before using the CLI: - **[Node.js and npm](https://nodejs.org/)** (supported versions **20–24**) — also see [npm](https://www.npmjs.com/). @@ -43,31 +44,6 @@ The script may prompt for `sudo` when your system package manager installs GitHu npm install -g @patternfly/patternfly-cli ``` -## Uninstall - -### Uninstall script (macOS and Linux) - -If you ever wish to uninstall PatternFly Cli, you can do the following. Pipe the repository uninstall script into `bash`. It removes the globally installed `@patternfly/patternfly-cli` package with npm. It does **not** remove Node.js, nvm, Corepack, or GitHub CLI. - -```sh -curl -fsSL https://raw.githubusercontent.com/patternfly/patternfly-cli/main/scripts/uninstall.sh | bash -``` - -Swap `main` for another branch or tag if you need a specific revision. To save the script and inspect it before running: - -```sh -curl -fsSL https://raw.githubusercontent.com/patternfly/patternfly-cli/main/scripts/uninstall.sh -o uninstall-patternfly-cli.sh -bash uninstall-patternfly-cli.sh -``` - -### Windows npm package uninstall - -If you installed the CLI on Windows, you can remove the CLI with: - -```sh -npm uninstall -g @patternfly/patternfly-cli -``` - ## Usage After installation, you can verify the latest version of the CLI has been installed by running the following in the termianl: @@ -78,7 +54,7 @@ patternfly-cli -v ### Available CLI commands -| Command | Description | +| Command | Usage | | --- | --- | | `create` | Create a new project from the available templates. | | `list` | List all available templates (built-in and optional custom). | @@ -89,9 +65,9 @@ patternfly-cli -v | `load` | Pull the latest updates from GitHub. | | `deploy` | Build and deploy your app to GitHub Pages. | -For the most up-to-date flags and behavior, see the [PatternFly CLI README](https://github.com/patternfly/patternfly-cli/blob/main/README.md) on GitHub. +For the most up-to-date flags and behavior guidance, refer to [PatternFly CLI README](https://github.com/patternfly/patternfly-cli/blob/main/README.md) on GitHub. -## Custom templates +### Custom templates You can add your own templates in addition to the built-in ones by passing a JSON file with `--template-file` (or `-t`). Custom templates are merged with the built-in list; if a custom template has the same `name` as a built-in one, the custom definition is used. @@ -126,7 +102,3 @@ patternfly-cli list --template-file ./my-templates.json - **`repo`** (required): Git clone URL. - **`options`** (optional): Array of extra arguments for `git clone` (e.g. `["--single-branch", "--branch", "main"]`). - **`packageManager`** (optional): `npm`, `yarn`, or `pnpm`; defaults to `npm` if omitted. - -## Source and releases - -The CLI is developed in the open at [github.com/patternfly/patternfly-cli](https://github.com/patternfly/patternfly-cli). Report issues or contribute there; release notes and tags are published on the repository’s [Releases](https://github.com/patternfly/patternfly-cli/releases) page. From 2af1111a2a78f36bbc643810daa6c6cc0d5298eb Mon Sep 17 00:00:00 2001 From: Donald Labaj Date: Thu, 2 Apr 2026 20:14:12 -0400 Subject: [PATCH 4/8] chore: Added review comments. --- .../content/get-started/patternfly-cli.mdx | 64 +++++-------------- 1 file changed, 15 insertions(+), 49 deletions(-) diff --git a/packages/site/src/content/get-started/patternfly-cli.mdx b/packages/site/src/content/get-started/patternfly-cli.mdx index 642532d9e2..6db306ba0c 100644 --- a/packages/site/src/content/get-started/patternfly-cli.mdx +++ b/packages/site/src/content/get-started/patternfly-cli.mdx @@ -10,13 +10,15 @@ The [PatternFly CLI](https://github.com/patternfly/patternfly-cli) is a command- ## Features -- **Project scaffolding:** Quickly set up new projects with predefined templates. -- **Code modifications:** Automate repetitive code changes. -- **Task runner:** Execute project-related tasks efficiently. +- **Project scaffolding:** Quickly set up new PatternFly based projects for development, and prototyping. This is done using predefined templates. +- **Code modifications:** Automate repetitive code changes that helps users upgrade to the latest version of PatternFly. +- **Task runner:** Execute project-related tasks efficiently, such as source code management and task running. -## Prerequisites -If you use the [install script](#install-script-macos-and-linux) on macOS or Linux, it covers the items below (you may still need administrator access for system packages). Otherwise, install the following yourself before using the CLI: +## How do I setup PatternFly CLI? + +### Prerequisites +Prerequistes can be found below. For macOS, WSL, and Linux it is recommended that you use [install script](#install-script-macos-and-linux), it covers the items below (you may still need administrator access for system packages). Window based system you will need to install the following yourself before using the CLI: - **[Node.js and npm](https://nodejs.org/)** (supported versions **20–24**) — also see [npm](https://www.npmjs.com/). - **[Corepack](https://nodejs.org/api/corepack.html)** — included with Node.js; enable with `corepack enable` after installing npm. @@ -32,59 +34,27 @@ You can pipe the repository install script into `bash`. It installs Node.js with curl -fsSL https://raw.githubusercontent.com/patternfly/patternfly-cli/main/scripts/install.sh | bash ``` -Swap `main` for another branch or tag if you need a specific revision. To save the script and inspect it before running: - -```sh -curl -fsSL https://raw.githubusercontent.com/patternfly/patternfly-cli/main/scripts/install.sh -o install-patternfly-cli.sh -bash install-patternfly-cli.sh -``` - The script may prompt for `sudo` when your system package manager installs GitHub CLI. -### npm +### Windows Install -If you already have the [prerequisites](#prerequisites) on your machine, install the published package globally: + After installing the [prerequisites](#prerequisites) on your machine, install the published package globally: ```sh npm install -g @patternfly/patternfly-cli ``` -## Uninstall - -### Uninstall script (macOS and Linux) - -Pipe the repository uninstall script into `bash`. It removes the globally installed `@patternfly/patternfly-cli` package with npm. It does **not** remove Node.js, nvm, Corepack, or GitHub CLI. - -```sh -curl -fsSL https://raw.githubusercontent.com/patternfly/patternfly-cli/main/scripts/uninstall.sh | bash -``` - -Swap `main` for another branch or tag if you need a specific revision. To save the script and inspect it before running: - -```sh -curl -fsSL https://raw.githubusercontent.com/patternfly/patternfly-cli/main/scripts/uninstall.sh -o uninstall-patternfly-cli.sh -bash uninstall-patternfly-cli.sh -``` - -### npm - -If you installed with npm globally, remove the package with: - -```sh -npm uninstall -g @patternfly/patternfly-cli -``` - ## Usage -After installation, run: +After installation, you can verify the latest version of the CLI has been installed by running the following in the termianl: ```sh -patternfly-cli [command] +patternfly-cli -v ``` -### Available commands +### Available CLI commands -| Command | Description | +| Command | Usage | | --- | --- | | `create` | Create a new project from the available templates. | | `list` | List all available templates (built-in and optional custom). | @@ -95,9 +65,9 @@ patternfly-cli [command] | `load` | Pull the latest updates from GitHub. | | `deploy` | Build and deploy your app to GitHub Pages. | -For the most up-to-date flags and behavior, see the [PatternFly CLI README](https://github.com/patternfly/patternfly-cli/blob/main/README.md) on GitHub. +For the most up-to-date flags and behavior guidance, refer to [PatternFly CLI README](https://github.com/patternfly/patternfly-cli/blob/main/README.md) on GitHub. -## Custom templates +### Custom templates You can add your own templates in addition to the built-in ones by passing a JSON file with `--template-file` (or `-t`). Custom templates are merged with the built-in list; if a custom template has the same `name` as a built-in one, the custom definition is used. @@ -132,7 +102,3 @@ patternfly-cli list --template-file ./my-templates.json - **`repo`** (required): Git clone URL. - **`options`** (optional): Array of extra arguments for `git clone` (e.g. `["--single-branch", "--branch", "main"]`). - **`packageManager`** (optional): `npm`, `yarn`, or `pnpm`; defaults to `npm` if omitted. - -## Source and releases - -The CLI is developed in the open at [github.com/patternfly/patternfly-cli](https://github.com/patternfly/patternfly-cli). Report issues or contribute there; release notes and tags are published on the repository’s [Releases](https://github.com/patternfly/patternfly-cli/releases) page. From 7128c866ad3d264d04172f82c6c6d24e34e41906 Mon Sep 17 00:00:00 2001 From: Donald Labaj Date: Thu, 2 Apr 2026 20:16:59 -0400 Subject: [PATCH 5/8] chore: Added review comments. --- .../patternfly-cli.md | 2 +- .../content/get-started/patternfly-cli.mdx | 104 ------------------ 2 files changed, 1 insertion(+), 105 deletions(-) rename packages/documentation-site/patternfly-docs/content/{get-started => developer-guides}/patternfly-cli.md (99%) delete mode 100644 packages/site/src/content/get-started/patternfly-cli.mdx diff --git a/packages/documentation-site/patternfly-docs/content/get-started/patternfly-cli.md b/packages/documentation-site/patternfly-docs/content/developer-guides/patternfly-cli.md similarity index 99% rename from packages/documentation-site/patternfly-docs/content/get-started/patternfly-cli.md rename to packages/documentation-site/patternfly-docs/content/developer-guides/patternfly-cli.md index 6db306ba0c..c4a33249d9 100644 --- a/packages/documentation-site/patternfly-docs/content/get-started/patternfly-cli.md +++ b/packages/documentation-site/patternfly-docs/content/developer-guides/patternfly-cli.md @@ -1,7 +1,7 @@ --- id: PatternFly CLI title: PatternFly CLI -section: get-started +section: developer-guides --- import './get-started.css'; diff --git a/packages/site/src/content/get-started/patternfly-cli.mdx b/packages/site/src/content/get-started/patternfly-cli.mdx deleted file mode 100644 index 6db306ba0c..0000000000 --- a/packages/site/src/content/get-started/patternfly-cli.mdx +++ /dev/null @@ -1,104 +0,0 @@ ---- -id: PatternFly CLI -title: PatternFly CLI -section: get-started ---- - -import './get-started.css'; - -The [PatternFly CLI](https://github.com/patternfly/patternfly-cli) is a command-line tool for scaffolding projects, performing code modifications, and running project-related tasks. It aims to streamline development workflows and improve productivity. The published package is [`@patternfly/patternfly-cli` on npm](https://www.npmjs.com/package/@patternfly/patternfly-cli). - -## Features - -- **Project scaffolding:** Quickly set up new PatternFly based projects for development, and prototyping. This is done using predefined templates. -- **Code modifications:** Automate repetitive code changes that helps users upgrade to the latest version of PatternFly. -- **Task runner:** Execute project-related tasks efficiently, such as source code management and task running. - - -## How do I setup PatternFly CLI? - -### Prerequisites -Prerequistes can be found below. For macOS, WSL, and Linux it is recommended that you use [install script](#install-script-macos-and-linux), it covers the items below (you may still need administrator access for system packages). Window based system you will need to install the following yourself before using the CLI: - -- **[Node.js and npm](https://nodejs.org/)** (supported versions **20–24**) — also see [npm](https://www.npmjs.com/). -- **[Corepack](https://nodejs.org/api/corepack.html)** — included with Node.js; enable with `corepack enable` after installing npm. -- **[GitHub CLI](https://cli.github.com/)** (`gh`) - -## Installation - -### Install script (macOS and Linux) - -You can pipe the repository install script into `bash`. It installs Node.js with [nvm](https://github.com/nvm-sh/nvm) when `node` is not available, enables Corepack, installs GitHub CLI when it is missing, then installs the CLI globally from npm: - -```sh -curl -fsSL https://raw.githubusercontent.com/patternfly/patternfly-cli/main/scripts/install.sh | bash -``` - -The script may prompt for `sudo` when your system package manager installs GitHub CLI. - -### Windows Install - - After installing the [prerequisites](#prerequisites) on your machine, install the published package globally: - -```sh -npm install -g @patternfly/patternfly-cli -``` - -## Usage - -After installation, you can verify the latest version of the CLI has been installed by running the following in the termianl: - -```sh -patternfly-cli -v -``` - -### Available CLI commands - -| Command | Usage | -| --- | --- | -| `create` | Create a new project from the available templates. | -| `list` | List all available templates (built-in and optional custom). | -| `update` | Update your project to a newer version. | -| `cli-upgrade` | Upgrade the globally installed CLI to the latest npm release. It runs `npm install -g @patternfly/patternfly-cli@latest`; use your package manager’s equivalent if you did not install with npm. | -| `init` | Initialize a git repository and optionally create a GitHub repository. | -| `save` | Commit and push changes to the current branch. | -| `load` | Pull the latest updates from GitHub. | -| `deploy` | Build and deploy your app to GitHub Pages. | - -For the most up-to-date flags and behavior guidance, refer to [PatternFly CLI README](https://github.com/patternfly/patternfly-cli/blob/main/README.md) on GitHub. - -### Custom templates - -You can add your own templates in addition to the built-in ones by passing a JSON file with `--template-file` (or `-t`). Custom templates are merged with the built-in list; if a custom template has the same `name` as a built-in one, the custom definition is used. - -**Create with custom templates:** - -```sh -patternfly-cli create my-app --template-file ./my-templates.json -``` - -**List templates including custom file:** - -```sh -patternfly-cli list --template-file ./my-templates.json -``` - -**JSON format** (array of template objects, same shape as the built-in templates): - -```json -[ - { - "name": "my-template", - "description": "My custom project template", - "repo": "https://github.com/org/repo.git", - "options": ["--single-branch", "--branch", "main"], - "packageManager": "npm" - } -] -``` - -- **`name`** (required): Template identifier. -- **`description`** (required): Short description shown in prompts and `list`. -- **`repo`** (required): Git clone URL. -- **`options`** (optional): Array of extra arguments for `git clone` (e.g. `["--single-branch", "--branch", "main"]`). -- **`packageManager`** (optional): `npm`, `yarn`, or `pnpm`; defaults to `npm` if omitted. From dfdd52f60ce0ebe0283f4ee591d7a38979d367ef Mon Sep 17 00:00:00 2001 From: Donald Labaj Date: Thu, 2 Apr 2026 20:21:06 -0400 Subject: [PATCH 6/8] chore: Added review comments. --- .../patternfly-docs/content/developer-guides/patternfly-cli.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/packages/documentation-site/patternfly-docs/content/developer-guides/patternfly-cli.md b/packages/documentation-site/patternfly-docs/content/developer-guides/patternfly-cli.md index c4a33249d9..c06b6344ee 100644 --- a/packages/documentation-site/patternfly-docs/content/developer-guides/patternfly-cli.md +++ b/packages/documentation-site/patternfly-docs/content/developer-guides/patternfly-cli.md @@ -4,8 +4,6 @@ title: PatternFly CLI section: developer-guides --- -import './get-started.css'; - The [PatternFly CLI](https://github.com/patternfly/patternfly-cli) is a command-line tool for scaffolding projects, performing code modifications, and running project-related tasks. It aims to streamline development workflows and improve productivity. The published package is [`@patternfly/patternfly-cli` on npm](https://www.npmjs.com/package/@patternfly/patternfly-cli). ## Features From d526d7f5f6c66385d8a00896eeb9a8815235fc8f Mon Sep 17 00:00:00 2001 From: Donald Labaj Date: Mon, 6 Apr 2026 13:15:55 -0400 Subject: [PATCH 7/8] Update packages/documentation-site/patternfly-docs/content/developer-guides/patternfly-cli.md Co-authored-by: Erin Donehoo <105813956+edonehoo@users.noreply.github.com> --- .../content/developer-guides/patternfly-cli.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/documentation-site/patternfly-docs/content/developer-guides/patternfly-cli.md b/packages/documentation-site/patternfly-docs/content/developer-guides/patternfly-cli.md index c06b6344ee..bda9f149fd 100644 --- a/packages/documentation-site/patternfly-docs/content/developer-guides/patternfly-cli.md +++ b/packages/documentation-site/patternfly-docs/content/developer-guides/patternfly-cli.md @@ -8,8 +8,8 @@ The [PatternFly CLI](https://github.com/patternfly/patternfly-cli) is a command- ## Features -- **Project scaffolding:** Quickly set up new PatternFly based projects for development, and prototyping. This is done using predefined templates. -- **Code modifications:** Automate repetitive code changes that helps users upgrade to the latest version of PatternFly. +- **Project scaffolding:** Quickly set up new PatternFly based projects for development and prototyping via predefined templates. +- **Code modifications:** Automate repetitive code changes to help accelerate PatternFly version upgrades. - **Task runner:** Execute project-related tasks efficiently, such as source code management and task running. From 139bbe5ef3a014052980b72de4a6eda14e168ec9 Mon Sep 17 00:00:00 2001 From: Donald Labaj Date: Mon, 6 Apr 2026 13:50:54 -0400 Subject: [PATCH 8/8] Apply suggestions from code review Co-authored-by: Erin Donehoo <105813956+edonehoo@users.noreply.github.com> --- .../developer-guides/patternfly-cli.md | 45 +++++++++---------- 1 file changed, 21 insertions(+), 24 deletions(-) diff --git a/packages/documentation-site/patternfly-docs/content/developer-guides/patternfly-cli.md b/packages/documentation-site/patternfly-docs/content/developer-guides/patternfly-cli.md index bda9f149fd..909e0e9191 100644 --- a/packages/documentation-site/patternfly-docs/content/developer-guides/patternfly-cli.md +++ b/packages/documentation-site/patternfly-docs/content/developer-guides/patternfly-cli.md @@ -6,35 +6,35 @@ section: developer-guides The [PatternFly CLI](https://github.com/patternfly/patternfly-cli) is a command-line tool for scaffolding projects, performing code modifications, and running project-related tasks. It aims to streamline development workflows and improve productivity. The published package is [`@patternfly/patternfly-cli` on npm](https://www.npmjs.com/package/@patternfly/patternfly-cli). -## Features +## What does the PatternFly CLI help with? - **Project scaffolding:** Quickly set up new PatternFly based projects for development and prototyping via predefined templates. - **Code modifications:** Automate repetitive code changes to help accelerate PatternFly version upgrades. - **Task runner:** Execute project-related tasks efficiently, such as source code management and task running. -## How do I setup PatternFly CLI? +## How do I set up PatternFly CLI? ### Prerequisites -Prerequistes can be found below. For macOS, WSL, and Linux it is recommended that you use [install script](#install-script-macos-and-linux), it covers the items below (you may still need administrator access for system packages). Window based system you will need to install the following yourself before using the CLI: +There are a few key prerequisites to meet before using PatternFly CLI. For macOS, WSL, and Linux, we recommended using [install script](#install-script-macos-and-linux) to address the following prerequisites (you might still need administrator access for system packages). For a Windows-based system, you will need to install the following items manually: -- **[Node.js and npm](https://nodejs.org/)** (supported versions **20–24**) — also see [npm](https://www.npmjs.com/). -- **[Corepack](https://nodejs.org/api/corepack.html)** — included with Node.js; enable with `corepack enable` after installing npm. +- **[Node.js](https://nodejs.org/)** (Supported versions: 20–24) and **[npm](https://www.npmjs.com/)** +- **[Corepack](https://nodejs.org/api/corepack.html)** (Included with Node.js and enabled via `corepack enable` after installing npm) - **[GitHub CLI](https://cli.github.com/)** (`gh`) ## Installation ### Install script (macOS and Linux) -You can pipe the repository install script into `bash`. It installs Node.js with [nvm](https://github.com/nvm-sh/nvm) when `node` is not available, enables Corepack, installs GitHub CLI when it is missing, then installs the CLI globally from npm: +You can pipe the repository install script into `bash`. This installs Node.js with [nvm](https://github.com/nvm-sh/nvm) when `node` is not available, enables Corepack, installs GitHub CLI when it is missing, and installs the CLI globally from npm: ```sh curl -fsSL https://raw.githubusercontent.com/patternfly/patternfly-cli/main/scripts/install.sh | bash ``` -The script may prompt for `sudo` when your system package manager installs GitHub CLI. +The script might prompt you to include `sudo` when your system package manager installs GitHub CLI. -### Windows Install +### Windows After installing the [prerequisites](#prerequisites) on your machine, install the published package globally: @@ -42,22 +42,19 @@ The script may prompt for `sudo` when your system package manager installs GitHu npm install -g @patternfly/patternfly-cli ``` -## Usage +## How do I use PatternFly CLI? -After installation, you can verify the latest version of the CLI has been installed by running the following in the termianl: +After installation, you can verify the latest version of the CLI has been installed by running the following terminal command: -```sh -patternfly-cli -v -``` ### Available CLI commands - +Once the PatternFly CLI is installed, you can run the following commands via `patternfly-cli [command]`: | Command | Usage | | --- | --- | | `create` | Create a new project from the available templates. | | `list` | List all available templates (built-in and optional custom). | | `update` | Update your project to a newer version. | -| `cli-upgrade` | Upgrade the globally installed CLI to the latest npm release. It runs `npm install -g @patternfly/patternfly-cli@latest`; use your package manager’s equivalent if you did not install with npm. | +| `cli-upgrade` | Upgrade the globally installed CLI to the latest npm release. It runs `npm install -g @patternfly/patternfly-cli@latest`—use your package manager’s equivalent if you did not install with npm. | | `init` | Initialize a git repository and optionally create a GitHub repository. | | `save` | Commit and push changes to the current branch. | | `load` | Pull the latest updates from GitHub. | @@ -67,21 +64,21 @@ For the most up-to-date flags and behavior guidance, refer to [PatternFly CLI RE ### Custom templates -You can add your own templates in addition to the built-in ones by passing a JSON file with `--template-file` (or `-t`). Custom templates are merged with the built-in list; if a custom template has the same `name` as a built-in one, the custom definition is used. +In addition to the built-in templates, you can add your own templates by passing a JSON file with `--template-file` (or `-t`). Custom templates are merged with the built-in list—if a custom template has the same `name` as a built-in template, the custom definition is used. -**Create with custom templates:** +**Create a project based on custom templates:** ```sh patternfly-cli create my-app --template-file ./my-templates.json ``` -**List templates including custom file:** +**List templates included in custom file:** ```sh patternfly-cli list --template-file ./my-templates.json ``` -**JSON format** (array of template objects, same shape as the built-in templates): +**JSON format** (Array of template objects, shown in the same shape as the built-in templates): ```json [ @@ -95,8 +92,8 @@ patternfly-cli list --template-file ./my-templates.json ] ``` -- **`name`** (required): Template identifier. -- **`description`** (required): Short description shown in prompts and `list`. -- **`repo`** (required): Git clone URL. -- **`options`** (optional): Array of extra arguments for `git clone` (e.g. `["--single-branch", "--branch", "main"]`). -- **`packageManager`** (optional): `npm`, `yarn`, or `pnpm`; defaults to `npm` if omitted. +- **`name`** (required): Template identifier +- **`description`** (required): Short description shown in prompts and `list` +- **`repo`** (required): Git clone URL +- **`options`** (optional): Array of extra arguments for `git clone` (such as `["--single-branch", "--branch", "main"]`) +- **`packageManager`** (optional): `npm`, `yarn`, or `pnpm`; defaults to `npm` if omitted