Gatsby CLI Quick Reference

Updated on October 27, 2020
Default avatar

By Daniel Stout

Gatsby CLI Quick Reference


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.


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

  1. 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:

  1. 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:

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

Local Development Server

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

  1. 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 and automatically opens in a browser:

  1. gatsby develop -H -p 8888 -o

Generate Production Builds

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

  1. 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:

  1. 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.)

  1. 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 with prefixed paths, and automatically opens in a browser:

  1. gatsby serve -H -p 9999 -prefix-paths -o

Get Environment Info

The info command displays environment information about your Gatsby project.

  1. 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.

  1. 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.

  1. 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.


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:

Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

Learn more about us

About the authors
Default avatar
Daniel Stout


Still looking for an answer?

Ask a questionSearch for more help

Was this helpful?
Leave a comment

This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!

Try DigitalOcean for free

Click below to sign up and get $200 of credit to try our products over 60 days!

Sign up

Join the Tech Talk
Success! Thank you! Please check your email for further details.

Please complete your information!

Get our biweekly newsletter

Sign up for Infrastructure as a Newsletter.

Hollie's Hub for Good

Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.

Become a contributor

Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.

Welcome to the developer cloud

DigitalOcean makes it simple to launch in the cloud and scale up as you grow — whether you're running one virtual machine or ten thousand.

Learn more
DigitalOcean Cloud Control Panel