docs: document interactive prompting policy (all-or-nothing) #11984
Conversation
|
Thank you for your pull request! 🎉 This PR appears to fix the following issues that are not labeled with
help wanted
As outlined in our Contributing Guidelines, we expect that PRs are only created for issues that have been labeled While we appreciate your initiative, please note that:
What happens next:
Thank you for your understanding and contribution to the project! 🙏 This comment was automatically generated by cliAutomation. |
There was a problem hiding this comment.
Pull Request Overview
This PR documents GitHub CLI's "all-or-nothing" interactive prompting behavior, addressing issue #10623. The documentation clarifies that commands either run in fully interactive mode (no input flags) or fully non-interactive mode (all input via flags), preventing confusion when users expect partial prompting.
Key Changes:
- Added a new "Interactive prompting policy" section to command-line-syntax.md explaining the CLI's prompting behavior
- Provided examples demonstrating interactive vs non-interactive command usage
- Included troubleshooting guidance for users who don't receive expected prompts
Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
| ## Interactive prompting policy | ||
| Design note: many `gh` commands follow an "all-or-nothing" prompting policy: if any flags or arguments that supply input are provided on the command line, the command will not prompt interactively for other fields. Put another way, commands behave either in a fully interactive mode (no input flags) or in a fully non-interactive mode (all required input supplied via flags/arguments). | ||
|
|
||
| Why this exists |
There was a problem hiding this comment.
This heading should follow standard markdown formatting with a leading '#' symbol. Change to '### Why this exists' to maintain proper heading hierarchy.
| Why this exists | |
| ### Why this exists |
Copilot uses AI. Check for mistakes.
| - Predictability: automation and scripts can call `gh` with flags and be confident it will not hang waiting for input. | ||
| - Simplicity: a single, easy-to-understand model reduces confusion for users — either supply everything up front or be prompted for everything. | ||
|
|
||
| Examples |
There was a problem hiding this comment.
This heading should follow standard markdown formatting with a leading '#' symbol. Change to '### Examples' to maintain proper heading hierarchy.
| Examples | |
| ### Examples |
Copilot uses AI. Check for mistakes.
|
|
||
| Supplying any input flags like `--title` or `--body` causes the command to avoid prompting for other fields. | ||
|
|
||
| If you expect a prompt but are not prompted |
There was a problem hiding this comment.
This heading should follow standard markdown formatting with a leading '#' symbol. Change to '### If you expect a prompt but are not prompted' to maintain proper heading hierarchy.
| If you expect a prompt but are not prompted | |
| ### If you expect a prompt but are not prompted |
Copilot uses AI. Check for mistakes.
| - Ensure no input flags or arguments are present. Even a single flag that supplies a value may disable interactive prompts for the remainder of the command. | ||
| - Consult the command's help (for example, `gh help issue create`) to see which flags are considered input flags. | ||
|
|
||
| Filing issues |
There was a problem hiding this comment.
This heading should follow standard markdown formatting with a leading '#' symbol. Change to '### Filing issues' to maintain proper heading hierarchy.
| Filing issues | |
| ### Filing issues |
Copilot uses AI. Check for mistakes.
|
|
||
| See the project's contribution guide for issue templates and guidance: `../.github/CONTRIBUTING.md`. | ||
|
|
||
| Rationale for placement |
There was a problem hiding this comment.
This heading should follow standard markdown formatting with a leading '#' symbol. Change to '### Rationale for placement' to maintain proper heading hierarchy.
| Rationale for placement | |
| ### Rationale for placement |
Copilot uses AI. Check for mistakes.
Fixes #10623
This patch adds a short, discoverable section to command-line-syntax.md that explains the CLI's "interactive prompting" behaviour: many commands are intentionaly "all-or-nothing" — if you supply any input via flags, the command will not prompt for missing fields. The new section explains the rationale, gives a brief example (when to use --title/--body vs gh issue create --fill), offers simple troubleshooting steps for users who expect partial prompting, and points contributors to the repository's CONTRIBUTING guidance for filing bugs or suggesting UX changes.