Introduction

When working with Gatsby.js, we constantly make use of its built-in command line interface (CLI.) This essential tool allows us to do things like creating new projects from starters, launching a dev server with hot-reloading, and generating production builds. Here’s a quick reference guide to help you use it.

Installation

If you haven’t already performed a global installation of gatsby-cli, you will need to do that first:

npm install -g gatsby-cli

With gatsby-cli installed globally, you can now run all of Gatsby’s commands from anywhere on your machine. Now let’s cover the available commands!

Create a New Project

The new command creates a new Gatsby site, installs all of its dependencies, and initializes a new git repository locally with an initial commit.

Running the command with no arguments will prompt for a folder name and optional starter:

gatsby new

Available Arguments:

• site directory: Optional, specifies the installation directory.
• starter: Optional, this can either be a repo URL or a Github username/repo string. If this is not set, gatsby-starter-default is automatically used.

Here’s an example that installs into a my-site folder, and uses gatsby-starter-blog as the starter:

gatsby new my-site gatsbyjs/gatsby-starter-blog

Local Development Server

The develop command starts up a local development server with hot-reloading.

gatsby develop

Available Options:

• -H, --host: Set host URL/IP. Defaults to localhost.
• -p, --port: Set application port. Defaults to 8000.
• -o, --open: Automatically opens the site in your (default) browser.
• -S, --https: Use HTTPS. (More info on that can be found here.)

Here’s an additional example that runs at http://0.0.0.0:8888 and automatically opens in a browser:

gatsby develop -H 0.0.0.0 -p 8888 -o

Generate Production Builds

The build command compiles your site for production-ready deployments.

gatsby build

Available Options:

• -prefix-paths: Builds the site with link paths prefixed. (But only if you’ve set pathPrefix in your Gatsby config!)
• -no-uglify: Builds the site without uglifying JavaScript (Useful for debugging.)
• -open-tracing-config-file: Sets the tracer configuration file for an OpenTracing tool. (More info at Gatsby’s Performance Tracing page.)

Here’s an example that generates a build with prefixed paths and uglify disabled:

gatsby build -prefix-paths -no-uglify

Serve Production Builds Locally

The serve command runs production builds locally, which can be helpful for testing and debugging. (You must run the build command prior to running this, of course.)

gatsby serve

Available Options:

• -H, --host: Set host address. Defaults to localhost.
• -p, --port: Set application port. Defaults to 9000.
• -o, --open: Automatically opens the site in your (default) browser.
• -prefix-paths: Serves the site with prefixed paths, if you set a pathPrefix value in your Gatsby config.

Here’s an an example that serves a production build at http://10.0.0.1:9999 with prefixed paths, and automatically opens in a browser:

gatsby serve -H 10.0.0.1 -p 9999 -prefix-paths -o

Get Environment Info

The info command displays environment information about your Gatsby project.

gatsby info

Available Option:

• -C, --clipboard: Automatically copies the info to your clipboard.

Running this command returns an object including your OS, CPU type, Yarn/npm versions, installed languages, browsers, and installed npm packages.

NOTE: This info is required when submitting an official bug report to Gatsby.

Remove Stale Caches/Builds

The clean command deletes the .cache and public directories from your project root.

gatsby clean

While this command is probably not something you will use too often, it’s still a handy shortcut to know about! Sometimes strange caching issues happen, and this is a fast and safe way to clear it. (It’s easier to type two words vs. typing out two folder deletion commands, and there’s no risk of accidentally deleting the wrong folder.)

REPL Access

The repl command opens access to Gatsby’s interactive REPL (Read-Eval-Print-Loop) shell.

gatsby repl

The use of this command is far beyond the scope of a quick reference article, but you can find full usage details in the Gatsby documentation’s REPL page.

Conclusion

Hopefully this short guide will help you navigate the Gatsby CLI with ease. It’s important to be comfortable with it, since you will use it so frequently in your Gatsby projects!

More information is also available, if needed:

• The Gatsby CLI page in the official documentation is great!
• The Github repo for gatsby-cli is useful to keep up with updates/changes.
• The Gatsby team also created a printable cheat sheet, which includes the most-used CLI commands.