Skip to main content

Shannon Soper

UX designer and educational psychology, music, & art fan. Keeps up with her dog's Instagram fans @dgtrwatson.

2 min read · May 22nd 2019

Lions and Tigers and Errors, Oh My! Redesigning the Gatsby CLI

Why did we do this study?

Our command-line interface (CLI) is OK but not great. It will be useful to generate a set of design principles to base the CLI around — but not change what’s working well (which is a lot of it). So let’s do it!

The CLI is the main entry point and interface people have (currently) for Gatsby. Everyone sees it! So it has a huge influence on people’s experience of Gatsby.

We’re going to create a CLI style guide and then implement that style guide, which includes redesigning error messages, introducing gatsby --quiet as a default mode and make more extensive use of the gatsby --verbose flag. To make the CLI easier to design and improve, we’ll implement Ink. To optimize the CLI design, we’ll use the data being collected through our telemetry setup, which collects data about CLI usage (opt out is possible).

What did we learn?

We conducted 4 usability tests with awesome Gatsby users to learn how they do tasks using the Gatsby CLI and how they use error messages to debug their projects. Thanks Simon Koelewijn, Gene Smith, Jonathan Prozzi, and Benjamin Lannon for teaching us how you use the CLI, and thanks to @sidharthachatterjee, @wardpeet, @pieh, @m-allanson, @gillkyle for copiloting the interviews with me and helping turn what we learned into action.

If you want to be part of future usability tests, sign up here.

We also did a thorough search of other CLIs and style guides to learn what we’re doing well and where we might be falling short. Here are resources that informed our knowledge of problems that Gatsby CLI has and possible ways to solve those problems:

What do we need to do?

  1. Crunch some numbers to find out “what are the most common error messages people get?”
  2. Make error messages better, starting with the most common ones
  3. Create a CLI style guide and make sure the CLI starts matching the style guide
  4. Do some other things that will make the CLI easier to use (easier = takes less time to do a task and/or is less frustrating). See issues tagged with topic: cli in the OSS repo!

Want to dive in and help / comment?

Get consensus on the Error Survey RFC & CLI Redesign RFCs start on the changes they suggest!

All the related issues will be tagged with topic: cli in the OSS repo.

List of issues (some already have PRs in progress):

Tagged with cli, uxView all Tags

Enjoyed this post? Receive the next one in your inbox!


Setting up Yarn Workspaces for Theme Development