-
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 all commits
494d350
311103c
47ec8f3
2af1111
7128c86
dfdd52f
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,102 @@ | ||||||||||||||||||||||
| --- | ||||||||||||||||||||||
| id: PatternFly CLI | ||||||||||||||||||||||
| title: PatternFly CLI | ||||||||||||||||||||||
| 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). | ||||||||||||||||||||||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I did just want to mention that (as someone who has no knowledge of this tool) it's not extremely clear to me why this is a separate tool and why designers will be using this. When I read "streamline development workflows and improve productivity" it just sounds like a general dev accelerator tool, so it might be helpful to more explicitly state why we've created this new tool, why we're doing it now, and what's special about it. If I was a designer I wouldn't necessarily pick up that this tool was intended for me to use that extra context could go up front or in the next ## Features section |
||||||||||||||||||||||
|
|
||||||||||||||||||||||
| ## Features | ||||||||||||||||||||||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
Maybe some sort of question-formatted heading to help users move through the doc? |
||||||||||||||||||||||
|
|
||||||||||||||||||||||
| - **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. | ||||||||||||||||||||||
|
Comment on lines
+11
to
+13
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
would be good to clarify what "task running" means in the last bullet - right now the description doesn't add much extra context for what sort of tasks this might refer to |
||||||||||||||||||||||
|
|
||||||||||||||||||||||
|
|
||||||||||||||||||||||
| ## How do I setup PatternFly CLI? | ||||||||||||||||||||||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||||||||||||||
|
|
||||||||||||||||||||||
| ### 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: | ||||||||||||||||||||||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||||||||||||||
|
|
||||||||||||||||||||||
| - **[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`) | ||||||||||||||||||||||
|
Comment on lines
+21
to
+23
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||||||||||||||
|
|
||||||||||||||||||||||
| ## 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: | ||||||||||||||||||||||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||||||||||||||
|
|
||||||||||||||||||||||
| ```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. | ||||||||||||||||||||||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||||||||||||||
|
|
||||||||||||||||||||||
| ### Windows Install | ||||||||||||||||||||||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||||||||||||||
|
|
||||||||||||||||||||||
| After installing the [prerequisites](#prerequisites) on your machine, install the published package globally: | ||||||||||||||||||||||
|
|
||||||||||||||||||||||
| ```sh | ||||||||||||||||||||||
| npm install -g @patternfly/patternfly-cli | ||||||||||||||||||||||
| ``` | ||||||||||||||||||||||
|
|
||||||||||||||||||||||
| ## Usage | ||||||||||||||||||||||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||||||||||||||
|
|
||||||||||||||||||||||
| After installation, you can verify the latest version of the CLI has been installed by running the following in the termianl: | ||||||||||||||||||||||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||||||||||||||
|
|
||||||||||||||||||||||
| ```sh | ||||||||||||||||||||||
| patternfly-cli -v | ||||||||||||||||||||||
| ``` | ||||||||||||||||||||||
|
|
||||||||||||||||||||||
| ### Available CLI commands | ||||||||||||||||||||||
|
|
||||||||||||||||||||||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||||||||||||||
| | 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. | | ||||||||||||||||||||||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||||||||||||||
| | `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. | ||||||||||||||||||||||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||||||||||||||
|
|
||||||||||||||||||||||
| **Create with custom templates:** | ||||||||||||||||||||||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||||||||||||||
|
|
||||||||||||||||||||||
| ```sh | ||||||||||||||||||||||
| patternfly-cli create my-app --template-file ./my-templates.json | ||||||||||||||||||||||
| ``` | ||||||||||||||||||||||
|
|
||||||||||||||||||||||
| **List templates including custom file:** | ||||||||||||||||||||||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||||||||||||||
|
|
||||||||||||||||||||||
| ```sh | ||||||||||||||||||||||
| patternfly-cli list --template-file ./my-templates.json | ||||||||||||||||||||||
| ``` | ||||||||||||||||||||||
|
|
||||||||||||||||||||||
| **JSON format** (array of template objects, same shape as the built-in templates): | ||||||||||||||||||||||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||||||||||||||
|
|
||||||||||||||||||||||
| ```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. | ||||||||||||||||||||||
|
Comment on lines
+98
to
+102
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||||||||||||||
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.
just saw your previous reply that this tool is actually more oriented towards designers right now. with that in mind (combined with the technicality of the doc itself), I think your initial suggestion of putting this in the get started section is okay for now actually