cli: T9077: document literal question mark entry and value quoting - #2149
cli: T9077: document literal question mark entry and value quoting#2149BradKollmyer wants to merge 1 commit into
Conversation
Document how to enter a literal '?' (Ctrl-V, and quoted values on rolling with the T9077 fix), the previously undocumented 'set terminal key query-help' toggle, and the need to quote values containing shell special characters such as '&'. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
📝 WalkthroughSummary by CodeRabbit
WalkthroughChangesCLI value input
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches✨ Simplify code
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
Claude finished @BradKollmyer's task in 3m 33s —— View job VyOS documentation review — PR #2149
IssuesWARNING — INFO — Verified against source
Needs Verification
Stats
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/cli.md`:
- Around line 44-45: Update the shell quoting guidance in the CLI documentation
to explain how to represent embedded quote characters, especially that single
quotes cannot appear directly inside Bash single-quoted strings. Describe using
an alternate delimiter or Bash escaping form, and ensure the examples cover
values containing quotes alongside spaces and shell-special characters.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Central YAML (inherited), Organization UI (inherited)
Review profile: CHILL
Plan: Pro
Run ID: 51ab4840-8c92-4182-897b-2b3dbbcf83e1
📒 Files selected for processing (1)
docs/cli.md
🔗 Linked repositories identified
CodeRabbit considers these linked repositories for cross-repo context during reviews:
ansible/ansible(manual)
📜 Review details
⏰ Context from checks skipped due to timeout. (4)
- GitHub Check: CodeRabbit
- GitHub Check: validate
- GitHub Check: Mergify Merge Protections
- GitHub Check: Summary
🧰 Additional context used
📓 Path-based instructions (2)
docs/**/*.md
📄 CodeRabbit inference engine (AGENTS.md)
docs/**/*.md: Canonical docs pages must be written as MyST Markdown (.md); edit existing pages in.mdonly and never use the oldmd-prefix for new pages.
Use{cfgcmd},{opcmd}, and{cmdincludemd}fenced directives in MyST pages for VyOS command coverage; do not replace them with plaintextorbashfences.
Use MyST ATX headings (#,##,###, etc.) in canonical pages; the RST heading hierarchy does not apply to.mdsources.
In MyST pages, prefer single backticks for inline code; double backticks are reserved for embedded RST contexts.
Use% stop_vyoslinterand% start_vyoslintercomment markers in top-level MyST content to suppress real IPs or other allowed long-line exceptions, and keep them paired.
In MyST pages, write TODO markers as{todo}fenced directives.
Files:
docs/cli.md
docs/{_include/*.txt,**/*.md}
📄 CodeRabbit inference engine (AGENTS.md)
Keep documentation lines within 80 characters unless the content is inside a code block or fenced/preformatted block.
Files:
docs/cli.md
🧠 Learnings (13)
📚 Learning: 2026-05-06T20:48:49.689Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 1902
File: CLAUDE.md:71-71
Timestamp: 2026-05-06T20:48:49.689Z
Learning: In vyos/vyos-documentation, the 80-character line-length rule documented under Source conventions / Formatting applies only to documentation source files located under docs/ (e.g., docs/**/*.rst and docs/**/*.md). The rule is enforced by the vyoslinter (doc-linter.py from vyos/.github) when reviewing changed files via lint-doc.yml, and only for files within docs/**. Do not suggest hard-wrapping CLAUDE.md (repo-root documentation) because GitHub renders and reflows content. For CLAUDE.md, reviews should not enforce the 80-char wrapping; apply the rule only to files matching **/docs/**/*.{rst,md}.
Applied to files:
docs/cli.md
📚 Learning: 2026-05-06T20:48:57.970Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 1902
File: CLAUDE.md:91-93
Timestamp: 2026-05-06T20:48:57.970Z
Learning: The 80-character line limit applies only to documentation sources under docs/** (RST/MD). Do not enforce this limit on repo-root Markdown files like CLAUDE.md or README.md. The vyoslinter (doc-linter.py, run via lint-doc.yml from vyos/.github) lints only changed files within docs/**; root files are excluded. GitHub renders root Markdown with viewport-width reflow, so hard-wrapping these files reduces readability without tooling benefit.
Applied to files:
docs/cli.md
📚 Learning: 2026-05-06T20:48:50.446Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 1902
File: CLAUDE.md:64-64
Timestamp: 2026-05-06T20:48:50.446Z
Learning: Enforce the 80-character line-length limit only for documentation source files under docs/ (docs/**/*.md and docs/**/*.rst rendered by Sphinx and linted by vyoslinter via lint-doc.yml). Do not flag line-length issues in repository-root Markdown files such as CLAUDE.md or README.md, which GitHub renders with viewport-width reflow. This applies to all files within docs/ that are part of the documentation source.
Applied to files:
docs/cli.md
📚 Learning: 2026-05-06T20:48:54.578Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 1902
File: CLAUDE.md:80-84
Timestamp: 2026-05-06T20:48:54.578Z
Learning: Enforce the 80-character line-length limit only for documentation source files under docs/ (docs/**/*.rst and docs/**/*.md). Do not flag repo-root files like CLAUDE.md or README.md, since they are rendered by GitHub and not subject to this rule. The doc-linter (doc-linter.py via lint-doc.yml) only lints docs/**, so CI checks won't flag root files for line length.
Applied to files:
docs/cli.md
📚 Learning: 2026-05-06T20:49:00.044Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 1902
File: CLAUDE.md:108-108
Timestamp: 2026-05-06T20:49:00.044Z
Learning: Limit the 80-character line length check and vyoslinter (doc-linter.py) enforcement to documentation source files under docs/**/*.{rst,md}. Do not apply or flag line-length issues in repo-root files like CLAUDE.md or README.md, which are rendered directly by GitHub and are not linted by lint-doc.yml. This pattern narrows checks to Sphinx source docs and prevents false positives in non-doc files.
Applied to files:
docs/cli.md
📚 Learning: 2026-05-06T20:48:53.302Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 1902
File: CLAUDE.md:79-79
Timestamp: 2026-05-06T20:48:53.302Z
Learning: Limit line length to 80 characters only for documentation sources under the docs directory (docs/**/*.rst and docs/**/*.md). This is enforced by the vyoslinter doc-linter.py (from the vyos/.github repo) via lint-doc.yml on changed files under docs/**. Do not flag line-length violations in repository-root Markdown files like CLAUDE.md or README.md, as they are rendered by GitHub and reflow in the UI.
Applied to files:
docs/cli.md
📚 Learning: 2026-05-06T20:49:10.359Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 1902
File: CLAUDE.md:142-142
Timestamp: 2026-05-06T20:49:10.359Z
Learning: In vyos/vyos-documentation, the 80-character line limit and vyoslinter enforcement apply only to documentation source files under docs/**/*.rst and docs/**/*.md that Sphinx renders. Repo-root files such as CLAUDE.md and README.md are outside the linter's scope (lint-doc.yml runs on docs/**) and are rendered by GitHub with automatic paragraph reflow — do not flag line-length violations in these files.
Applied to files:
docs/cli.md
📚 Learning: 2026-05-06T20:49:15.361Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 1902
File: CLAUDE.md:163-163
Timestamp: 2026-05-06T20:49:15.361Z
Learning: In vyos/vyos-documentation, enforce the 80-character line-length limit (Source conventions / Formatting) only for Sphinx documentation source files under docs/**/*.rst and docs/**/*.md. The lint-doc.yml workflow runs the doc-linter (doc-linter.py) and checks only docs/** changed files. Files in the repository root (e.g., CLAUDE.md, README.md) are rendered by GitHub and are not subject to this rule; do not flag line-length violations in those files.
Applied to files:
docs/cli.md
📚 Learning: 2026-05-08T07:01:22.978Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 1878
File: docs/troubleshooting/connectivity.rst:0-0
Timestamp: 2026-05-08T07:01:22.978Z
Learning: For the VyOS documentation (MyST-based docs), MyST directive opener lines must keep the entire directive arguments on a single line. This includes MyST fenced-directive openers like ```{opcmd} ... ``` and the RST-equivalent form .. opcmd:: ... when ported/used in MyST. Because the MyST parser does not support wrapped/continued directive arguments across multiple lines, do not raise/keep review warnings suggesting line wrapping for these directive opener lines due to line-length (even if they exceed 80 characters).
Applied to files:
docs/cli.md
📚 Learning: 2026-05-08T07:01:22.978Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 1878
File: docs/troubleshooting/connectivity.rst:0-0
Timestamp: 2026-05-08T07:01:22.978Z
Learning: In vyos/vyos-documentation, do not raise line-length (>80 chars) review findings for MyST directive opener lines (the directive “opener” that uses MyST directive syntax such as `{cfgcmd}` / `{opcmd}` fence/openers). CI does not enforce the 80-character limit for these specific opener lines, and existing documentation contains longer opener lines that pass lint.
Applied to files:
docs/cli.md
📚 Learning: 2026-05-13T22:16:06.198Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 2021
File: docs/automation/terraform/terraformvyos.md:14-14
Timestamp: 2026-05-13T22:16:06.198Z
Learning: In the vyos/vyos-documentation repo, when a PR is a byte-for-byte documentation port of an existing file from the rolling branch to a release branch (e.g., circinus, sagitta), keep the port content identical to the production-tested rolling source. For these ports, do not raise new review findings for documentation issues that are already present in the rolling source (for example, markdownlint MD059 like non-descriptive link text such as `[link]`/`[install]`). Instead, defer those existing issues to a rolling-side cleanup PR (e.g., `#2024`) and then backport the cleanup via Mergify.
Applied to files:
docs/cli.md
📚 Learning: 2026-05-13T22:43:41.056Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 2024
File: docs/automation/terraform/terraformvyos.md:0-0
Timestamp: 2026-05-13T22:43:41.056Z
Learning: In docs/**/*.md, for Markdown reference definition lines of the form `[label]: <URL>`, if the line cannot be shortened to <= 80 characters (because the URL itself is near/at the limit), suppress the vyoslinter warning by wrapping only that reference definition with a `% stop_vyoslinter` / `% start_vyoslinter` block. If the reference definition can fit within 80 characters, leave it outside any suppression block.
Applied to files:
docs/cli.md
📚 Learning: 2026-06-05T19:21:44.474Z
Learnt from: LiudmylaNad
Repo: vyos/vyos-documentation PR: 2066
File: docs/configuration/protocols/traffic-engineering.md:0-0
Timestamp: 2026-06-05T19:21:44.474Z
Learning: In the vyos/vyos-documentation MyST documentation pages, when writing CLI example invocations directly under a `{cfgcmd}` directive, use `none` fenced code blocks for those examples. Do not change these example blocks to `{opcmd}` or `{cfgcmd}`—`{opcmd}` is reserved for operational-mode commands, and the surrounding `{cfgcmd}` directive already documents the target command. Plain `none` blocks for these CLI examples are intentional and correct.
Applied to files:
docs/cli.md
🔍 Remote MCP Context7
Relevant shell context for the PR:
- In Bash/readline,
quoted-insert(Ctrl-Q/Ctrl-V) inserts the next typed character verbatim. cite - Double quotes preserve literal value for most characters, but Bash still treats
$,`,\, and!specially in some cases. cite - Bash control operators include
∧, so unquoted&/;can change command structure. cite ?is a shell glob wildcard matching a single character, and special pattern characters must be quoted to match literally. cite
This supports the doc change’s guidance about quoting values and avoiding shell interpretation of special characters. cite
🔀 Multi-repo context ansible/ansible
Linked repositories findings
ansible/ansible
- No
query-help,set terminal key, orCtrl-Vreferences were found; this repository does not appear to implement or consume the documented CLI behavior.[::ansible/ansible::] - Ansible does document shell-safe quoting through the
quotefilter inlib/ansible/plugins/filter/quote.yml, and uses it in shell-related examples, but this is unrelated to the proposed terminal command.[::ansible/ansible::]
🔇 Additional comments (1)
docs/cli.md (1)
20-39: 🎯 Functional CorrectnessVerify the release-specific behavior claims.
The command and its enabled default are established in the Vyatta reference, but the supplied evidence does not confirm the rolling/LTS distinction,
Ctrl-Vsupport on every release, or persistence in~/.bashrc. Validate these claims against each supported VyOS release or add explicit version/source qualifiers. (sdpf.ntt.com)
| Always quote a value that contains spaces or shell special characters such | ||
| as `&`, `;`, `#` or quotes. The configuration shell is based on bash: an |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Explain how to quote embedded quote characters.
“Always quote” is incomplete for values containing quotes: a single quote cannot appear inside a Bash single-quoted string, so users need delimiter-specific escaping or an alternate quoting form. Bash documents this restriction explicitly. (gnu.org)
Suggested wording
-Always quote a value that contains spaces or shell special characters such
-as `&`, `;`, `#` or quotes.
+Quote and escape values that contain spaces or shell special characters such
+as `&`, `;`, `#`, or quote characters. Use a quoting form that does not
+conflict with any embedded quote.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Always quote a value that contains spaces or shell special characters such | |
| as `&`, `;`, `#` or quotes. The configuration shell is based on bash: an | |
| Quote and escape values that contain spaces or shell special characters such | |
| as `&`, `;`, `#`, or quote characters. Use a quoting form that does not | |
| conflict with any embedded quote. The configuration shell is based on bash: an |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/cli.md` around lines 44 - 45, Update the shell quoting guidance in the
CLI documentation to explain how to represent embedded quote characters,
especially that single quotes cannot appear directly inside Bash single-quoted
strings. Describe using an alternate delimiter or Bash escaping form, and ensure
the examples cover values containing quotes alongside spaces and shell-special
characters.
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| On LTS and older releases the `?` key always triggers help, even inside | ||
| quotes — use `Ctrl-V` `?` there. | ||
|
|
||
| ```{opcmd} set terminal key query-help <enable | disable> |
There was a problem hiding this comment.
WARNING — Unescaped angle brackets in {opcmd} directive argument
Doc says: ```{opcmd} set terminal key query-help <enable | disable>
Convention elsewhere in this file and repo escapes them as \<...\> — e.g. docs/cli.md:866 (show system commit diff \<number\>), docs/configuration/service/dns.md:321 (reset dns forwarding \<all | domain\>), docs/configuration/service/console-server.md:192 (connect console \<device | alias\>).
Branch: rolling (vyos-1x: current)
Unescaped <enable | disable> can be parsed as an HTML tag by MyST/Sphinx and stripped or malformed in HTML output. Please escape for consistency and safe rendering:
| ```{opcmd} set terminal key query-help <enable | disable> | |
| ```{opcmd} set terminal key query-help \<enable | disable\> |
| ### Quoting values | ||
|
|
||
| Always quote a value that contains spaces or shell special characters such | ||
| as `&`, `;`, `#` or quotes. The configuration shell is based on bash: an | ||
| unquoted `&` does not cause an error — it is interpreted as a command | ||
| separator and the value is **silently truncated** at the `&`: | ||
|
|
||
| ``` none | ||
| set firewall group remote-group EXAMPLE url 'https://example.com/list?key=abc&ipVersion=4' | ||
| ``` | ||
|
|
||
| For example typing `sh` followed by the `TAB` key will complete to `show`. |
There was a problem hiding this comment.
INFO — Section placement disrupts existing flow
Before the change, the paragraph at line 14–16 (about ? and TAB) flowed directly into "For example typing sh followed by the TAB key will complete to show." (now line 53). After inserting the two new h3 sections, the "For example" reference sits two headings away from the introductory TAB mention, and the immediate context above it is about quoting & in values — unrelated to the tab-completion example that follows.
Consider moving the new "Typing a literal question mark" and "Quoting values" sections after the tab-completion examples (around line ~100+), so the intro → tab example flow is preserved and the special-character caveats are grouped with the rest of the operational-mode notes.
There was a problem hiding this comment.
Pull request overview
This PR updates the VyOS CLI user documentation to clarify how to enter a literal ? (without triggering interactive help) and when/why to quote CLI values that include shell-special characters.
Changes:
- Adds guidance for typing a literal
?in CLI input (including rolling-only quote-aware behavior). - Documents the
set terminal key query-help <enable | disable>operational command. - Adds a new “Quoting values” section explaining why special characters (e.g.,
&,;,#) require quoting.
| On LTS and older releases the `?` key always triggers help, even inside | ||
| quotes — use `Ctrl-V` `?` there. | ||
|
|
||
| ```{opcmd} set terminal key query-help <enable | disable> |
| separator and the value is **silently truncated** at the `&`: | ||
|
|
||
| ``` none | ||
| set firewall group remote-group EXAMPLE url 'https://example.com/list?key=abc&ipVersion=4' |
Change Summary
Document how to enter a literal question mark in the CLI, and the need to quote values containing shell special characters.
docs/cli.md:Ctrl-V?(all releases), and the rolling behavior from T9077 / vyos-1x#5328 where a?typed inside a quoted string is inserted literally.set terminal key query-help <enable | disable>operational command.&,;, spaces etc. must be quoted — an unquoted&silently truncates the command instead of raising an error.Related Task(s)
Related PR(s)
Backport
The
Ctrl-Vguidance and the quoting section apply to all releases; the quoted-?behavior is rolling-only and is phrased as such, so backporting is optional.Checklist:
🤖 Generated with Claude Code