Clearer spelling suggestions in CLI

[shannonbux]

Summary

Suggestion to improve the CLI suggestions when you misspell a command or enter an unsupported/invalid command.

Details

Currently, the CLI looks like this when you misspell something.

Here's what happens when you enter an invalid command. Exactly the same as above except the last few lines look like this:

This is pretty good, and can still be improved because it isn't immediately obvious that

1. the command didn't work
2. there is a suggestion that the user can act on

Possible improvements

One design principle is proximity, which means it's helpful to users when the relevant information is close to each other in time and space. So we want these things to be close to each other in time and space:

1. The error explanation
2. The suggestion for what to do next
3. The area where the user can take action and run the new command

If someone accepts an autocorrect suggestion:

Shannons-MacBook-Pro:watson-dog shannonsoper$ gatsby dvelop
Running `gatsby develop` (press [n] to run `gatsby dvelop` instead)

If someone doesn't want the autocorrect behavior:

Shannons-MacBook-Pro:watson-dog shannonsoper$ gatsby dvelop
Running `gatsby develop` (press n to run `gatsby dvelop` instead) n
Running `gatsby dvelop`
Error: unknown argument: `gatsby dvelop` 
Here are all Gatsby commands. Did you mean one of these?

Usage: gatsby <command> [options]

Commands:
  gatsby develop                   Start development server. Watches files,
                                   rebuilds, and hot reloads if something
                                   changes
  gatsby build                     Build a Gatsby project.
  gatsby serve                     Serve previously built Gatsby site.
  gatsby info                      Get environment information for debugging and
                                   issue reporting
  gatsby clean                     Wipe the local gatsby environment including
                                   built assets and cache
  gatsby repl                      Get a node repl with context of Gatsby
                                   environment, see (add docs link here)
  gatsby new [rootPath] [starter]  Create new Gatsby project.
  gatsby telemetry                 Enable or disable Gatsby anonymous analytics
                                   collection.

Options:
  --verbose                Turn on verbose output     [boolean] [default: false]
  --no-color, --no-colors  Turn off the color in output
                                                      [boolean] [default: false]
  -h, --help               Show help                                   [boolean]
  -v, --version            Show version number                         [boolean]
 
Shannons-MacBook-Pro:watson-dog shannonsoper$

OR autocorrect could work great too, sort of like spellchecking in Microsoft Word.

Motivation

It's good to reduce the amount of cognitive effort people have to spend on small and large things. This is a small thing that we can reduce people's effort to notice and correct. #12951

Question

If the CLI talks directly to the user, do we want it to be an "I" or a "we" e.g. "I will run this command for you"? Otherwise, we have to speak in passive voice, e.g. "this command will be run". I'm sort of in favor of "I" with passive voice a close second, though could be convinced otherwise. Not a fan of "we" lol.

Thanks and fyi @DSchau @jamo @KyleAMathews @sidharthachatterjee

[dev-rsilver]

I would suggest phrasing as a question directed to the user to avoid use of "I" or "we". "Do you want to run gatsby develop [y/n]?"

[janosh]

Slightly related: I think the CLI could also be improved by not asking the user if gatsby-cli should use a different port if something is already occupying the default one (8000) but simply do it. I.e. rather than

Something is already running at port 8000 
Would you like to run the app at another port instead? [Y/n]

just inform the user that the next available port will be used instead:

Something is already running at port 8000 
Using port 8001 instead.
Rerun `<command name>` with the `-p` option to specify a different port.

I made this suggestion before in #368 and would be interested if there's a problem with this approach that escapes me.

[shannonbux]

I like both of those ideas!

…

On Tue, Apr 23, 2019 at 5:28 AM Janosh Riebesell ***@***.***> wrote: Slightly related: I think the CLI could also be improved by not asking the user if gatsby-cli should use a different port if something is already occupying the default one (8000) but *simply do it*. I.e. rather than Something is already running at port 8000 Would you like to run the app at another port instead? [Y/n] just inform the user that the next available port will be used instead: Something is already running at port 8000 Using port 8001 instead. Rerun `<command name>` with the `-p` option to specify a different port. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <https://github.com/gatsbyjs/gatsby/issues/13512#issuecomment-485781525>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AHXWRWWVXZLO3WN7QHVH7WLPR36IDANCNFSM4HHIV72Q> .

[DSchau]

Hi @shannonbux!

This works!

gatsby develo
error Usage: gatsby <command> [options]

Commands:
  gatsby develop                   Start development server. Watches files, rebuilds, and hot reloads if something changes
  gatsby build                     Build a Gatsby project.
  gatsby serve                     Serve previously built Gatsby site.
  gatsby info                      Get environment information for debugging and issue reporting
  gatsby clean                     Wipe the local gatsby environment including built assets and cache
  gatsby repl                      Get a node repl with context of Gatsby environment, see (add docs link here)
  gatsby new [rootPath] [starter]  Create new Gatsby project.
  gatsby plugin                    Useful commands relating to Gatsby plugins
  gatsby telemetry                 Enable or disable Gatsby anonymous analytics collection.

Options:
  --verbose                Turn on verbose output                                                                           [boolean] [default: false]
  --no-color, --no-colors  Turn off the color in output                                                                     [boolean] [default: false]
  -h, --help               Show help                                                                                                         [boolean]
  -v, --version            Show version number                                                                                               [boolean]

Did you mean this?
     develop

Maybe we could improve the comprehension of the message so it's clearer?

[shannonbux]

That does look like an improvement since it now says the word "error," which wasn't there before.

However "error Usage: gatsby [options] " still isn't quite as helpful as it could be because the user still has to scan the list with no assistance. It could say something like

gatsby devlop
error: this command doesn't exist. Did you mean `gatsby develop` or another one of the commands below?

Commands:
  gatsby develop                   Start development server. Watches files, rebuilds, and hot reloads if something changes
  gatsby build                     Build a Gatsby project.
  gatsby serve                     Serve previously built Gatsby site.
  gatsby info                      Get environment information for debugging and issue reporting
  gatsby clean                     Wipe the local gatsby environment including built assets and cache
  gatsby repl                      Get a node repl with context of Gatsby environment, see (add docs link here)
  gatsby new [rootPath] [starter]  Create new Gatsby project.
  gatsby plugin                    Useful commands relating to Gatsby plugins
  gatsby telemetry                 Enable or disable Gatsby anonymous analytics collection.

Options:
  --verbose                Turn on verbose output                                                                           [boolean] [default: false]
  --no-color, --no-colors  Turn off the color in output                                                                     [boolean] [default: false]
  -h, --help               Show help                                                                                                         [boolean]
  -v, --version            Show version number                                                                                               [boolean]

or even better, what would it take for us to do what google search does? They just run the thing they think you mean anyway, and tell you they are doing it.

gatsby devlop
running `gatsby develop` now. Press [n] to stop

[shannonbux]

Figma file ready for commenting: https://www.figma.com/file/z81zOLund5Z5FCjnHnUIrN/CLI?node-id=195%3A40