Make bin/doom options consistent & improve errors/docs

bin/doom

@@ -95,7 +95,8 @@
            (condition-case e
                (doom-dispatch (car args) (cdr args))
              (user-error
-              (signal (car e) (cdr e)))
+              (print! (error "%s\n") (error-message-string e))
+              (print! (yellow "See 'doom help %s' for documentation on this command.") (car args)))
              ((debug error)
               (message "--------------------------------------------------\n")
               (message "There was an unexpected error:")

core/cli/debug.el

@@ -7,17 +7,29 @@
 ;;; Commands
 
 (def-command! info (&optional format)
-  "Output system info in markdown for bug reports."
+  "Output system info in markdown for bug reports.
+
+Will print in the following formats:
+
+  --json
+  --md / --markdown
+  --lisp
+
+If no arguments are given, --raw is assumed."
   (pcase format
-    ("json"
+    ("--json"
      (require 'json)
      (with-temp-buffer
        (insert (json-encode (doom-info)))
        (json-pretty-print-buffer)
        (print! (buffer-string))))
-    ((or "md" "markdown")
+    ((or "--md" "--markdown")
      (doom/info))
-    (_ (doom/info 'raw)))
+    ((or `nil "--lisp")
+     (doom/info 'raw))
+    (_
+     (user-error "I don't understand %S. Did you mean --json, --md/--markdown or --lisp?"
+                 format)))
   nil)
 
 (def-command! (version v) ()

core/cli/env.el

@@ -1,11 +1,13 @@
 ;;; core/cli/env.el -*- lexical-binding: t; -*-
 
-(def-command! env (&optional command)
-  "Manages your envvars file.
+(def-command! env (&rest args)
+  "Regenerates your envvars file.
 
-  env [SUBCOMMAND]
+  doom env [-c|--clear]
 
-Available subcommands:
+If -c or --clear is present
+
+Available switches:
 
   refresh  Create or regenerate your envvar file
   auto     enable auto-reloading of your envvars file (on `doom refresh`)
@@ -21,16 +23,24 @@ To generate a file, run `doom env refresh`. If you'd like this file to be
 auto-reloaded when running `doom refresh`, run `doom env enable` instead (only
 needs to be run once)."
   (let ((default-directory doom-emacs-dir))
-    (pcase command
-      ("clear"
+    (when (member "clear" args)  ; DEPRECATED
+      (message "'doom env clear' is deprecated. Use 'doom env -c' or 'doom env --clear' instead")
+      (push "-c" args))
+
+    (cond ((or (member "-c" args)
+               (member "--clear" args))
            (unless (file-exists-p doom-env-file)
              (user-error! "%S does not exist to be cleared"
                           (relpath doom-env-file)))
            (delete-file doom-env-file)
            (print! (success "Successfully deleted %S")
                    (relpath doom-env-file)))
-      (_
-       (doom-reload-env-file 'force)))))
+
+          ((null args)
+           (doom-reload-env-file 'force))
+
+          ((user-error "I don't understand 'doom env %s'"
+                       (string-join args " "))))))
 
 
 ;;

core/cli/install.el

@@ -1,7 +1,9 @@
 ;;; core/cli/install.el -*- lexical-binding: t; -*-
 
 (def-command! quickstart (&rest args)  ; DEPRECATED
-  ""
+  "This is a deprecated alias for 'doom install'.
+
+See 'doom help install' instead."
   :hidden t
   (apply #'doom-cli-install args))
 
@@ -30,7 +32,8 @@ install understands the following switches:
   --no-config    Don't create DOOMDIR or dummy files therein
   --no-install   Don't auto-install packages
   --no-env       Don't generate an envvars file (see `doom help env`)
-  --no-fonts     Don't install (or prompt to install) all-the-icons fonts"
+  --no-fonts     Don't install (or prompt to install) all-the-icons fonts
+  -y / --yes     Auto-accept any confirmation prompts"
   (print! (green "Installing Doom Emacs!\n"))
   (let ((default-directory (doom-path "~")))
     ;; Create `doom-private-dir'

core/cli/packages.el

@@ -30,13 +30,15 @@ or :ignore property."
 This ensures that all needed files are symlinked from their package repo and
 their elisp files are byte-compiled."
   (doom--ensure-autoloads-while
-   (doom-packages-rebuild doom-auto-accept (member "all" args))))
+   (doom-packages-rebuild doom-auto-accept (member "-f" args))))
 
 (def-command! (purge p) (&rest args)
   "Deletes any unused packages and repos."
   (doom--ensure-autoloads-while
    (straight-check-all)
-   (doom-packages-purge 'elpa-p 'build-p 'repos-p doom-auto-accept)))
+   (doom-packages-purge 'elpa-p 'build-p
+                        (member "-f" args)
+                        doom-auto-accept)))
 
 ;; (def-command! rollback () ; TODO rollback
 ;;   "<Not implemented yet>"

core/cli/patch-macos.el

@@ -1,6 +1,6 @@
 ;;; core/cli/patch-macos.el -*- lexical-binding: t; -*-
 
-(def-command! patch-macos ()
+(def-command! patch-macos ()  ; DEPRECATED
   "Patches Emacs.app to respect your shell environment.
 
 WARNING: This command is deprecated. Use 'doom env' instead.

core/cli/upgrade.el

@@ -3,7 +3,8 @@
 (def-command! (upgrade up) ()
   "Updates Doom and packages.
 
-Doing so is equivalent to:
+This requires that ~/.emacs.d is a git repo, and is the equivalent of the
+following shell commands:
 
     cd ~/.emacs.d
     git pull

core/core-cli.el

@@ -99,6 +99,7 @@ If SHOW-HELP is non-nil, show the documentation for said dispatcher."
       (let ((start-time (current-time)))
         (run-hooks 'doom-cli-pre-execute-hook)
         (unwind-protect
+            (condition-case e
                 (when-let (ret (apply fn args))
                   (print!
                    "\n%s"
@@ -108,6 +109,8 @@ If SHOW-HELP is non-nil, show the documentation for said dispatcher."
                                             start-time))))
                   (run-hooks 'doom-cli-post-execute-hook)
                   ret)
+              ('wrong-number-of-arguments
+               (user-error "I don't understand 'doom %s %s'\n\nRun 'doom help' to see what I do understand." cmd (string-join args " "))))
           (run-hooks 'doom-cli-post-error-execute-hook))))))
 
 (defmacro def-command-group! (name docstring &rest body)