Skip to main content

Commands (Gatsby CLI)


The Gatsby command line tool (CLI) is the main entry point for getting up and running with a Gatsby application and for using functionality including like running a development server and building out your Gatsby application for deployment.

We provide similar documentation available with the gatsby-cli README.

Note on globally installed executables

The Gatsby CLI (gatsby-cli) is packaged as an executable that can be used globally—in fact, this was previously how we recommended using the CLI.

However, global installs of the Gatsby CLI can sometimes lead to subtle bugs in behavior and functionality if the version of the globally installed executable does not match the version of Gatsby in your application. To avoid this, we highly recommend using the package.json script variant of these commands, typically exposed for you with most starters.

For example, if we want to make the gatsby develop command available in our application, we would open up package.json and add a script like so:

  "scripts": {
    "develop": "gatsby develop"

Now we have the develop script available to be used which will use our package’s version of Gatsby, rather than a globally installed version. It can be run by using the name of the script, e.g. npm run develop in this case. Feel free to read more about NPM scripts if you’re interested!

How to use

The Gatsby CLI is available via npm and should be installed globally by running npm install -g gatsby-cli to use it locally.

Run gatsby --help for full help.


gatsby new gatsby-site

See the Gatsby starters docs for a comprehensive list of starters to get started with Gatsby.


Once you’ve installed a Gatsby site, go to the root directory of your project and start the development server:

gatsby develop


Option Description
-H, --host Set host. Defaults to localhost
-p, --port Set port. Defaults to 8000
-o, --open Open the site in your (default) browser for you
-S, --https Use HTTPS

Follow the Local HTTPS guide to find out how you can set up an HTTPS development server using Gatsby.


At the root of a Gatsby site, compile your application and make it ready for deployment:

gatsby build


Option Description
--prefix-paths Build site with link paths prefixed (set pathPrefix in your config)
--no-uglify Build site without uglifying JS bundles (for debugging)
--open-tracing-config-file Tracer configuration file (OpenTracing compatible). See Performance Tracing


At the root of a Gatsby site, serve the production build of your site for testing:

gatsby serve


Option Description
-H, --host Set host. Defaults to localhost
-p, --port Set port. Defaults to 9000
-o, --open Open the site in your (default) browser for you
--prefix-paths Serve site with link paths prefixed (if built with pathPrefix in your gatsby-config.js).


At the root of a Gatsby site, get helpful environment information which will be required when reporting a bug:

gatsby info


Option Description
-C, --clipboard Automagically copy environment information to clipboard


At the root of a Gatsby site, wipe out the cache (.cache folder) and public directories:

gatsby clean

This is useful as a last resort when your local project seems to have issues or content does not seem to be refreshing. Issues this may fix commonly include:

  • Stale data, e.g. this file/resource/etc. isn’t appearing
  • GraphQL error, e.g. this GraphQL resource should be present but is not
  • Dependency issues, e.g. invalid version, cryptic errors in console, etc.
  • Plugin issues, e.g. developing a local plugin and changes don’t seem to be taking effect


Get a Node.js REPL (interactive shell) with context of your Gatsby environment:

gatsby repl

Gatsby will prompt you to type in commands and explore. When it shows this: gatsby >

You can type in a command, such as one of these:










When combined with the GraphQL explorer, these REPL commands could be very helpful for understanding your Gatsby site’s data.

Edit this page on GitHub