From 6df0818c8d5fbe0550d4a4e16561a2c34ef09ad0 Mon Sep 17 00:00:00 2001 From: Erin Donehoo Date: Fri, 2 May 2025 16:11:47 -0400 Subject: [PATCH 1/5] docs(CLI-handbook): Content review and edits. --- .../developer-resources/cli-guidelines.md | 522 +++--------------- .../developer-resources/cli-writing.md | 296 ++++++++++ 2 files changed, 369 insertions(+), 449 deletions(-) create mode 100644 packages/documentation-site/patternfly-docs/content/developer-resources/cli-writing.md 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 index 23bb71cdda..d9c5c1c54f 100644 --- a/packages/documentation-site/patternfly-docs/content/developer-resources/cli-guidelines.md +++ b/packages/documentation-site/patternfly-docs/content/developer-resources/cli-guidelines.md @@ -1,42 +1,48 @@ --- -id: CLI Guidelines -title: Command Line Interface Guidelines +id: CLI handbook +title: Command-line interface handbook +source: overview section: developer-resources --- -## Overview +# Designing for command-line interfaces -This document provides best practices and UX guidelines for designing consistent, usable, and developer-friendly command-line interfaces (CLIs). These principles are intended to support both developers building CLI tooling and UX designers collaborating on technical products. +This resource provides best practices and guidelines for designing consistent, usable, and developer-friendly command-line interfaces (CLIs). These principles are intended to support both developers building CLI tooling and designers collaborating on technical products. These guidelines emphasize clarity, structure, and user-centered design across command syntax, help documentation, error messaging, and interactive behaviors. While they are applicable to a wide range of use cases, they are particularly helpful for teams working in environments where CLI tools serve as the primary or critical part of the user experience. ## Accessibility considerations -Accessibility matters in CLI design just as much as it does in graphical interfaces. Clear, inclusive output ensures all users — including those using screen readers or alternative input devices — can successfully interact with the tool. +While CLIs don't have visual UI elements, many [accessibility principles](/accessibility/about-accessibility/) still apply. -While CLIs don't have visual UI elements, many accessibility principles still apply. +Accessibility matters in CLI design just as much as it does in graphical interfaces. Clear, inclusive output ensures all users—including those using screen readers or alternative input devices—can successfully interact with the tool. -### Best Practices +### Color -- Don’t rely on **color alone** to convey meaning - - Use text alongside color-based cues (e.g., “Success”, “Error” labels) - - Avoid red/green-only indicators that may be difficult for colorblind users +| **Don't** | **Do** | +|--------|-----------| +| Don’t rely on color alone to convey meaning. | Do use text alongside color-based cues (such as “Success” and “Error” labels).

Do use text alongside red/green indicators, to make the information accessible to colorblind users. | -- Use **descriptive text** for prompts and feedback - - Don’t assume users can infer meaning from context alone - - Avoid vague terms like “it failed” — be specific +### Content -- Ensure all commands and prompts are **keyboard-accessible and non-interactive-safe** - - Use flags like `--non-interactive` for scripting or assistive tech users - - Avoid prompt flows that require visual scanning without clear text guidance +| **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. | -- Use **plain, structured output** that screen readers can parse - - Avoid overly styled ASCII tables, long walls of text, or dynamic animations - - Prefer clean, labeled output with headings, bullet points, or clear separators +### Testing -### Examples: +It is important to test your output through accessibility tools to reveal subtle issues in contrast, clarity, and verbosity. -**Good:** +| **Don't** | **Do** | +|--------|-----------| +| Don't assume that your design is accessible. | Do test with screen readers and colorblind simulators. | + +### Example + +**Accessible:** ```plaintext ✅ Deployment successful. Run `tool status` to check environment health. @@ -46,21 +52,25 @@ Run `tool status` to check environment health. ```plaintext ✅ You did it! ``` -**Tip:** Test with screen readers and colorblind simulators -Even though CLIs aren’t GUIs, testing your output through accessibility tools can reveal subtle issues in contrast, clarity, and verbosity — all of which can affect user experience. -## Naming conventions +## CLI inputs + +CLI inputs are composed of a few parts: +- [Command name:](#command-names) Identifies the action a command will perform and the subject that the action applies to. +- [Arguments:](#arguments) Additional details used alongside the command name, which users select to specify the way that a command is applied. +- [Flags:](#flags) Named parameters that modify the behavior of the command. -Command names should follow a clear and consistent **verb-noun** structure. This convention improves readability, reinforces expected behavior, and aligns with common patterns seen in widely-used CLIs like `git`, `kubectl`, and `docker`. +### Commands -- **Verb**: Describes the action the command performs. -- **Noun**: Identifies the resource or object the action applies to. +A **command** describes the action that the CLI will trigger. -### Why verb-noun? +Command names should follow a clear and consistent verb-noun structure: +- Verb: The action the command performs. +- Noun*: The resource or object the action applies to. -Verb-noun commands mirror how people think about tasks: _"create a project"_, _"delete a user"_, _"list models"_. This makes the command more intuitive and easier to discover or guess. In contrast, **noun-verb** structures (e.g., `project create`) can be harder to parse and don't scale well as command options grow. +Verb-noun commands mirror how people think about tasks, which makes the command more intuitive and easier for users to discover or guess. Noun-verb structures can be harder to parse and don't scale well. The verb-noun format also aligns with common patterns seen in widely-used CLIs like `git`, `kubectl`, and `docker`. -### Examples: + ```bash tool create project @@ -68,66 +78,45 @@ tool delete environment tool scale deployment ``` -## Inputs: Flags vs Arguments -_choosing between positional arguments vs flags_ +`create project`, `delete environment`, and `scale deployment` are all commands. -Command-line inputs come in two main forms: +### Arguments -- **Arguments** – Positional inputs that are required and order-dependent -- **Flags** – Named inputs (using `-` or `--`) that modify behavior or provide optional parameters +An argument is anything to the right of a command that is not a flag. Often, they will be file paths, project names, or similar unique identifiers. -### Arguments +A command requires an argument in order to execute. There can be multiple arguments in a command, but the order of arguments matters. It is better to use fewer arguments when possible, to make it easier for users to remember and avoid confusion. -Use arguments for required, primary inputs that define the core action. Because arguments are positional, their order matters and should be kept minimal to avoid confusion. -**Examples:** -- my-app and production are arguments -- They represent the main object being acted on ```bash tool delete project my-app tool deploy environment production ``` +`delete project` and `deploy environment` are commands, while `my-app` and `production` are arguments that represent the object being acted on. + ### Flags -Use flags for optional or named inputs, especially when: -- Order should not matter -- The input is not required -- It's important to clarify intent with a label -**Examples:** +Flags are named parameters 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. + + + ```bash tool deploy --env staging --force tool create user --role admin --email user@Examples:.com ``` -These flags: -- Can appear in any order -- Make the command easier to understand and script -- Support long-form and short-form (--env / -e) -### Guidelines -- ✅ Use arguments for required, unique inputs (e.g., a file path, project name) -- ✅ Use flags for modifiers, options, or non-essential configuration -- ❌ Don’t use too many arguments — it becomes hard to parse and remember -- ✅ Document expected input types (e.g., string, int, boolean) for all flags +#### Forms -## Flags and options -_when and why to use long/short/boolean_ +There are 2 forms for flags: -Flags are named parameters that modify the behavior of a command. They provide flexibility, improve clarity, and allow users to specify input in a structured way. +##### 1. Long-form flags -There are two main types of flags: -- **Long-form flags**: More descriptive, ideal for clarity and scripting. -- **Short-form flags**: Concise, best for highly-used commands or power users. +Long-form flags are clearer and more descriptive. -### Long-Form Flags +They are written with 2 hyphens (--) and a descriptive name. -Long-form flags use two hyphens and a descriptive name. They should be: -- Clear and self-explanatory -- Easy to read and remember -- Consistent across commands -**Examples:** ```bash tool deploy app --enable-autoscaling @@ -135,16 +124,15 @@ tool configure user --assign-admin-privileges tool update cluster --set-min-replicas 3 ``` -### Short-Form Flags +##### 1. Short-form flags -Short-form flags use a single hyphen followed by one or two letters. They’re useful for: -- Frequently used options -- Experienced users who prefer speed -- Situations where space or typing efficiency matters +Short-form flags are more concise than long-form flags. They are and are particularly useful frequently used options, experienced users who prefer speed, and situations where space or typing efficiency matters. +They are written with a single hyphen (-) followed by 1 or 2 letters. + When possible, pair short-form flags with long-form equivalents for clarity and discoverability. -**Examples:** + ```bash tool --help # Long-form @@ -157,385 +145,21 @@ tool --config path/to/file tool -c path/to/file # Short-form (Config file path) ``` -### Boolean Flags -Boolean flags represent on/off or true/false options. If possible: -- Set a sensible default (e.g., false) -- Don’t require users to pass an explicit value unless necessary - -**Examples:** -```bash -tool deploy --dry-run # Runs without executing -tool delete --force # Skips confirmation prompt -``` - -## Help flags and documentation - -Every CLI should provide structured, easy-to-access help output that explains: -- What a command does -- What arguments or flags it accepts -- How to use it, with clear Examples: - -### Standard Help Flags - -Provide both a long and short help flag: -- `--help` for discoverability and scripting -- `-h` for quick access - -### Help Output Structure -Help output should be consistent across commands and follow a clear structure: - -1. Description – What the command does in plain language -2. Usage – Syntax with required arguments and flags -3. Examples: – At least one clear, real-world usage Examples: -4. Flags – A list of available options with brief, actionable descriptions -5. Documentation Link (optional) – If more detail exists elsewhere - -**Examples: Help Output** -```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 -``` - -### Best Practices -- Keep help text brief but meaningful -- Avoid internal jargon and acronyms without explanation -- Ensure consistency across all commands -- If your CLI supports interactive prompts, reference --help in the prompt (e.g., Type ? or --help for more info) - - -## Documenting flags -_how to write about flags in --help and docs_ - -Well-documented flags improve discoverability, reduce user error, and make it easier for contributors and users alike to understand the CLI’s capabilities. - -Clear flag documentation should be included in: -- `--help` output for the command -- Official CLI documentation or reference guides -- Interactive prompt hints (if applicable) - -### Best Practices - -- Use **descriptive names** that clearly indicate the flag’s purpose -- Document the **flag’s input type** (string, boolean, int, etc.) -- Show the **default value** if one exists -- Mention whether the flag is optional or required -- Avoid vague or ambiguous flag names (e.g., `--flag1`, `--optionX`) - -### Recommended Flag Format - -In help text and documentation, each flag should show: - -```plaintext ---flag-name Description of what this flag does (default: value) -``` - -**Examples: Flags Documentation:** -```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 -``` - -### Boolean Flags -For flags that act as switches (true/false): -- Default to false unless enabled -- Do not require an explicit value (i.e., use --force, not --force=true) -- Clearly state what enabling the flag does - -**Tip:** Include usage context -When possible, explain how the flag affects the command’s behavior or when it’s most useful: - -```plaintext ---dry-run Simulate the command without making changes. Useful for validation or preview. ---watch Continuously stream status updates until completion. -``` -By documenting flags thoroughly and consistently, you create a better experience for users and contributors alike — reducing friction, guesswork, and onboarding time. - -**Tip:** Think like a user -- Ask: “If I saw this message for the first time, would I know what to do?” -- Avoid hidden meanings, technical slang, or filler words -- Be intentional with every line of output — it’s the primary UX for many CLI tools - -## Interactive prompts - -Interactive prompts guide users through a process step-by-step. They’re commonly used for setup wizards, configuration flows, or when input is too complex to pass in a single command. - -When designed well, prompts can reduce friction and help users make informed decisions — especially during onboarding or first use. But when overused or inconsistent, they can frustrate users or become blockers in automated workflows. - -### Best Practices - -- Use prompts for guided setup, not quick or repeatable tasks -- Let users bypass prompts with a `--non-interactive` or `--yes` flag -- Clearly show default values and how to accept them -- Offer inline help (e.g., `? for help`) -- Don’t require prompts for essential inputs that could be passed as flags - -### Examples: Prompt Flow - -```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. -``` - -### Prompt design tips -- Use question-style phrasing -Good: Enable autoscaling? (Y/n) -Avoid: Autoscaling enabled: -- Offer help inline -Output directory [? for help]: -- Be explicit about defaults -Framework (React/Vue) [React]: clearly shows what happens on Enter -- Avoid chaining too many prompts -Consider using a --guided flag to trigger multi-step flows intentionally - -### Exit and Escape options -Always allow users to: -- Cancel with Ctrl+C -- Exit early from multi-step flows -= Provide equivalent flags to bypass promots - -```bash -tool init --name my-app --language js --use-docker -``` - -### When to use interactive mode -- Recommended: --- Setup or initialization wizards --- Optional configuration flows --- Profile or environment selection - -- Avoid: --- Simple one-off tasks --- Repetitive actions (e.g., run, delete, status) --- Commands that will be run in automation, CI, or pipelines - -## Handling default values in prompts - -When users are presented with a list of options in an interactive prompt, it’s important to clearly indicate which choice will be selected by default — especially if the user simply presses Enter. - -Default values provide helpful guidance, but unclear or unintentional defaults can cause confusion, errors, or misconfiguration. - -### Best Practices - -- Always indicate the default value in a clear, visual way -- Choose defaults based on common use cases or sensible fallbacks -- Avoid making the **first item** the default unless it is truly the most likely choice -- Don’t hide defaults in help text or assume the user knows them - -### Ways to Display Defaults - -Use a consistent format to indicate which option will be used by default: - -- Brackets: `[default]` -- Parentheses: `(default)` -- Yes/No conventions: `(Y/n)` or `(y/N)` depending on which is default - -**Examples:** - -```plaintext -Choose deployment region: -[1] US East (N. Virginia) -[2] US West (Oregon) (default) -[3] Europe (Frankfurt) - -Enable telemetry? (y/N) -``` - -### Optional vs. Default Inputs -Clarify whether a prompt is: -- Optional: User can skip it entirely -- Has a Default: Will proceed with a pre-set value if left blank -*Tip*: Use inline notes to explain default behavior, especially in longer flows. - -```plaintext -Select output format (default = 'json') [Use arrows to move, type to filter, ? for help]: -``` - -### Implementation Tips -- Inform users that pressing Enter will accept the default -- If using interactive libraries, make sure default selections are pre-highlighted or noted in the prompt -- Log or echo the selected value for confirmation (even if it was a default) - -**Examples: Output:** - -```plaintext -OIDC Configuration ID (default = 'abc123xyz'): -✅ Using default: abc123xyz -``` - -By handling defaults clearly and consistently, you reduce friction, increase trust, and create a better user experience across interactive and scripted workflows. - - -## Error messaging and corrections - -When something goes wrong, the CLI should help users understand: -- What happened -- Why it happened -- How to fix it - -Error messages are a core part of the user experience. They should be written in plain language, not internal jargon, and provide actionable next steps. - -### Best Practices - -- ✅ Make error messages human-readable -- ❌ Avoid stack traces unless a debug flag is enabled -- ✅ Place the most important information at the end (where scanning starts) -- ✅ Suggest solutions whenever possible - -### Examples: - -**Generic failure with correction:** - -```plaintext -❌ Error: Cannot connect to remote service. -Check your network connection or try again with `--offline` mode. -``` - -**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. -``` - -**Command syntax error** -```plaintext -❌ Error: Unrecognized flag --versoin -Did you mean: --version ? -``` - -### Auto-correction and suggestions -Where appropriate, CLIs may offer suggestions or corrections for common typos: - -```plaintext -❌ Error: Unknown command “initaite” -Did you mean: “initiate”? -``` - -### Debugging information -For unexpected or low-level errors: -- Provide a clean message by default -- Use --debug or --trace flags to expose full stack traces or internal logs - -```plaintext -❌ Unexpected error: Operation timed out. -Run with --debug for more details. -``` - -## Feedback and output formatting - -CLIs should clearly communicate when an action completes successfully. This builds trust, reinforces that a command worked as intended, and helps guide users toward their next step. - -### Best Practices - -- ✅ Confirm successful actions with a short, clear message -- ✅ Use consistent formatting, symbols, or icons for different message types -- ✅ Include optional next steps when appropriate (e.g., view status, open logs) -- ❌ Avoid silent success unless explicitly requested (e.g., in `--quiet` mode) - -### Message Types and Symbols - -- **Success**: Action completed - `✅ Dataset uploaded successfully.` - -- **Warning**: Action completed but with something to review - `⚠️ Model trained, but validation accuracy is low.` - -- ❌ **Error**: Something failed (covered in previous section) - -### Examples: Output Patterns - -```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 -``` - -### Structuring output for readability -- Use spacing, dividers, or indentation to break up large blocks of output. -- Use consistent headers or labels for repeated outputs (e.g., listing results or summaries). - -```plaintext -Results: - -✓ 12 files processed -✓ 2 files skipped (already up to date) -✓ 1 warning: Unused flag --optimize -``` - -## Version listing and pagination - -When your CLI displays lists of items — such as software versions, available resources, or deployment options — it should be structured for easy scanning and include guidance when the list becomes long. - -Pagination and sensible ordering improve readability and reduce cognitive overload, especially when the output may exceed the visible terminal window. - -### Best Practices - -- **Show the most relevant or default item first** (e.g., the currently installed version) -- **Clearly label the default or active item** (e.g., with a "Yes" or "*") -- **Paginate output when the list exceeds 5–7 items** -- **Use table formatting or columns for consistency** -- Avoid dumping unstructured text or long, scrollable blobs - -### Examples:: Version Listing Output - -```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 -``` -- Versions are ordered top-down from newest to oldest -- The current default is clearly marked -- Upgrade paths are shown next to each item - -### Pagination tips -For long lists: -- Break into pages of 5–7 items at a time -- Prompt the user with --more, --page, or allow Enter to continue - -**Examples:** -```bash -tool versions list --limit 5 -tool resources list --page 2 -``` - -### Sorting and Filtering -- Default sort should be by relevance or recency (e.g., newest version first) -- Offer flags like --sort, --filter, or --status for flexible output -- Make sure the default view meets the needs of most users — avoid requiring flags to make output usable - +#### Types -## Final thoughts +1. Boolean flags: Represent on/off or true/false options. -These CLI UX guidelines are intended to create a more consistent, thoughtful experience for users — whether they’re interacting through interactive prompts, automation scripts, or help commands. + - Set a sensible default. + - Don’t require users to pass an explicit value unless necessary. -As command-line tools continue to play a growing role in infrastructure, AI, and automation workflows, applying good design practices is more important than ever. + ```bash + tool deploy --dry-run # Runs without executing + tool delete --force # Skips confirmation prompt + ``` -This document is a starting point. Contributions and improvements are welcome as CLI patterns evolve and as we learn more from user feedback and real-world use. +2. Help flags: Allow users to receive help and load additional documentation that explains: + - What a command does. + - What arguments or flags it accepts. + - How to use it, with clear examples. -Together, we can build tooling that’s not only powerful — but intuitive, inclusive, and a pleasure to use. + Users should be able to use both a long (`--help` ) and short help (`-h`) flag. \ 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..e526d2b181 --- /dev/null +++ b/packages/documentation-site/patternfly-docs/content/developer-resources/cli-writing.md @@ -0,0 +1,296 @@ +--- +id: CLI handbook +title: Command-line interface handbook +source: writing-guidelines +section: developer-resources +--- + +## Help documentation + +Users must have access to help within a CLI. + +When writing help documentation: +- Keep help text brief but meaningful. +- Avoid internal jargon and acronyms without explanation. +- Ensure consistency across all commands. +- If your CLI supports [interactive prompts](#interactive-prompts), reference `--help` in the prompt. + +**Tip:** Think like a user +- Ask: “If I saw this message for the first time, would I know what to do?” +- Avoid hidden meanings, technical slang, or filler words +- Be intentional with every line of output — it’s the primary UX for many CLI tools + +### Writing help output +Help output should be consistent across commands and follow a clear structure: +1. Description: What the command does in plain language. +2. Usage: Syntax with required arguments and flags. +3. Examples: At least 1 clear, real-world usage example. +4. Flags: A list of available options with brief, actionable descriptions. +5. Documentation link (optional): If more detail exists elsewhere. + +```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 +``` + +### Flag documentation +Well-documented flags improve discoverability, reduce user error, and make it easier for contributors and users to understand the CLI’s capabilities. + +Clear flag documentation should be included in: +- `--help` output for the command. +- Official CLI documentation or reference guides. +- Interactive prompt hints (if applicable). + +Flag documentation should show the following: + +```plaintext +--flag-name Description of what this flag does (default: value) +``` + +```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): +- Default to false unless enabled. +- Do not require an explicit value (for example, use `--force`, not `--force=true`). +- Clearly state what enabling the flag does. +- When possible, explain how the flag affects the command’s behavior or when it’s most useful: + +```plaintext +--dry-run Simulate the command without making changes. Useful for validation or preview. +--watch Continuously stream status updates until completion. +``` + +#### Best practices +- Use **descriptive names** that clearly indicate the flag’s purpose. +- Document the **flag’s input type** (string, boolean, int, and so on). +- Show the **default value** if one exists. +- Mention whether the flag is optional or required. +- Avoid vague or ambiguous flag names (like `--flag1`, `--optionX`). + +## Interactive prompts + +Interactive prompts guide users through a process step-by-step. They’re commonly used for setup wizards, configuration flows, or when input is too complex to pass in a single command. + + +### When to use interactive mode +- Recommended: +-- Setup or initialization wizards +-- Optional configuration flows +-- Profile or environment selection + +- Avoid: +-- Simple one-off tasks +-- Repetitive actions (e.g., run, delete, status) +-- Commands that will be run in automation, CI, or pipelines + +### Best Practices + +- Use prompts for guided setup, not quick or repeatable tasks. +- Let users bypass prompts with a `--non-interactive` or `--yes` flag. +- Clearly show default values and how to accept them. +- Offer inline help (fore example "? for help"). +- Don’t require prompts for essential inputs that could be passed as flags. + +```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]: +``` + +### Writing interactive prompts + +When writing interactive prompts, follow these best practices: + +#### Default values: + +Choose defaults based on common use cases or sensible fallbacks. + - Tell users that pressing Enter will accept the default andwWill proceed with a pre-set value if left blank. + - Always indicate the default value in a clear, visual way. For example, `[default]`, `(default)` or `(Y/n)`/`(y/N)`. + - Avoid making the first item the default unless it is truly the most likely choice. + - Don’t hide defaults in help text or assume the user knows them. + - Log or echo the selected value for confirmation (even if it was a default). + +#### Clarity: + - Use question-style phrasing, such as "Enable autoscaling? (Y/n)". + - Be clear if a prompt is optional. + - Offer help inline, such as "Output directory [? for help]". + - Avoid chaining too many prompts. + - CLIs should clearly communicate when an action completes successfully. + - Confirm successful actions with a short, clear message +- Use consistent formatting, symbols, or icons for different message types +- Include optional next steps when appropriate (e.g., view status, open logs) +- Avoid silent success unless explicitly requested (e.g., in `--quiet` mode) + +#### User control: + - Cancel with Ctrl+C + - Provide equivalent flags to bypass prompts + +#### Multi-step flows: + - Consider using a `--guided` flag to trigger multi-step flows intentionally. + - Allow users to exit early if needed. + +#### Error messaging and corrections + +When something goes wrong, the CLI should help users understand: +- What happened +- Why it happened +- How to fix it + +Error messages are a core part of the user experience. They should be written in plain language, not internal jargon, and provide actionable next steps. + + +- Make error messages human-readable +- Avoid stack traces unless a debug flag is enabled +- Place the most important information at the end (where scanning starts) +- Suggest solutions whenever possible + +**Generic failure with correction:** + +```plaintext +❌ Error: Cannot connect to remote service. +Check your network connection or try again with `--offline` mode. +``` + +**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. +``` + +**Command syntax error** +```plaintext +❌ Error: Unrecognized flag --versoin +Did you mean: --version ? +``` + +### Auto-correction and suggestions +Where appropriate, CLIs may offer suggestions or corrections for common typos: + +```plaintext +❌ Error: Unknown command “initaite” +Did you mean: “initiate”? +``` + +### Debugging information +For unexpected or low-level errors: +- Provide a clean message by default +- Use --debug or --trace flags to expose full stack traces or internal logs + +```plaintext +❌ Unexpected error: Operation timed out. +Run with --debug for more details. +``` + +## Output patterns + +- **Success**: Action completed + `✅ Dataset uploaded successfully.` + +- **Warning**: Action completed but with something to review + `⚠️ Model trained, but validation accuracy is low.` + +- ❌ **Error**: Something failed (covered in previous section) + +### Examples: Output Patterns + +```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 +``` + +### Structuring output for readability +- Use spacing, dividers, or indentation to break up large blocks of output. +- Use consistent headers or labels for repeated outputs (e.g., listing results or summaries). + +```plaintext +Results: + +✓ 12 files processed +✓ 2 files skipped (already up to date) +✓ 1 warning: Unused flag --optimize +``` + +### Version listing and pagination + +When your CLI displays lists of items — such as software versions, available resources, or deployment options — it should be structured for easy scanning and include guidance when the list becomes long. + +Pagination and sensible ordering improve readability and reduce cognitive overload, especially when the output may exceed the visible terminal window. + +### Best Practices + +- **Show the most relevant or default item first** (e.g., the currently installed version) +- **Clearly label the default or active item** (e.g., with a "Yes" or "*") +- **Paginate output when the list exceeds 5–7 items** +- **Use table formatting or columns for consistency** +- Avoid dumping unstructured text or long, scrollable blobs + +### Examples:: Version Listing Output + +```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 +``` +- Versions are ordered top-down from newest to oldest +- The current default is clearly marked +- Upgrade paths are shown next to each item + +### Pagination tips +For long lists: +- Break into pages of 5–7 items at a time +- Prompt the user with --more, --page, or allow Enter to continue + +**Examples:** +```bash +tool versions list --limit 5 +tool resources list --page 2 +``` + +### Sorting and Filtering +- Default sort should be by relevance or recency (e.g., newest version first) +- Offer flags like --sort, --filter, or --status for flexible output +- Make sure the default view meets the needs of most users — avoid requiring flags to make output usable + From 0189a79a9208237e31ffac0a05d57bb52e5928fe Mon Sep 17 00:00:00 2001 From: Erin Donehoo Date: Mon, 5 May 2025 15:37:52 -0400 Subject: [PATCH 2/5] Continues refining. --- .../developer-resources/cli-writing.md | 328 ++++++++---------- 1 file changed, 150 insertions(+), 178 deletions(-) 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 index e526d2b181..1eb3edbe73 100644 --- a/packages/documentation-site/patternfly-docs/content/developer-resources/cli-writing.md +++ b/packages/documentation-site/patternfly-docs/content/developer-resources/cli-writing.md @@ -5,28 +5,119 @@ 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.` | + + +### Output patterns + +#### Formatting + +To ensure that output is readable: + +- Use spacing, dividers, or indentation to break up large blocks of output. +- Use consistent headers or labels for repeated outputs (such as listing results or summaries). +- When your CLI displays lists of items—such as software versions, available resources, or deployment options—it should be structured for easy scanning and include guidance when the list becomes long. +- Show the most relevant or default item first (like the currently installed version). +- Clearly label the default or active item (like with a "Yes" or "*"). +- [Paginate](#pagination) output when the list exceeds 5–7 items. +- Use table formatting or columns for consistency. +- Avoid dumping unstructured text or long, scrollable blobs. + +```plaintext +Results: + +✓ 12 files processed +✓ 2 files skipped (already up to date) +✓ 1 warning: Unused flag --optimize +``` + +#### Success messages + +Clearly communicate when an action completes successfully to build trust, reinforce that a command worked as intended, and guide users toward their next step. + +```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 something goes wrong, help users understand what happened, why it happened, and how to fix it. + +Like with our standard [UI error writing guidelines](/ux-writing/error-messages), CLI errors should: +- Be written in plain language. +- Not use internal jargon. +- Provide suggestions and actionable next steps. +- End with the most important information, rather than lead with it. +- Not display stack traces unless a debug flag is enabled. + +For unexpected or low-level errors: +- Provide a clean message by default. +- Use `--debug` or `--trace` flags to expose full stack traces or internal logs. + +#### 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. + +```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 + +Use pagination to break long lists into pages of 5–7 items at a time. When using pagination, prompt the user with `--more`, `--page`, or allow them to press **Enter** to continue + +```bash +tool versions list --limit 5 +tool resources list --page 2 +``` + +#### Sorting and filtering + +To help users make sense of large CLI output, allow them to sort and filter as needed. When using sorting and filtering: + +- Default sort should be by relevance or recency. +- Offer flags like `--sort`, `--filter`, or `--status` for flexible output. +- Make sure the default view meets the needs of most users and avoid requiring flags to make output usable + ## Help documentation Users must have access to help within a CLI. +When considering the relevance of help documentation, think like a user and ask yourself: “If I saw this message for the first time, would I know what to do?” + When writing help documentation: - Keep help text brief but meaningful. - Avoid internal jargon and acronyms without explanation. - Ensure consistency across all commands. - If your CLI supports [interactive prompts](#interactive-prompts), reference `--help` in the prompt. -**Tip:** Think like a user -- Ask: “If I saw this message for the first time, would I know what to do?” -- Avoid hidden meanings, technical slang, or filler words -- Be intentional with every line of output — it’s the primary UX for many CLI tools - ### Writing help output -Help output should be consistent across commands and follow a clear structure: -1. Description: What the command does in plain language. -2. Usage: Syntax with required arguments and flags. -3. Examples: At least 1 clear, real-world usage example. -4. Flags: A list of available options with brief, actionable descriptions. -5. Documentation link (optional): If more detail exists elsewhere. +Help output should be consistent across commands and follow a clear structure, containing these elements: +- **Description:** What the command does in plain language. +- **Usage:** Syntax with required arguments and flags. +- **Examples:** At least 1 clear, real-world usage example. +- **Flags:** A list of available options with brief, actionable descriptions. +- **Documentation link (optional):** If more detail exists elsewhere. ```bash Usage: @@ -46,7 +137,7 @@ Flags: For more information, visit: https://Examples:.com/docs/deploy ``` -### Flag documentation +### Documenting flags Well-documented flags improve discoverability, reduce user error, and make it easier for contributors and users to understand the CLI’s capabilities. Clear flag documentation should be included in: @@ -54,6 +145,13 @@ Clear flag documentation should be included in: - Official CLI documentation or reference guides. - Interactive prompt hints (if applicable). +#### Best practices +- Use **descriptive names** that clearly indicate the flag’s purpose. +- Document the **flag’s input type** (string, boolean, int, and so on). +- Show the **default value** if one exists. +- Mention whether the flag is optional or required. +- Avoid vague or ambiguous flag names (like `--flag1`, `--optionX`). + Flag documentation should show the following: ```plaintext @@ -80,74 +178,48 @@ For boolean flags that act as switches (true/false): --watch Continuously stream status updates until completion. ``` -#### Best practices -- Use **descriptive names** that clearly indicate the flag’s purpose. -- Document the **flag’s input type** (string, boolean, int, and so on). -- Show the **default value** if one exists. -- Mention whether the flag is optional or required. -- Avoid vague or ambiguous flag names (like `--flag1`, `--optionX`). +## Interactive mode -## Interactive prompts +The CLI's interactive mode uses prompts to guide users through a process step-by-step., commonly for setup wizards, configuration flows, or input that is too complex to pass in a single command. -Interactive prompts guide users through a process step-by-step. They’re commonly used for setup wizards, configuration flows, or when input is too complex to pass in a single command. +### When to use interactive mode +User interactive mode for: +- Setup or initialization wizards. +- Optional configuration flows. +- Profile or environment selection. -### When to use interactive mode -- Recommended: --- Setup or initialization wizards --- Optional configuration flows --- Profile or environment selection +### When not to use interactive mode -- Avoid: --- Simple one-off tasks --- Repetitive actions (e.g., run, delete, status) --- Commands that will be run in automation, CI, or pipelines +Do not use interactive mode for: +- Simple one-off tasks. +- Repetitive actions (such as run, delete, status). +- Commands that will be run in automation, CI, or pipelines. -### Best Practices +### Writing interactive prompts + +When writing interactive prompts, follow these best practices: - Use prompts for guided setup, not quick or repeatable tasks. - Let users bypass prompts with a `--non-interactive` or `--yes` flag. - Clearly show default values and how to accept them. -- Offer inline help (fore example "? for help"). +- Offer inline help (for example "? for help"). - Don’t require prompts for essential inputs that could be passed as flags. -```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) +#### Default values -Enable telemetry? (y/N) -``` - -```plaintext -Select output format (default = 'json') [Use arrows to move, type to filter, ? for help]: -``` +Choose defaults based on common use cases or sensible fallbacks. -### Writing interactive prompts - -When writing interactive prompts, follow these best practices: - -#### Default values: - -Choose defaults based on common use cases or sensible fallbacks. - - Tell users that pressing Enter will accept the default andwWill proceed with a pre-set value if left blank. + - Tell users that pressing Enter will accept the default and will proceed with a pre-set value if left blank. - Always indicate the default value in a clear, visual way. For example, `[default]`, `(default)` or `(Y/n)`/`(y/N)`. - Avoid making the first item the default unless it is truly the most likely choice. - Don’t hide defaults in help text or assume the user knows them. - Log or echo the selected value for confirmation (even if it was a default). -#### Clarity: +#### Clarity + +Be as clear as possible in all messaging. + - Use question-style phrasing, such as "Enable autoscaling? (Y/n)". - Be clear if a prompt is optional. - Offer help inline, such as "Output directory [? for help]". @@ -158,139 +230,39 @@ Choose defaults based on common use cases or sensible fallbacks. - Include optional next steps when appropriate (e.g., view status, open logs) - Avoid silent success unless explicitly requested (e.g., in `--quiet` mode) -#### User control: - - Cancel with Ctrl+C - - Provide equivalent flags to bypass prompts - -#### Multi-step flows: - - Consider using a `--guided` flag to trigger multi-step flows intentionally. - - Allow users to exit early if needed. - -#### Error messaging and corrections +#### User control -When something goes wrong, the CLI should help users understand: -- What happened -- Why it happened -- How to fix it +Give users control over their experience in the CLI. -Error messages are a core part of the user experience. They should be written in plain language, not internal jargon, and provide actionable next steps. - - -- Make error messages human-readable -- Avoid stack traces unless a debug flag is enabled -- Place the most important information at the end (where scanning starts) -- Suggest solutions whenever possible - -**Generic failure with correction:** - -```plaintext -❌ Error: Cannot connect to remote service. -Check your network connection or try again with `--offline` mode. -``` - -**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. -``` - -**Command syntax error** -```plaintext -❌ Error: Unrecognized flag --versoin -Did you mean: --version ? -``` - -### Auto-correction and suggestions -Where appropriate, CLIs may offer suggestions or corrections for common typos: - -```plaintext -❌ Error: Unknown command “initaite” -Did you mean: “initiate”? -``` + - Consider using a `--guided` flag to trigger multi-step flows intentionally. + - Provide flags to bypass prompts. + - Allow users to cancel or exit flows early with **Ctrl**+**C**. -### Debugging information -For unexpected or low-level errors: -- Provide a clean message by default -- Use --debug or --trace flags to expose full stack traces or internal logs +### Example ```plaintext -❌ Unexpected error: Operation timed out. -Run with --debug for more details. -``` - -## Output patterns - -- **Success**: Action completed - `✅ Dataset uploaded successfully.` - -- **Warning**: Action completed but with something to review - `⚠️ Model trained, but validation accuracy is low.` - -- ❌ **Error**: Something failed (covered in previous section) - -### Examples: Output Patterns +Welcome! Let's configure your project. -```plaintext -✅ Project "my-app" deployed successfully. +Project name: my-app +Language (js, py, go) [py]: +Use Docker? (y/N): y -Next steps: -- Run `tool status my-app` to check deployment health -- Run `tool logs my-app` to view runtime output +✅ Project "my-app" configured successfully. ``` -### Structuring output for readability -- Use spacing, dividers, or indentation to break up large blocks of output. -- Use consistent headers or labels for repeated outputs (e.g., listing results or summaries). - ```plaintext -Results: +Choose deployment region: +[1] US East (N. Virginia) +[2] US West (Oregon) (default) +[3] Europe (Frankfurt) -✓ 12 files processed -✓ 2 files skipped (already up to date) -✓ 1 warning: Unused flag --optimize +Enable telemetry? (y/N) ``` -### Version listing and pagination - -When your CLI displays lists of items — such as software versions, available resources, or deployment options — it should be structured for easy scanning and include guidance when the list becomes long. - -Pagination and sensible ordering improve readability and reduce cognitive overload, especially when the output may exceed the visible terminal window. - -### Best Practices - -- **Show the most relevant or default item first** (e.g., the currently installed version) -- **Clearly label the default or active item** (e.g., with a "Yes" or "*") -- **Paginate output when the list exceeds 5–7 items** -- **Use table formatting or columns for consistency** -- Avoid dumping unstructured text or long, scrollable blobs - -### Examples:: Version Listing Output - ```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 +Select output format (default = 'json') [Use arrows to move, type to filter, ? for help]: ``` -- Versions are ordered top-down from newest to oldest -- The current default is clearly marked -- Upgrade paths are shown next to each item -### Pagination tips -For long lists: -- Break into pages of 5–7 items at a time -- Prompt the user with --more, --page, or allow Enter to continue -**Examples:** -```bash -tool versions list --limit 5 -tool resources list --page 2 -``` -### Sorting and Filtering -- Default sort should be by relevance or recency (e.g., newest version first) -- Offer flags like --sort, --filter, or --status for flexible output -- Make sure the default view meets the needs of most users — avoid requiring flags to make output usable From ab910dd25e9b66e1fa8862c2901ccdf47c69aa38 Mon Sep 17 00:00:00 2001 From: Erin Donehoo Date: Wed, 7 May 2025 11:37:08 -0400 Subject: [PATCH 3/5] Finalizes content editing. Signed-off-by: Erin Donehoo --- .../developer-resources/cli-guidelines.md | 132 ++++++----- .../developer-resources/cli-writing.md | 206 +++++++++--------- 2 files changed, 171 insertions(+), 167 deletions(-) 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 index d9c5c1c54f..7fac83a8dd 100644 --- a/packages/documentation-site/patternfly-docs/content/developer-resources/cli-guidelines.md +++ b/packages/documentation-site/patternfly-docs/content/developer-resources/cli-guidelines.md @@ -7,70 +7,83 @@ section: developer-resources # Designing for command-line interfaces -This resource provides best practices and guidelines for designing consistent, usable, and developer-friendly command-line interfaces (CLIs). These principles are intended to support both developers building CLI tooling and designers collaborating on technical products. - -These guidelines emphasize clarity, structure, and user-centered design across command syntax, help documentation, error messaging, and interactive behaviors. While they are applicable to a wide range of use cases, they are particularly helpful for teams working in environments where CLI tools serve as the primary or critical part of the user experience. +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 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—including those using screen readers or alternative input devices—can successfully interact with the tool. +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 rely on color alone to convey meaning. | Do use text alongside color-based cues (such as “Success” and “Error” labels).

Do use text alongside red/green indicators, to make the information accessible to colorblind users. | +| --- | --- | +| 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 -It is important to test your output through accessibility tools to reveal subtle issues in contrast, clarity, and verbosity. +
| **Don't** | **Do** | -|--------|-----------| -| Don't assume that your design is accessible. | Do test with screen readers and colorblind simulators. | +| --- | --- | +| 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:** +Accessible: + ```plaintext ✅ Deployment successful. Run `tool status` to check environment health. ``` -**Less accessible** +Less accessible: + ```plaintext ✅ You did it! ``` ## CLI inputs -CLI inputs are composed of a few parts: -- [Command name:](#command-names) Identifies the action a command will perform and the subject that the action applies to. -- [Arguments:](#arguments) Additional details used alongside the command name, which users select to specify the way that a command is applied. -- [Flags:](#flags) Named parameters that modify the behavior of the command. +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 that the CLI will trigger. +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. -Command names should follow a clear and consistent verb-noun structure: -- Verb: The action the command performs. -- Noun*: The resource or object the action applies to. +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. -Verb-noun commands mirror how people think about tasks, which makes the command more intuitive and easier for users to discover or guess. Noun-verb structures can be harder to parse and don't scale well. The verb-noun format also aligns with common patterns seen in widely-used CLIs like `git`, `kubectl`, and `docker`. +#### Example - +In the following code block, `create project`, `delete environment`, and `scale deployment` are all commands. ```bash tool create project @@ -78,88 +91,73 @@ tool delete environment tool scale deployment ``` -`create project`, `delete environment`, and `scale deployment` are all commands. - ### Arguments -An argument is anything to the right of a command that is not a flag. Often, they will be file paths, project names, or similar unique identifiers. +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. There can be multiple arguments in a command, but the order of arguments matters. It is better to use fewer arguments when possible, to make it easier for users to remember and avoid confusion. +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 ``` -`delete project` and `deploy environment` are commands, while `my-app` and `production` are arguments that represent the object being acted on. - ### Flags -Flags are named parameters 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. +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 ``` -#### Forms +#### Long-form and short-form There are 2 forms for flags: -##### 1. Long-form flags - -Long-form flags are clearer and more descriptive. - -They are written with 2 hyphens (--) and a descriptive name. +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 - -Short-form flags are more concise than long-form flags. They are and are particularly useful frequently used options, experienced users who prefer speed, and situations where space or typing efficiency matters. - -They are written with a single hyphen (-) followed by 1 or 2 letters. + ```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. -When possible, pair short-form flags with long-form equivalents for clarity and discoverability. - + - 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) -```bash -tool --help # Long-form -tool -h # Short-form (Help) + tool --verbose # Long-form + tool -v # Short-form (Verbose) -tool --verbose # Long-form -tool -v # Short-form (Verbose) - -tool --config path/to/file -tool -c path/to/file # Short-form (Config file path) -``` + tool --config path/to/file + tool -c path/to/file # Short-form (Config file path) + ``` -#### Types +#### Types of flags -1. Boolean flags: Represent on/off or true/false options. +1. **Boolean flags:** Represent on/off or true/false options. - Set a sensible default. - - Don’t require users to pass an explicit value unless necessary. + - 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: Allow users to receive help and load additional documentation that explains: - - What a command does. - - What arguments or flags it accepts. - - How to use it, with clear examples. +2. **Help flags:** Provide help documentation that explains a command's purpose, its arguments/flags, and usage examples. - Users should be able to use both a long (`--help` ) and short help (`-h`) flag. \ No newline at end of file + - 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 index 1eb3edbe73..d9c2fde04f 100644 --- a/packages/documentation-site/patternfly-docs/content/developer-resources/cli-writing.md +++ b/packages/documentation-site/patternfly-docs/content/developer-resources/cli-writing.md @@ -15,33 +15,11 @@ CLI output messages typically fall into one of 3 categories: | 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 -### Output patterns - -#### Formatting - -To ensure that output is readable: - -- Use spacing, dividers, or indentation to break up large blocks of output. -- Use consistent headers or labels for repeated outputs (such as listing results or summaries). -- When your CLI displays lists of items—such as software versions, available resources, or deployment options—it should be structured for easy scanning and include guidance when the list becomes long. -- Show the most relevant or default item first (like the currently installed version). -- Clearly label the default or active item (like with a "Yes" or "*"). -- [Paginate](#pagination) output when the list exceeds 5–7 items. -- Use table formatting or columns for consistency. -- Avoid dumping unstructured text or long, scrollable blobs. - -```plaintext -Results: +To build trust, reinforce that a command worked as intended, and guide users toward their next step, clearly communicate successful actions. -✓ 12 files processed -✓ 2 files skipped (already up to date) -✓ 1 warning: Unused flag --optimize -``` - -#### Success messages - -Clearly communicate when an action completes successfully to build trust, reinforce that a command worked as intended, and guide users toward their next step. +#### Example ```plaintext ✅ Project "my-app" deployed successfully. @@ -51,20 +29,48 @@ Next steps: - Run `tool logs my-app` to view runtime output ``` -#### Error messages +### 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. + ``` -When something goes wrong, help users understand what happened, why it happened, and how to fix it. +1. Command syntax error: + ```plaintext + ❌ Error: Unrecognized flag --versoin + Did you mean: --version ? + ``` -Like with our standard [UI error writing guidelines](/ux-writing/error-messages), CLI errors should: -- Be written in plain language. -- Not use internal jargon. -- Provide suggestions and actionable next steps. -- End with the most important information, rather than lead with it. -- Not display stack traces unless a debug flag is enabled. +### Output patterns + +#### Formatting -For unexpected or low-level errors: -- Provide a clean message by default. -- Use `--debug` or `--trace` flags to expose full stack traces or internal logs. +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 @@ -73,6 +79,8 @@ When listing version information: - Clearly mark the current default. - Display upgrade paths beside each item. +##### Example + ```plaintext Available Versions - @@ -84,7 +92,9 @@ VERSION DEFAULT AVAILABLE UPGRADES #### Pagination -Use pagination to break long lists into pages of 5–7 items at a time. When using pagination, prompt the user with `--more`, `--page`, or allow them to press **Enter** to continue +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 @@ -93,31 +103,31 @@ tool resources list --page 2 #### Sorting and filtering -To help users make sense of large CLI output, allow them to sort and filter as needed. When using sorting and filtering: - -- Default sort should be by relevance or recency. -- Offer flags like `--sort`, `--filter`, or `--status` for flexible output. -- Make sure the default view meets the needs of most users and avoid requiring flags to make output usable +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 -Users must have access to help within a CLI. - -When considering the relevance of help documentation, think like a user and ask yourself: “If I saw this message for the first time, would I know what to do?” +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? -When writing help documentation: -- Keep help text brief but meaningful. -- Avoid internal jargon and acronyms without explanation. -- Ensure consistency across all commands. -- If your CLI supports [interactive prompts](#interactive-prompts), reference `--help` in the prompt. +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 -Help output should be consistent across commands and follow a clear structure, containing these elements: -- **Description:** What the command does in plain language. -- **Usage:** Syntax with required arguments and flags. -- **Examples:** At least 1 clear, real-world usage example. -- **Flags:** A list of available options with brief, actionable descriptions. -- **Documentation link (optional):** If more detail exists elsewhere. + +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: @@ -140,24 +150,25 @@ 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. -Clear flag documentation should be included in: -- `--help` output for the command. +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. -- Document the **flag’s input type** (string, boolean, int, and so on). -- Show the **default value** if one exists. -- Mention whether the flag is optional or required. -- Avoid vague or ambiguous flag names (like `--flag1`, `--optionX`). +- 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 show the following: +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 @@ -168,19 +179,19 @@ Flags: ``` For boolean flags that act as switches (true/false): -- Default to false unless enabled. -- Do not require an explicit value (for example, use `--force`, not `--force=true`). +- 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 how the flag affects the command’s behavior or when it’s most useful: +- 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. -``` + ```plaintext + --dry-run Simulate the command without making changes. Useful for validation or preview. + --watch Continuously stream status updates until completion. + ``` ## Interactive mode -The CLI's interactive mode uses prompts to guide users through a process step-by-step., commonly for setup wizards, configuration flows, or input that is too complex to pass in a single command. +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 @@ -193,50 +204,45 @@ User interactive mode for: Do not use interactive mode for: - Simple one-off tasks. -- Repetitive actions (such as run, delete, status). -- Commands that will be run in automation, CI, or pipelines. +- 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 writing interactive prompts, follow these best practices: +When designing interactive prompts, prioritize flags for essential inputs and use prompts primarily for optional choices or guided multi-step processes. -- Use prompts for guided setup, not quick or repeatable tasks. -- Let users bypass prompts with a `--non-interactive` or `--yes` flag. -- Clearly show default values and how to accept them. -- Offer inline help (for example "? for help"). -- Don’t require prompts for essential inputs that could be passed as flags. +Key considerations include: #### Default values - Choose defaults based on common use cases or sensible fallbacks. - - Tell users that pressing Enter will accept the default and will proceed with a pre-set value if left blank. - - Always indicate the default value in a clear, visual way. For example, `[default]`, `(default)` or `(Y/n)`/`(y/N)`. - - Avoid making the first item the default unless it is truly the most likely choice. - - Don’t hide defaults in help text or assume the user knows them. - - Log or echo the selected value for confirmation (even if it was a default). +- 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 -Be as clear as possible in all messaging. +Ensure prompts are as clear as possible. - - Use question-style phrasing, such as "Enable autoscaling? (Y/n)". - - Be clear if a prompt is optional. - - Offer help inline, such as "Output directory [? for help]". - - Avoid chaining too many prompts. - - CLIs should clearly communicate when an action completes successfully. - - Confirm successful actions with a short, clear message -- Use consistent formatting, symbols, or icons for different message types -- Include optional next steps when appropriate (e.g., view status, open logs) -- Avoid silent success unless explicitly requested (e.g., in `--quiet` mode) +- 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 -Give users control over their experience in the CLI. +Empower users with control over their CLI experience. - - Consider using a `--guided` flag to trigger multi-step flows intentionally. - - Provide flags to bypass prompts. - - Allow users to cancel or exit flows early with **Ctrl**+**C**. +- 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 From 54e8404c3ad7d2b8b5ec0db83c4e827ad4305750 Mon Sep 17 00:00:00 2001 From: Erin Donehoo <105813956+edonehoo@users.noreply.github.com> Date: Wed, 7 May 2025 12:11:30 -0400 Subject: [PATCH 4/5] Typo --- .../content/developer-resources/cli-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 7fac83a8dd..e32fe6449a 100644 --- a/packages/documentation-site/patternfly-docs/content/developer-resources/cli-guidelines.md +++ b/packages/documentation-site/patternfly-docs/content/developer-resources/cli-guidelines.md @@ -7,7 +7,7 @@ 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 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. +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 From d72f7d46ef26f12841d45686edf7b3bb7969db56 Mon Sep 17 00:00:00 2001 From: Erin Donehoo <105813956+edonehoo@users.noreply.github.com> Date: Wed, 7 May 2025 12:12:22 -0400 Subject: [PATCH 5/5] Typo --- .../content/developer-resources/cli-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index e32fe6449a..ee1c0bf24a 100644 --- a/packages/documentation-site/patternfly-docs/content/developer-resources/cli-guidelines.md +++ b/packages/documentation-site/patternfly-docs/content/developer-resources/cli-guidelines.md @@ -151,7 +151,7 @@ There are 2 forms for 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`. + - Don’t require explicit values unless necessary. For example, allow `--force` rather than `--force=true`. ```bash tool deploy --dry-run # Runs without executing