diff --git a/packages/documentation-site/patternfly-docs/content/developer-resources/cli-guidelines.md b/packages/documentation-site/patternfly-docs/content/developer-resources/cli-guidelines.md new file mode 100644 index 0000000000..ee1c0bf24a --- /dev/null +++ b/packages/documentation-site/patternfly-docs/content/developer-resources/cli-guidelines.md @@ -0,0 +1,163 @@ +--- +id: CLI handbook +title: Command-line interface handbook +source: overview +section: developer-resources +--- + +# Designing for command-line interfaces + +Our CLI handbook offers best practices for designing consistent, usable, and developer-friendly command-line interfaces (CLIs). It supports developers building CLI tools and designers collaborating on technical products. These guidelines are particularly helpful for environments where CLI tools are the primary or critical part of the user experience, emphasizing clarity, structure, and user-centered design across command syntax, help documentation, error messaging, and interactive behaviors. + +## Accessibility considerations + +While CLIs don't have visual UI elements, many [accessibility principles](/accessibility/about-accessibility/) still apply. + +Accessibility matters in CLI design just as much as it does in graphical interfaces. Clear, inclusive output ensures all users can successfully interact with the tool—including those using screen readers or alternative input devices. + +To ensure a CLI's accessibility, adhere to the following additional color, content, and testing practices. + +### Color + +
+ +| **Don't** | **Do** | +| --- | --- | +| Don’t convey meaning through color alone. | Do use text alongside color-based cues. For example, “Success” and “Error” labels. | +| | Do use text alongside red/green indicators, to make the information accessible to colorblind users. | + +
+ +### Content + +
+ +| **Don't** | **Do** | +| --- | --- | +| Don't use vague terms like “it failed”.| Do be direct and transparent with descriptive, specific language. | +| Don’t assume users can infer meaning from context alone.| Do use descriptive text for prompts and feedback. | +| Don't use prompt flows that require visual scanning without clear text guidance. | Do ensure all commands and prompts are keyboard-accessible and non-interactive-safe.

Do use flags like `--non-interactive` for scripting or assistive tech users. | +| Don't use overly styled ASCII tables, long walls of text, or dynamic animations. | Do use plain, structured output that screen readers can parse.

Do use clean, labeled output with headings, bullet points, or clear separators. | +
+ +### Testing + +
+ +| **Don't** | **Do** | +| --- | --- | +| Don't assume that your design is accessible. | Do test with screen readers and colorblind simulators to reveal subtle issues in contrast, clarity, and verbosity. | +
+ +### Example + +Accessible: + +```plaintext +✅ Deployment successful. +Run `tool status` to check environment health. +``` + +Less accessible: + +```plaintext +✅ You did it! +``` + +## CLI inputs + +To write effectively for CLIs, it is important to understand the different elements of CLI inputs: +1. **[Command name:](#command-names)** Identifies the action a command will perform and the subject that the action applies to. +1. **[Arguments:](#arguments)** Additional details used alongside the command name, which users select to specify the way that a command is applied. +1. **[Flags:](#flags)** Named parameters that modify the behavior of the command. + +### Commands + +A command describes the action triggered by the CLI. + +Command names should consistently use a verb-noun structure: +- **Verb:** The action performed. +- **Noun:** The resource or object affected. + +This structure mirrors how people think about tasks, making commands more intuitive and discoverable. The verb-noun format also aligns with widely-used CLIs like `git`, `kubectl`, and `docker`. In contrast, noun-verb structures can be harder to parse and don't scale well. + +#### Example + +In the following code block, `create project`, `delete environment`, and `scale deployment` are all commands. + +```bash +tool create project +tool delete environment +tool scale deployment +``` + +### Arguments + +Arguments are non-flag values following a command, typically unique identifiers like file paths or project names. + +A command requires an argument in order to execute. While multiple arguments can be used, their order matters. Fewer arguments are preferable to support easier recall and avoid confusion. + +#### Example + +In the following code block, `delete project` and `deploy environment` are commands, while `my-app` and `production` are arguments that represent the object being acted on. + +```bash +tool delete project my-app +tool deploy environment production +``` + +### Flags + +Flags are named parameters, prefixed with 2 hyphens (--), that modify the behavior of a command. They allow users to specify command modifiers, options, or other non-essential configuration. Flags can be added in any order. + +#### Example + +In the following code block, `--env`, `--force`, `--role`, and `--email` are flags. + +```bash +tool deploy --env staging --force +tool create user --role admin --email user@Examples:.com +``` + +#### Long-form and short-form + +There are 2 forms for flags: + +1. **Long-form flags:** More descriptive and clear. + + ```bash + tool deploy app --enable-autoscaling + tool configure user --assign-admin-privileges + tool update cluster --set-min-replicas 3 + ``` +1. **Short-form flags:** More concise, with 1-2 letters. + + - Reserve for frequently-used options. This benefits experienced users who prefer speed and situations with limited space. + - When possible, pair with long-form equivalents for better clarity and discoverability. + + ```bash + tool --help # Long-form + tool -h # Short-form (Help) + + tool --verbose # Long-form + tool -v # Short-form (Verbose) + + tool --config path/to/file + tool -c path/to/file # Short-form (Config file path) + ``` + +#### Types of flags + +1. **Boolean flags:** Represent on/off or true/false options. + + - Set a sensible default. + - Don’t require explicit values unless necessary. For example, allow `--force` rather than `--force=true`. + + ```bash + tool deploy --dry-run # Runs without executing + tool delete --force # Skips confirmation prompt + ``` + +2. **Help flags:** Provide help documentation that explains a command's purpose, its arguments/flags, and usage examples. + + - Offer both long `--help` and short `-h` options. \ No newline at end of file diff --git a/packages/documentation-site/patternfly-docs/content/developer-resources/cli-writing.md b/packages/documentation-site/patternfly-docs/content/developer-resources/cli-writing.md new file mode 100644 index 0000000000..d9c2fde04f --- /dev/null +++ b/packages/documentation-site/patternfly-docs/content/developer-resources/cli-writing.md @@ -0,0 +1,274 @@ +--- +id: CLI handbook +title: Command-line interface handbook +source: writing-guidelines +section: developer-resources +--- + +## CLI outputs + +CLI output messages typically fall into one of 3 categories: + +| Category | Usage | Example | +| --- | --- | --- | +| Success | Completed actions. | `✅ Dataset uploaded successfully.` | +| Warning | Completed actions that require review. | `⚠️ Model trained, but validation accuracy is low.` | +| Error | Failed actions. | `❌ Error: Cannot connect to remote service. Check your network connection or try again with --offline mode.` | + +### Success messages + +To build trust, reinforce that a command worked as intended, and guide users toward their next step, clearly communicate successful actions. + +#### Example + +```plaintext +✅ Project "my-app" deployed successfully. + +Next steps: +- Run `tool status my-app` to check deployment health +- Run `tool logs my-app` to view runtime output +``` + +### Error messages + +When errors occur, explain what happened, why, and how to fix it. + +Expanding on our [UI error writing guidelines](/ux-writing/error-messages), CLI errors should: +- Use plain language, avoiding internal jargon. +- Offer suggestions and actionable next steps. +- Conclude with the most important information. This is the opposite of content design for products with GUIs. +- By default, provide a clean message. Full stack traces or internal logs should only be exposed via debug flags (like `--debug` or `--trace`). + +#### Examples + +1. Generic failure with correction: + ```plaintext + ❌ Error: Cannot connect to remote service. + Check your network connection or try again with `--offline` mode. + ``` + +1. File permission issue: + ```plaintext + ❌ Error: Unable to write to file.txt + You may need to change the file’s permissions or run the command with elevated privileges. + ``` + +1. Command syntax error: + ```plaintext + ❌ Error: Unrecognized flag --versoin + Did you mean: --version ? + ``` + +### Output patterns + +#### Formatting + +To ensure that output is readable: +1. Structure large outputs: + - Use spacing, dividers, indentation, or table/column formats to break up large blocks and avoid unstructured text. + - Ensure consistent headers or labels for repeated information (like results or summaries). +2. Manage lists effectively: + - Structure lists for easy scanning—including software versions, resources, or deployment options. + - Display the most relevant or default item first (like the current version) and clearly label it with "Yes" or "*". + - [Paginate](#pagination) lists that exceed 5–7 items. + +#### Version listing + +When listing version information: +- Arrange versions top-down from newest to oldest. +- Clearly mark the current default. +- Display upgrade paths beside each item. + +##### Example + +```plaintext +Available Versions +- +VERSION DEFAULT AVAILABLE UPGRADES +1.4.3 Yes 1.4.4, 1.4.5, 1.5.0 +1.3.9 1.4.0, 1.4.1 +1.3.8 1.3.9 +``` + +#### Pagination + +Paginate long lists into 5–7 item pages, prompting users to continue with `--more`, `--page`, by pressing the **Enter** key. + +##### Example + +```bash +tool versions list --limit 5 +tool resources list --page 2 +``` + +#### Sorting and filtering + +To help users make sense of large CLI outputs, provide sorting and filtering options: +Default to sorting by relevance or recency.- +- Offer flags like `--sort`, `--filter`, or `--status` for flexible control. +- Ensure the default view serves most users without requiring flags for basic usability. + +## Help documentation + +CLIs must provide accessible in-application help. To ensure its relevance, write from a new user's perspective: would they immediately know what to do? + +Effective help documentation is: +- Brief yet meaningful. +- Clear, avoiding unexplained jargon or acronyms. +- Consistent across all commands. +- Referenced in [interactive prompts](#interactive-mode) (via `--help`) if supported. + +### Writing help output + +Structure help output consistently with these elements: +- **Description:** Plain language explanation of the command’s function. +- **Usage:** Command syntax, including required arguments and flags. +- **Examples:** At least 1 clear, real-world usage scenario. +- **Flags:** List of available options with brief, actionable descriptions. +- **Documentation link (optional):** For further details. + +#### Example + +```bash +Usage: + tool deploy [flags] + +Description: + Deploys the specified project to your active environment. + +Examples: + tool deploy my-app --env staging + +Flags: + -e, --env string Environment to deploy to + -f, --force Force deployment even if conflicts exist + -h, --help Show help for the deploy command + +For more information, visit: https://Examples:.com/docs/deploy +``` + +### Documenting flags +Well-documented flags improve discoverability, reduce user error, and make it easier for contributors and users to understand the CLI’s capabilities. + +Document flags clearly in: +- A command's `--help` output. +- Official CLI documentation or reference guides. +- Interactive prompt hints (if applicable). + +#### Best practices +- Use descriptive names that clearly indicate the flag’s purpose. Avoid ambiguous names like `--flag1`. +- Document the input type (such as string, boolean, or int). +- Show any default value. +- Mention if the flag is optional or required. + +Flag documentation should generally follow this format: + +```plaintext +--flag-name Description of what this flag does (default: value) +``` + +##### Example + +```plaintext +Flags: + -n, --name string Name of the project to create + -e, --env string Target environment (e.g., staging, prod) + -f, --force Skip confirmation prompts (default: false) + -o, --output string Output format: json, yaml, or table (default: table) + -h, --help Show help for this command +``` + +For boolean flags that act as switches (true/false): +- Typically default to `false`. +- Don't require an explicit value (for example, use `--force`, not `--force=true`). +- Clearly state what enabling the flag does. +- When possible, explain the flag's effect or common use cases: + + ```plaintext + --dry-run Simulate the command without making changes. Useful for validation or preview. + --watch Continuously stream status updates until completion. + ``` + +## Interactive mode + +Interactive mode guides users step-by-step with prompts, commonly for setup wizards, configuration flows, or complex inputs not suited for single commands. + +### When to use interactive mode + +User interactive mode for: +- Setup or initialization wizards. +- Optional configuration flows. +- Profile or environment selection. + +### When not to use interactive mode + +Do not use interactive mode for: +- Simple one-off tasks. +- Repetitive actions, such as run, delete, status. +- Automated commands, such as in CI/CD pipelines. +- Essential inputs that could be passed as flags. + +### Writing interactive prompts + +When designing interactive prompts, prioritize flags for essential inputs and use prompts primarily for optional choices or guided multi-step processes. + +Key considerations include: + +#### Default values +Choose defaults based on common use cases or sensible fallbacks. + +- Make defaults obvious—don't hide them in help text or assume user knowledge. +- Visually indicate defaults clearly (such as `[default]`, `(default)` or `(Y/n)`/`(y/N)`). +- If using a list, ensure a first-item default is genuinely the most common choice. +- Explain that pressing **Enter** accepts the default (if the input is left blank). +- Confirm (log or echo) the selected value after the prompt, even if it was the default. + +#### Clarity + +Ensure prompts are as clear as possible. + +- Phrase prompts as questions. + - For example: "Enable autoscaling? (Y/n)" +- Clearly state if responding to a prompt is optional. +- Offer inline help where useful. + - For example: "Output directory [? for help]" +- Avoid chaining an excessive number of prompts. +- Include optional next steps when appropriate (like view status, open logs). +- Avoid silent success unless explicitly requested (like in `--quiet` mode). + +#### User control + +Empower users with control over their CLI experience. + +- Consider using a `--guided` flag to let users intentionally trigger multi-step interactive flows. +- Let users bypass prompts with a `--non-interactive` or `--yes` flag. +- Allow users to cancel or exit flows early with **Ctrl+C** or a similar command. + +### Example + +```plaintext +Welcome! Let's configure your project. + +Project name: my-app +Language (js, py, go) [py]: +Use Docker? (y/N): y + +✅ Project "my-app" configured successfully. +``` + +```plaintext +Choose deployment region: +[1] US East (N. Virginia) +[2] US West (Oregon) (default) +[3] Europe (Frankfurt) + +Enable telemetry? (y/N) +``` + +```plaintext +Select output format (default = 'json') [Use arrows to move, type to filter, ? for help]: +``` + + + +