Skip to content

Commit 011fea9

Browse files
dlabajedonehoo
dlabaj
and
edonehoo
authored
feat: added documentation for patternfly cli. (#5009)
* feat: added documentation for patternfly cli. * chore: updated with comments from team. * Update packages/documentation-site/patternfly-docs/content/AI/patternfly-cli.md Co-authored-by: Erin Donehoo <105813956+edonehoo@users.noreply.github.com> * Update packages/documentation-site/patternfly-docs/content/AI/patternfly-cli.md Co-authored-by: Erin Donehoo <105813956+edonehoo@users.noreply.github.com> * fix: updated with review comments. * chore: updated with additional review comments. * chore: prereq. section. * Update packages/documentation-site/patternfly-docs/content/AI/patternfly-cli.md Co-authored-by: Erin Donehoo <105813956+edonehoo@users.noreply.github.com> * Update packages/documentation-site/patternfly-docs/content/AI/patternfly-cli.md Co-authored-by: Erin Donehoo <105813956+edonehoo@users.noreply.github.com> * Update packages/documentation-site/patternfly-docs/content/AI/patternfly-cli.md Co-authored-by: Erin Donehoo <105813956+edonehoo@users.noreply.github.com> * Update packages/documentation-site/patternfly-docs/content/AI/patternfly-cli.md Co-authored-by: Erin Donehoo <105813956+edonehoo@users.noreply.github.com> * Update packages/documentation-site/patternfly-docs/content/AI/patternfly-cli.md Co-authored-by: Erin Donehoo <105813956+edonehoo@users.noreply.github.com> * chore: fixed code format --------- Co-authored-by: Erin Donehoo <105813956+edonehoo@users.noreply.github.com>
1 parent 77aed25 commit 011fea9

1 file changed

Lines changed: 149 additions & 0 deletions

File tree

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

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
---
2+
id: PatternFly CLI
3+
title: PatternFly CLI
4+
section: AI
5+
---
6+
7+
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 streamlines everyday development work and PatternFly upgrades, making it convenient and easy to work straight from the terminal. You can run it in the terminal on its own, or use it from an AI-enabled editor (such as [Cursor](https://www.cursor.com/)) so coding agents can rely on the same predictable commands for scaffolding, updates, and git workflows. The published package is [`@patternfly/patternfly-cli` on npm](https://www.npmjs.com/package/@patternfly/patternfly-cli).
8+
9+
The npm package installs two equivalent entry points: `patternfly-cli` and the shorter alias `pfcli`. The examples below use `patternfly-cli`, but you can substitute `pfcli` in your own usage if you prefer.
10+
11+
## What does the PatternFly CLI help with?
12+
13+
- **Project scaffolding:** Quickly set up new PatternFly based projects for development and prototyping via predefined templates.
14+
- **Code modifications:** Automate repetitive code changes to help accelerate PatternFly version upgrades.
15+
- **Task execution:** Run project-related tasks such as committing and pushing changes, pulling updates, and deploying your app to GitHub Pages.
16+
17+
18+
## How do I set up PatternFly CLI?
19+
20+
### Prerequisites
21+
There are a few key prerequisites to meet before using PatternFly CLI. For macOS, WSL, and Linux, we recommend 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:
22+
23+
- [Node.js](https://nodejs.org/) (Versions 20–24) and [npm](https://www.npmjs.com/)
24+
- [Corepack](https://nodejs.org/api/corepack.html), which is included with Node.js. After installing npm, enable via `corepack enable`
25+
- [GitHub CLI](https://cli.github.com/)
26+
27+
## Installation
28+
29+
### Install script (macOS and Linux)
30+
31+
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:
32+
33+
```sh
34+
curl -fsSL https://raw.githubusercontent.com/patternfly/patternfly-cli/main/scripts/install.sh | bash
35+
```
36+
37+
The script might prompt you to include `sudo` when your system package manager installs GitHub CLI.
38+
39+
### Windows
40+
41+
After installing the [prerequisites](#prerequisites) on your machine, install the published package globally:
42+
43+
```sh
44+
npm install -g @patternfly/patternfly-cli
45+
```
46+
47+
## How do I use PatternFly CLI?
48+
49+
After installation, you can verify the latest version of the CLI has been installed by running the following terminal command:
50+
51+
```sh
52+
patternfly-cli --version
53+
```
54+
### Typical workflow
55+
56+
If you're starting a new project and publishing it, this is the usual sequence:
57+
58+
```sh
59+
patternfly-cli create my-app # create a new project from a template
60+
cd my-app
61+
patternfly-cli init # set up Git and connect to GitHub
62+
patternfly-cli save # commit and push your changes
63+
patternfly-cli deploy # publish to GitHub Pages
64+
```
65+
66+
For an existing project, use patternfly-cli update to migrate to a newer PatternFly version.
67+
### Available CLI commands
68+
Once the PatternFly CLI is installed, you can run the following commands via `patternfly-cli [command]`:
69+
70+
| Command | Usage |
71+
| --- | --- |
72+
| `create` | Create a new project from the available templates. |
73+
| `list` | List all available templates (built-in and optional custom). |
74+
| `update` | Migrate your project to a newer PatternFly version using codemods, which handle import changes, component renames, and other breaking changes automatically.|
75+
| `cli-upgrade` | Upgrade the globally installed CLI to the latest npm release. It runs `npm install -g @patternfly/patternfly-cli@latest`&mdash;use your package manager’s equivalent if you did not install with npm. |
76+
| `init` | Initialize a git repository and optionally create a GitHub repository. |
77+
| `save` | Commit and push changes to the current branch. |
78+
| `load` | Pull the latest updates from GitHub. |
79+
| `deploy` | Build and deploy your app to GitHub Pages. |
80+
81+
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.
82+
83+
### Predefined templates
84+
85+
The following predefined templates ship with PatternFly CLI:
86+
87+
| Template name | Description |
88+
| --- | --- |
89+
| `starter` | Starter template for a PatternFly React TypeScript project |
90+
| `compass-starter` | Starter template for a PatternFly Compass theme TypeScript project |
91+
| `nextjs-starter` | Starter template for a PatternFly Next.js project |
92+
93+
To use a template, pass the template name to `patternfly-cli create [template name]` or choose the template from the interactive prompt triggered by the generic `patternfly-cli create` comman. To print a list of all templates from your installed version, run `patternfly-cli list`.
94+
95+
Template definitions can be found in the [patternfly-cli repo](https://github.com/patternfly/patternfly-cli/blob/main/src/templates.ts).
96+
97+
### Custom templates
98+
99+
In addition to the predefined templates, you can add your own templates by passing a JSON file with `--template-file` (or `-t`). Custom templates are merged with the predefined list&mdash;if a custom template has the same `name` as a predefined template, the custom definition is used.
100+
101+
**Create a project based on custom templates:**
102+
103+
```sh
104+
patternfly-cli create my-app --template-file ./my-templates.json
105+
```
106+
107+
**List templates included in custom file:**
108+
109+
```sh
110+
patternfly-cli list --template-file ./my-templates.json
111+
```
112+
113+
**JSON format** (Array of template objects, shown in the same shape as the built-in templates):
114+
115+
```json
116+
[
117+
{
118+
"name": "my-template",
119+
"description": "My custom project template",
120+
"repo": "https://github.com/org/repo.git",
121+
"options": ["--single-branch", "--branch", "main"],
122+
"packageManager": "npm"
123+
}
124+
]
125+
```
126+
127+
- **`name`** (required): Template identifier
128+
- **`description`** (required): Short description shown in prompts and `list`
129+
- **`repo`** (required): Git clone URL
130+
- **`options`** (optional): Array of extra arguments for `git clone` (such as `["--single-branch", "--branch", "main"]`)
131+
- **`packageManager`** (optional): `npm`, `yarn`, or `pnpm`; defaults to `npm` if omitted
132+
133+
## Uninstalling PatternFly CLI
134+
135+
### Uninstall script (macOS and Linux)
136+
137+
You can 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:
138+
139+
```sh
140+
curl -fsSL https://raw.githubusercontent.com/patternfly/patternfly-cli/main/scripts/uninstall.sh | bash
141+
```
142+
143+
### Windows
144+
145+
If you installed the published package globally with npm, remove it with:
146+
147+
```sh
148+
npm uninstall -g @patternfly/patternfly-cli
149+
```

0 commit comments

Comments
 (0)