diff --git a/Library/Homebrew/cmd/list.rb b/Library/Homebrew/cmd/list.rb
index 3e1aa57ba2..fcdec9e227 100644
--- a/Library/Homebrew/cmd/list.rb
+++ b/Library/Homebrew/cmd/list.rb
@@ -25,20 +25,44 @@ require "cli_parser"
 module Homebrew
   module_function
 
-  def list
-    Homebrew::CLI::Parser.parse do
-      switch "--unbrewed"
-      switch "--pinned"
-      switch "--versions"
-      switch "--full-name"
-      switch "--multiple", depends_on: "--versions"
-      switch :verbose
+  def list_args
+    Homebrew::CLI::Parser.new do
+      usage_banner <<~EOS
+        `list`, `ls` [<options>] [`-1`] [`-l`] [`-t`] [`-r`]
+
+        List all installed formulae.
+      EOS
+      switch "--full-name",
+        description: "Print formulae with fully-qualified names.  If `--full-name` is not "\
+                     "passed, other options (i.e. `-1`, `-l`, `-t` and `-r`) are passed to `ls` "\
+                     "which produces the actual output."
+      switch "--unbrewed",
+        description: "List all files in the Homebrew prefix not installed by Homebrew."
+      switch "--versions",
+        description: "Show the version number for installed formulae, or only the specified "\
+                     "formulae if <formulae> are given."
+      switch "--multiple",
+        depends_on:  "--versions",
+        description: "Only show formulae with multiple versions installed."
+      switch "--pinned",
+        description: "Show the versions of pinned formulae, or only the specified (pinned) "\
+                     "formulae if <formulae> are given. See also `pin`, `unpin`."
       # passed through to ls
-      switch "-1"
-      switch "-l"
-      switch "-t"
-      switch "-r"
+      switch "-1",
+        description: "Option passed to `ls`"
+      switch "-l",
+        description: "Option passed to `ls`"
+      switch "-t",
+        description: "Option passed to `ls`"
+      switch "-r",
+        description: "Option passed to `ls`"
+      switch :verbose
+      switch :debug
     end
+  end
+
+  def list
+    list_args.parse
 
     # Use of exec means we don't explicitly exit
     list_unbrewed if args.unbrewed?