diff --git a/doc/pages/commands.asciidoc b/doc/pages/commands.asciidoc
index 0e4f779bc..4baf5cbfe 100644
--- a/doc/pages/commands.asciidoc
+++ b/doc/pages/commands.asciidoc
@@ -79,12 +79,12 @@ command *q!* has to be used). Aliases are mentionned below each commands.
 
 == Options
 
-*declare-option* [-hidden] <type> <name> [<value>]::
+*declare-option* [<switches>] <type> <name> [<value>]::
     *alias* decl +
-    declare a new option, the -hidden hides the option in completion
+    declare a new option, the -hidden switch hides the option in completion
     suggestions (See <<options#declare-option,`:doc options declare-option`>>)
 
-*set-option* <scope> <name> <value>::
+*set-option* [<switches>] <scope> <name> <value>::
     *alias* set +
     change the value of an option
     note that the name of a particular buffer can be specified when the
@@ -103,7 +103,7 @@ command *q!* has to be used). Aliases are mentionned below each commands.
 
 == Commands and Keys
 
-*define-command* [<flags>] <name> <command>::
+*define-command* [<switches>] <name> <command>::
     *alias* def +
     define a new command (See <<declaring-new-commands,Declaring new commands>>)
 
@@ -114,16 +114,16 @@ command *q!* has to be used). Aliases are mentionned below each commands.
     remove an alias if its current value is the same as the one passed
     as an optional parameter, remove it unconditionally otherwise
 
-*evaluate-commands* [<flags>] <command> ...::
+*evaluate-commands* [<switches>] <command> ...::
     *alias* eval +
     evaluate commands, as if they were entered in the command prompt
     (See <<execeval#,`:doc execeval`>>)
 
-*execute-keys* [<flags>] <key> ...::
+*execute-keys* [<switches>] <key> ...::
     *alias* exec +
     execute a series of keys, as if they were hit (See <<execeval#,`:doc execeval`>>)
 
-*map* <scope> <mode> <key> <keys>::
+*map* [<switches>] <scope> <mode> <key> <keys>::
     bind a list of keys to a combination (See <<mapping#,`:doc mapping`>>)
 
 *unmap* <scope> <mode> <key> [<expected>]::
@@ -132,7 +132,7 @@ command *q!* has to be used). Aliases are mentionned below each commands.
 *declare-user-mode* <name>::
     declare a new user keymap mode
 
-*enter-user-mode* <name>::
+*enter-user-mode* [<switches>] <name>::
     enable <name> keymap mode for next key
 
     *-lock*:::
@@ -151,8 +151,8 @@ command *q!* has to be used). Aliases are mentionned below each commands.
 
 == Display
 
-*echo* [options] <text>::
-    show *text* in status line, with the following *options*:
+*echo* [<switches>] <text>::
+    show *text* in status line, with the following *switches*:
 
     *-markup*:::
         expand the markup strings in *text* (See
@@ -168,7 +168,7 @@ command *q!* has to be used). Aliases are mentionned below each commands.
 *colorscheme* <name>::
     load named colorscheme
 
-*add-highlighter* [<flags>] <highlighter_name> <highlighter_parameters> ...::
+*add-highlighter* <highlighter_name> <highlighter_parameters> ...::
     *alias* addhl +
     add a highlighter to the current window
     (See <<highlighters#,`:doc highlighters`>>)
@@ -184,7 +184,7 @@ Kakoune provides some helper commands that can be used to define composite
 commands in scripts. They are also available in the interactive mode,
 but not really useful in that context.
 
-*prompt* <prompt> <command>::
+*prompt* [<switches>] <prompt> <command>::
     prompt the user for a string, when the user validates, executes the
     command. The entered text is available in the `text` value accessible
     through `$kak_text` in shells or `%val{text}` in commands.
@@ -202,7 +202,7 @@ but not really useful in that context.
     available through the `key` value, accessible through `$kak_key`
     in shells, or `%val{key}` in commands.
 
-*menu* <label1> <commands1> <label2> <commands2> ...::
+*menu* [<switches>] <label1> <commands1> <label2> <commands2> ...::
     display a menu using labels, the selected label’s commands are
     executed. The *menu* command can take an *-auto-single* argument, to automatically
     run commands when only one choice is provided, and a *-select-cmds*
@@ -210,8 +210,8 @@ but not really useful in that context.
     last one being a command to execute when the item is selected (but
     not validated)
 
-*info* [options] <text>::
-    display text in an information box with the following *options*:
+*info* [<switches>] <text>::
+    display text in an information box with the following *switches*:
 
     *-anchor* <line>.<column>:::
         print the text at the given coordinates
@@ -253,8 +253,8 @@ backslash (\;) to be considered as a literal semicolon argument
 
 New commands can be defined using the *define-command* command:
 
-*define-command* [flags] <command_name> <commands>::
-    *commands* is a string containing the commands to execute, and *flags*
+*define-command* [<switches>] <command_name> <commands>::
+    *commands* is a string containing the commands to execute, and *switches*
     can be any combination of the following parameters:
 
 *-params* <num>:::
diff --git a/src/commands.cc b/src/commands.cc
index b6ba6b363..1af3cc90f 100644
--- a/src/commands.cc
+++ b/src/commands.cc
@@ -772,7 +772,7 @@ static Completions complete_hooks(const Context&, CompletionFlags,
 const CommandDesc add_hook_cmd = {
     "hook",
     nullptr,
-    "hook <switches> <scope> <hook_name> <filter> <command>: add <command> in <scope> "
+    "hook [<switches>] <scope> <hook_name> <filter> <command>: add <command> in <scope> "
     "to be executed on hook <hook_name> when its parameter matches the <filter> regex\n"
     "<scope> can be:\n"
     "  * global: hook is executed for any buffer or window\n"
@@ -1017,7 +1017,7 @@ void define_command(const ParametersParser& parser, Context& context, const Shel
 const CommandDesc define_command_cmd = {
     "define-command",
     "def",
-    "define-command <switches> <name> <cmds>: define a command <name> executing <cmds>",
+    "define-command [<switches>] <name> <cmds>: define a command <name> executing <cmds>",
     ParameterDesc{
         { { "params",             { true, "take parameters, accessible to each shell escape as $0..$N\n"
                                           "parameter should take the form <count> or <min>..<max> (both omittable)" } },
@@ -1264,7 +1264,7 @@ static OptionManager& get_options(StringView scope, const Context& context, Stri
 const CommandDesc set_option_cmd = {
     "set-option",
     "set",
-    "set-option <switches> <scope> <name> <value>: set option <name> in <scope> to <value>\n"
+    "set-option [<switches>] <scope> <name> <value>: set option <name> in <scope> to <value>\n"
     "<scope> can be global, buffer, window, or current which refers to the narrowest "
     "scope the option is set in",
     ParameterDesc{
@@ -1448,7 +1448,7 @@ auto map_key_completer =
 const CommandDesc map_key_cmd = {
     "map",
     nullptr,
-    "map <scope> <mode> <key> <keys>: map <key> to <keys> in given mode in <scope>.\n"
+    "map [<switches>] <scope> <mode> <key> <keys>: map <key> to <keys> in given mode in <scope>.\n"
     "<mode> can be:\n"
     "    normal\n"
     "    insert\n"
@@ -1693,7 +1693,7 @@ void context_wrap(const ParametersParser& parser, Context& context, Func func)
 const CommandDesc exec_string_cmd = {
     "execute-keys",
     "exec",
-    "execute-keys <switches> <keys>: execute given keys as if entered by user",
+    "execute-keys [<switches>] <keys>: execute given keys as if entered by user",
     context_wrap_params,
     CommandFlags::None,
     CommandHelper{},
@@ -1718,7 +1718,7 @@ const CommandDesc exec_string_cmd = {
 const CommandDesc eval_string_cmd = {
     "evaluate-commands",
     "eval",
-    "evaluate-commands <switches> <commands>...: execute commands as if entered by user",
+    "evaluate-commands [<switches>] <commands>...: execute commands as if entered by user",
     context_wrap_params,
     CommandFlags::None,
     CommandHelper{},
@@ -1831,7 +1831,7 @@ const CommandDesc prompt_cmd = {
 const CommandDesc menu_cmd = {
     "menu",
     nullptr,
-    "menu <switches> <name1> <commands1> <name2> <commands2>...: display a "
+    "menu [<switches>] <name1> <commands1> <name2> <commands2>...: display a "
     "menu and execute commands for the selected item",
     ParameterDesc{
         { { "auto-single", { false, "instantly validate if only one item is available" } },
@@ -1911,7 +1911,7 @@ const CommandDesc on_key_cmd = {
 const CommandDesc info_cmd = {
     "info",
     nullptr,
-    "info <switches> <params>...: display an info box with the params as content",
+    "info [<switches>] <params>...: display an info box with the params as content",
     ParameterDesc{
         { { "anchor",    { true, "set info anchoring <line>.<column>" } },
           { "placement", { true, "set placement relative to anchor (above, below)" } },
@@ -2162,7 +2162,7 @@ void enter_user_mode(Context& context, const String mode_name, KeymapMode mode,
 const CommandDesc enter_user_mode_cmd = {
     "enter-user-mode",
     nullptr,
-    "enter-user-mode <switches> <name>: enable <name> keymap mode for next key",
+    "enter-user-mode [<switches>] <name>: enable <name> keymap mode for next key",
     ParameterDesc{
         { { "lock", { false, "stay in mode until <esc> is pressed" } } },
         ParameterDesc::Flags::SwitchesOnlyAtStart, 1, 1