From 494d350190c931b82a9649cb0d3643cdcf5b3a48 Mon Sep 17 00:00:00 2001 From: Donald Labaj Date: Mon, 30 Mar 2026 21:58:54 -0400 Subject: [PATCH] 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.