-
Notifications
You must be signed in to change notification settings - Fork 147
feat: Added documenation for patternfly cli. #4981
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from 1 commit
494d350
311103c
47ec8f3
2af1111
7128c86
dfdd52f
d526d7f
139bbe5
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| @@ -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). | ||||||||||||||||||||||||||||||||||
|
||||||||||||||||||||||||||||||||||
| 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 published on npm as [`@patternfly/patternfly-cli`](https://www.npmjs.com/package/@patternfly/patternfly-cli). With this tool, you can scaffold projects from built-in or custom templates, automate code updates for repetitive changes, and run workflows (including init, sync with GitHub, updates, and deploys to GitHub Pages). | |
| The PatternFly CLI is developed in the open at [github.com/patternfly/patternfly-cli](https://github.com/patternfly/patternfly-cli), with release notes and tags published on [Releases page](https://github.com/patternfly/patternfly-cli/releases). To report issues or contribute to this tool, refer to the patternfly-cli repo for more instruction. |
wdyt about this description, rather than the "what you can do" list? Just to build those list points into the narrative a little more
also moved up the bit about source and releases from the end of the page
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| ## 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. |
remove, if you're okay with folding into the intro description as I did
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| ## Prerequisites | |
| ## How do I set up the PatternFly CLI? | |
| ### Prerequisites |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done.
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| Before you install the CLI, set up: | |
| Before you install the PatternFly CLI, you must set up the following: |
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| 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. | |
| 1. **[Node.js and npm](https://nodejs.org/)** (versions 20–24 currently supported). | |
| 1. **[Corepack](https://nodejs.org/api/corepack.html):** After Node is installed, enabled corepack via `corepack enable` on the command line. | |
| 1. **[GitHub CLI](https://cli.github.com/):** Required for commands that refer to GitHub (`gh`). |
Is corepack enable a cli command?
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| ## Install | |
| ### Install |
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| Install the CLI globally: | |
| Install the PatternFly CLI globally: |
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| ## Check your setup | |
| ### Check your setup |
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| Run the doctor command to verify prerequisites: | |
| To verify prerequisites, run the `doctor` command: |
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| To try to fix missing pieces automatically (Corepack and GitHub CLI only): | |
| To try to fix missing pieces automatically, add the `--fix` flag (Corepack and GitHub CLI only): |
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| <Alert title="Node.js must be installed separately" variant="warning" isInline> | |
| 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/). | |
| </Alert> | |
| <Alert title="Node.js must be installed separately" variant="warning" isInline> | |
| 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/). | |
| </Alert> |
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| ## Commands | |
| ## How do I use the PatternFly CLI? | |
| ### Commands |
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| After installation, run: | |
| Once the PatternFly CLI is installed, you can run the following commands via `patternfly-cli [command]`: |
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| | Command | Description | | |
| | Command | Usage | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done.
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| | `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. | | |
| | `doctor` | Check requirements. Add the `--fix` flag 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. | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"Add the --fix flag to enable Corepack and install gh where supported. |" This reads like --fix both enables Corepack and installs gh -- is that correct?
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| 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 the [PatternFly CLI README](https://github.com/patternfly/patternfly-cli/blob/main/README.md) on GitHub. |
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| ## Custom templates | |
| ### Custom templates |
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| You can merge your own templates with the built-ins by passing a JSON file with `--template-file` (or `-t`): | |
| You can merge your own templates with the built-in templates by passing a JSON file with `--template-file` (or `-t`): |
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| 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. | |
| 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` by default, or `yarn`/`pnpm`). If a custom template uses the same `name` as a built-in template, the custom definition is used. |
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| ## 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. |
moving up top?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Do we even need this? I can remove it since the guidance link will take you to the readme that will have this information in it. Removing for now, if you want me to add it back let me know.
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
| ``` | ||
|
|
||
| <Alert title="Node.js must be installed separately" variant="warning" isInline> | ||
| 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/). | ||
| </Alert> | ||
|
|
||
| ## 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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
the get started section is more so intended for introductory/overview information. Are you set on including these docs there? Otherwise, we could move to /developer-guides or maybe at least nest it under get-started/develop (assuming this is a dev-focused tool)?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is for both designers and developers. At the moment it's geared towards designers more. I'm good with putting it under developer guides