Skip to content

cli: T9077: document literal question mark entry and value quoting #2149

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
BradKollmyer wants to merge 1 commit into
base: rolling
Choose a base branch
from
Open

cli: T9077: document literal question mark entry and value quoting #2149

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 35 additions & 0 deletions docs/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,41 @@
display available commands. The `TAB` key can be used to auto-complete commands
and will present the help system upon a conflict or unknown value.

### Typing a literal question mark

Because `?` is the help key, a literal question mark needs special handling
when it is part of a value, such as a URL with a query string. Press
`Ctrl-V` followed by `?` to insert a literal question mark; this works on
all VyOS releases.

On current rolling releases a `?` typed **inside a quoted string** is
inserted literally, and only triggers the help system outside of quotes:

``` none
set firewall group remote-group EXAMPLE url 'https://example.com/list?key=abc'
```

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>

@github-actions github-actions Bot Jul 11, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

Suggested change
```{opcmd} set terminal key query-help <enable | disable>
```{opcmd} set terminal key query-help \<enable | disable\>


Enable or disable getting help using the question mark key. When disabled,
`?` always inserts a literal question mark. The setting is stored in the
user's `~/.bashrc` and persists across sessions. Default: enabled.
```

### 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
Comment on lines +44 to +45

@coderabbitai coderabbitai Bot Jul 11, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 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.

Suggested change
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.

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`.
Comment on lines +42 to 53

@github-actions github-actions Bot Jul 11, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Pressing `TAB` a second time will display the possible sub-commands of the
`show` command.
Expand Down Expand Up @@ -300,7 +335,7 @@

::::{hint}

Use the `show configuration commands | strip-private` command when you want to hide private data. You may want to do so if you want to share your configuration on the [forum](https://forum.vyos.io).

Check warning on line 338 in docs/cli.md

View workflow job for this annotation

GitHub Actions / doc-lint 

Line too long: len=198
::::

```{opcmd} show configuration json
Expand Down Expand Up @@ -721,7 +756,7 @@
}
:::
:::{note}
An important thing to note is that since the comment is added on top of the section, it will not appear if the `show <section>` command is used. With the above example, the ``show firewall`` command would return starting after the `firewall {` line, hiding the comment.

Check warning on line 759 in docs/cli.md

View workflow job for this annotation

GitHub Actions / doc-lint 

Line too long: len=269
:::
```

Expand Down Expand Up @@ -892,9 +927,9 @@
:::{note}
The number of revisions don\'t affect the commit-archive.

When using Git as destination for the commit archive the `source-address` CLI option has no effect.

Check warning on line 930 in docs/cli.md

View workflow job for this annotation

GitHub Actions / doc-lint 

Line too long: len=99

You may find VyOS not allowing the secure connection because it cannot verify the legitimacy of the remote server. You can use the workaround below to quickly add the remote host\'s SSH fingerprint to your `~/.ssh/known_hosts` file:

Check warning on line 932 in docs/cli.md

View workflow job for this annotation

GitHub Actions / doc-lint 

Line too long: len=232
:::
:::{code-block} none
vyos@vyos# ssh-keyscan <host> >> ~/.ssh/known_hosts
Expand Down
Loading