Commands (Gatsby CLI)
The Gatsby command line interface (CLI) is the main tool you use to initialize, build and develop Gatsby sites.
How to use gatsby-cli
To use the Gatsby CLI you must either:
- Install it globally with
npm install -g gatsby-cli, where you execute commands with the syntaxgatsby new, or - Run commands directly with
npx, where you execute commands with the syntaxnpx gatsby new
Useful Gatsby CLI commands are also pre-defined instarters asrun scripts.
API commands
All the following documentation is available in the tool by runninggatsby --help.
new
Runs an interactive shell with a prompt that helps you set up aCMS, styling system and plugins if you wish.
To create a new site with the prompt, execute:
You can also skip the prompt and clone a starter directly from GitHub. For example, to clone a newgatsby-starter-blog, execute:
The first argument (e.g.my-new-blog) is the name of your site, and the second argument is the GitHub URL of the starter you want to clone.
Note: The site name should only consist of letters and numbers. If you specify a
.,./or a<space>in the name,gatsby newwill throw an error.
develop
Compiles and serves a development build of your site that reflects your source code changes in the browser in real time. Should be run from the root of your project.
Options include:
| Option | Description |
|---|---|
-H,--host | Set host. Defaults tolocalhost |
-p,--port | Set port. Defaults toenv.PORT or8000 |
-o,--open | Open the site in your (default) browser for you |
-S,--https | Use HTTPS |
--inspect | Opens a port for debugging |
--verbose | Turn on verbose output |
To set up HTTPS, follow theLocal HTTPS guide.
To include a URL you can access from other devices on the same network, execute:
You will see this output:
You can use the “On Your Network” URL to access your site within your network.
build
Compiles your site for production so it can be deployed. Should be run from the root of your project.
Options include:
| Option | Description |
|---|---|
--prefix-paths | Build site with link paths prefixed (setpathPrefix in your config) |
--no-uglify | Build site without uglifying JS bundles (for debugging) |
--profile | Build site with react profiling. SeeProfiling Site Performance with React Profiler |
--open-tracing-config-file | Tracer configuration file (OpenTracing compatible). SeePerformance Tracing |
--graphql-tracing | Trace (see above) every graphql resolver, may have performance implications. |
--no-color,--no-colors | Disables colored terminal output |
--verbose | Turn on verbose output |
In addition to these build options, there are some optionalbuild environment variables for more advanced configurations that can adjust how a build runs. For example, settingCI=true as an environment variable will tailor output fordumb terminals.
serve
Serves the production build of your site for testing prior to deployment. Should be run from the root of your project.
Options include:
| Option | Description |
|---|---|
-H,--host | Set host. Defaults tolocalhost |
-p,--port | Set port. Defaults to9000 |
-o,--open | Open the site in your default browser for you |
--prefix-paths | Serve site with link paths prefixed (if built withpathPrefix in yourgatsby-config file). |
info
Show helpful environment information which is required in bug reports. Should be run from the root of your project.
Options include:
| Option | Description |
|---|---|
-C,--clipboard | Copy environment information to your clipboard |
clean
Delete the.cache andpublic directories. Should be run from the root of your project.
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
repl
Open a Node.js REPL (interactive shell) with context of your Gatsby environment. Should be run from the root of your project.
Gatsby will prompt you to type in commands and explore. When it shows this:gatsby >, you can type in one of these commands to see their values in real time:
babelrccomponentsdataPathsgetNodes()nodespagesschemasiteConfigstaticQueries
To exit the REPL:
- Press
Ctrl+CorCtrl+Dtwice, or - Type
.exitand pressEnter
When combined with theGraphQL explorer, these REPL commands could be very helpful for understanding your Gatsby site’s data.
Disabling colored output
In addition to the explicit--no-color option, the CLI respects the presence of theNO_COLOR environment variable (seeno-color.org).
How to change your default package manager for your next project?
When you usegatsby new for the first time to create a new project, you are asked to choose your default package manager between yarn and npm.
Once you’ve made your choice, the CLI won’t ask for your preference again for any subsequent project. If you want to change the preference, there are two ways to change the default package manager for your next project:
Using options command from CLI
You can use thegatsby options command to change the default package manager.
| Argument | Description |
|---|---|
| key | Set the package managergatsby new is using. choices:pm,package-manager |
| value | Set the package manager asnpm oryarn. |
To set the default package manager asyarn you’d run:
Editing the config file
You can also manually change the default package manager by editing the config file created automatically by the CLI.This file is available on your system at:~/.config/gatsby/config.json
In it you’re going to see something like this.
Edit yourpackageManager value, save and you’re good to go for your next project usinggatsby new.