Skip to content

Commit 311103c

Browse files
dlabajdlabaj
committed
chore: Update with comments from usability testing.
1 parent 494d350 commit 311103c

2 files changed

Lines changed: 138 additions & 68 deletions

File tree

‎packages/documentation-site/patternfly-docs/content/get-started/patternfly-cli.md‎

Lines changed: 67 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -5,83 +5,109 @@ section: get-started
55
---
66

77
import './get-started.css';
8-
import { Alert } from '@patternfly/react-core';
98

10-
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).
9+
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).
1110

12-
## What you can do
11+
## Features
12+
13+
- **Project scaffolding:** Quickly set up new PatternFly based projects for development, and prototyping. This is done using predefined templates.
14+
- **Code modifications:** Automate repetitive code changes that helps users upgrade to the latest version of PatternFly.
15+
- **Task runner:** Execute project-related tasks efficiently, such as source code management and task running.
1316

14-
- **Scaffold projects** from built-in or custom templates.
15-
- **Automate code updates** for repetitive changes.
16-
- **Run workflows** such as init, sync with GitHub, updates, and deploys to GitHub Pages.
1717

1818
## Prerequisites
1919

20-
Before you install the CLI, set up:
20+
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:
21+
22+
- **[Node.js and npm](https://nodejs.org/)** (supported versions **20–24**) — also see [npm](https://www.npmjs.com/).
23+
- **[Corepack](https://nodejs.org/api/corepack.html)** — included with Node.js; enable with `corepack enable` after installing npm.
24+
- **[GitHub CLI](https://cli.github.com/)** (`gh`)
2125

22-
1. **[Node.js and npm](https://nodejs.org/)** (supported versions **20–24**).
23-
1. **[Corepack](https://nodejs.org/api/corepack.html)** — included with Node.js; enable it with `corepack enable` after installing Node.
24-
1. **[GitHub CLI](https://cli.github.com/)** (`gh`) — required for commands that talk to GitHub.
26+
## Installation
2527

26-
## Install
28+
### Install script (macOS and Linux)
2729

28-
Install the CLI globally:
30+
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:
31+
32+
```sh
33+
curl -fsSL https://raw.githubusercontent.com/patternfly/patternfly-cli/main/scripts/install.sh | bash
34+
```
35+
36+
The script may prompt for `sudo` when your system package manager installs GitHub CLI.
37+
38+
### Windows Install
39+
40+
After installing the [prerequisites](#prerequisites) on your machine, install the published package globally:
2941

3042
```sh
3143
npm install -g @patternfly/patternfly-cli
3244
```
3345

34-
## Check your setup
46+
## Uninstall
47+
48+
### Uninstall script (macOS and Linux)
3549

36-
Run the doctor command to verify prerequisites:
50+
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.
3751

3852
```sh
39-
patternfly-cli doctor
53+
curl -fsSL https://raw.githubusercontent.com/patternfly/patternfly-cli/main/scripts/uninstall.sh | bash
4054
```
4155

42-
To try to fix missing pieces automatically (Corepack and GitHub CLI only):
56+
Swap `main` for another branch or tag if you need a specific revision. To save the script and inspect it before running:
4357

4458
```sh
45-
patternfly-cli doctor --fix
59+
curl -fsSL https://raw.githubusercontent.com/patternfly/patternfly-cli/main/scripts/uninstall.sh -o uninstall-patternfly-cli.sh
60+
bash uninstall-patternfly-cli.sh
4661
```
4762

48-
<Alert title="Node.js must be installed separately" variant="warning" isInline>
49-
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/).
50-
</Alert>
63+
### Windows npm package uninstall
5164

52-
## Commands
65+
If you installed the CLI on Windows, you can remove the CLI with:
5366

54-
After installation, run:
67+
```sh
68+
npm uninstall -g @patternfly/patternfly-cli
69+
```
70+
71+
## Usage
72+
73+
After installation, you can verify the latest version of the CLI has been installed by running the following in the termianl:
5574

5675
```sh
57-
patternfly-cli [command]
76+
patternfly-cli -v
5877
```
5978

79+
### Available CLI commands
80+
6081
| Command | Description |
6182
| --- | --- |
62-
| `doctor` | Check requirements; use `--fix` to enable Corepack and install `gh` where supported. |
63-
| `create` | Create a new project from a template. |
64-
| `list` | List available templates (built-in and custom). |
65-
| `update` | Update the project to a newer PatternFly-oriented version where applicable. |
66-
| `init` | Initialize a git repository and optionally create a GitHub repo. |
67-
| `save` | Commit and push changes on the current branch. |
68-
| `load` | Pull the latest changes from GitHub. |
69-
| `deploy` | Build and deploy the app to GitHub Pages. |
83+
| `create` | Create a new project from the available templates. |
84+
| `list` | List all available templates (built-in and optional custom). |
85+
| `update` | Update your project to a newer version. |
86+
| `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. |
87+
| `init` | Initialize a git repository and optionally create a GitHub repository. |
88+
| `save` | Commit and push changes to the current branch. |
89+
| `load` | Pull the latest updates from GitHub. |
90+
| `deploy` | Build and deploy your app to GitHub Pages. |
7091

7192
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.
7293

7394
## Custom templates
7495

75-
You can merge your own templates with the built-ins by passing a JSON file with `--template-file` (or `-t`):
96+
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.
97+
98+
**Create with custom templates:**
7699

77100
```sh
78101
patternfly-cli create my-app --template-file ./my-templates.json
79-
patternfly-cli list --template-file ./my-templates.json
80102
```
81103

82-
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.
104+
**List templates including custom file:**
83105

84-
Example:
106+
```sh
107+
patternfly-cli list --template-file ./my-templates.json
108+
```
109+
110+
**JSON format** (array of template objects, same shape as the built-in templates):
85111

86112
```json
87113
[
@@ -95,6 +121,12 @@ Example:
95121
]
96122
```
97123

124+
- **`name`** (required): Template identifier.
125+
- **`description`** (required): Short description shown in prompts and `list`.
126+
- **`repo`** (required): Git clone URL.
127+
- **`options`** (optional): Array of extra arguments for `git clone` (e.g. `["--single-branch", "--branch", "main"]`).
128+
- **`packageManager`** (optional): `npm`, `yarn`, or `pnpm`; defaults to `npm` if omitted.
129+
98130
## Source and releases
99131

100132
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.

‎packages/site/src/content/get-started/patternfly-cli.mdx‎

Lines changed: 71 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -5,83 +5,115 @@ section: get-started
55
---
66

77
import './get-started.css';
8-
import { Alert } from '@patternfly/react-core';
98

10-
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).
9+
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).
1110

12-
## What you can do
11+
## Features
1312

14-
- **Scaffold projects** from built-in or custom templates.
15-
- **Automate code updates** for repetitive changes.
16-
- **Run workflows** such as init, sync with GitHub, updates, and deploys to GitHub Pages.
13+
- **Project scaffolding:** Quickly set up new projects with predefined templates.
14+
- **Code modifications:** Automate repetitive code changes.
15+
- **Task runner:** Execute project-related tasks efficiently.
1716

1817
## Prerequisites
1918

20-
Before you install the CLI, set up:
19+
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:
2120

22-
1. **[Node.js and npm](https://nodejs.org/)** (supported versions **20–24**).
23-
1. **[Corepack](https://nodejs.org/api/corepack.html)** — included with Node.js; enable it with `corepack enable` after installing Node.
24-
1. **[GitHub CLI](https://cli.github.com/)** (`gh`) — required for commands that talk to GitHub.
21+
- **[Node.js and npm](https://nodejs.org/)** (supported versions **20–24**) — also see [npm](https://www.npmjs.com/).
22+
- **[Corepack](https://nodejs.org/api/corepack.html)** — included with Node.js; enable with `corepack enable` after installing npm.
23+
- **[GitHub CLI](https://cli.github.com/)** (`gh`)
2524

26-
## Install
25+
## Installation
2726

28-
Install the CLI globally:
27+
### Install script (macOS and Linux)
28+
29+
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:
30+
31+
```sh
32+
curl -fsSL https://raw.githubusercontent.com/patternfly/patternfly-cli/main/scripts/install.sh | bash
33+
```
34+
35+
Swap `main` for another branch or tag if you need a specific revision. To save the script and inspect it before running:
36+
37+
```sh
38+
curl -fsSL https://raw.githubusercontent.com/patternfly/patternfly-cli/main/scripts/install.sh -o install-patternfly-cli.sh
39+
bash install-patternfly-cli.sh
40+
```
41+
42+
The script may prompt for `sudo` when your system package manager installs GitHub CLI.
43+
44+
### npm
45+
46+
If you already have the [prerequisites](#prerequisites) on your machine, install the published package globally:
2947

3048
```sh
3149
npm install -g @patternfly/patternfly-cli
3250
```
3351

34-
## Check your setup
52+
## Uninstall
53+
54+
### Uninstall script (macOS and Linux)
3555

36-
Run the doctor command to verify prerequisites:
56+
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.
3757

3858
```sh
39-
patternfly-cli doctor
59+
curl -fsSL https://raw.githubusercontent.com/patternfly/patternfly-cli/main/scripts/uninstall.sh | bash
4060
```
4161

42-
To try to fix missing pieces automatically (Corepack and GitHub CLI only):
62+
Swap `main` for another branch or tag if you need a specific revision. To save the script and inspect it before running:
4363

4464
```sh
45-
patternfly-cli doctor --fix
65+
curl -fsSL https://raw.githubusercontent.com/patternfly/patternfly-cli/main/scripts/uninstall.sh -o uninstall-patternfly-cli.sh
66+
bash uninstall-patternfly-cli.sh
4667
```
4768

48-
<Alert title="Node.js must be installed separately" variant="warning" isInline>
49-
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/).
50-
</Alert>
69+
### npm
5170

52-
## Commands
71+
If you installed with npm globally, remove the package with:
72+
73+
```sh
74+
npm uninstall -g @patternfly/patternfly-cli
75+
```
76+
77+
## Usage
5378

5479
After installation, run:
5580

5681
```sh
5782
patternfly-cli [command]
5883
```
5984

85+
### Available commands
86+
6087
| Command | Description |
6188
| --- | --- |
62-
| `doctor` | Check requirements; use `--fix` to enable Corepack and install `gh` where supported. |
63-
| `create` | Create a new project from a template. |
64-
| `list` | List available templates (built-in and custom). |
65-
| `update` | Update the project to a newer PatternFly-oriented version where applicable. |
66-
| `init` | Initialize a git repository and optionally create a GitHub repo. |
67-
| `save` | Commit and push changes on the current branch. |
68-
| `load` | Pull the latest changes from GitHub. |
69-
| `deploy` | Build and deploy the app to GitHub Pages. |
89+
| `create` | Create a new project from the available templates. |
90+
| `list` | List all available templates (built-in and optional custom). |
91+
| `update` | Update your project to a newer version. |
92+
| `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. |
93+
| `init` | Initialize a git repository and optionally create a GitHub repository. |
94+
| `save` | Commit and push changes to the current branch. |
95+
| `load` | Pull the latest updates from GitHub. |
96+
| `deploy` | Build and deploy your app to GitHub Pages. |
7097

7198
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.
7299

73100
## Custom templates
74101

75-
You can merge your own templates with the built-ins by passing a JSON file with `--template-file` (or `-t`):
102+
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.
103+
104+
**Create with custom templates:**
76105

77106
```sh
78107
patternfly-cli create my-app --template-file ./my-templates.json
79-
patternfly-cli list --template-file ./my-templates.json
80108
```
81109

82-
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.
110+
**List templates including custom file:**
111+
112+
```sh
113+
patternfly-cli list --template-file ./my-templates.json
114+
```
83115

84-
Example:
116+
**JSON format** (array of template objects, same shape as the built-in templates):
85117

86118
```json
87119
[
@@ -95,6 +127,12 @@ Example:
95127
]
96128
```
97129

130+
- **`name`** (required): Template identifier.
131+
- **`description`** (required): Short description shown in prompts and `list`.
132+
- **`repo`** (required): Git clone URL.
133+
- **`options`** (optional): Array of extra arguments for `git clone` (e.g. `["--single-branch", "--branch", "main"]`).
134+
- **`packageManager`** (optional): `npm`, `yarn`, or `pnpm`; defaults to `npm` if omitted.
135+
98136
## Source and releases
99137

100138
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.

0 commit comments

Comments
 (0)