| 1 | # gatsby-cli
|
| 2 |
|
| 3 | The Gatsby command line interface (CLI). It is used to perform common functionality, such as creating a Gatsby application based on a starter, spinning up a hot-reloading local development server, and more!
|
| 4 |
|
| 5 | Let's you create new Gatsby apps using
|
| 6 | [Gatsby starters](https://www.gatsbyjs.org/docs/gatsby-starters/).
|
| 7 |
|
| 8 | 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.
|
| 9 |
|
| 10 | 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.
|
| 11 |
|
| 12 | For example, if we want to make the [`gatsby develop`](#develop) command available in our application, we would open up `package.json` and add a script like so:
|
| 13 |
|
| 14 | ```json:title
|
| 15 | {
|
| 16 | "scripts": {
|
| 17 | "develop": "gatsby develop"
|
| 18 | }
|
| 19 | }
|
| 20 | ```
|
| 21 |
|
| 22 | We can now use the `develop` script tied to our app's version of Gatsby, rather than a globally installed version. This script can be invoked by using the name of the script, e.g. `npm run develop` in this case. Feel free to [read more about NPM scripts](https://docs.npmjs.com/misc/scripts) if you're interested!
|
| 23 |
|
| 24 | ## How to use
|
| 25 |
|
| 26 | The Gatsby CLI is available via [npm](https://www.npmjs.com/) and should be installed globally by running `npm install -g gatsby-cli` to use it locally.
|
| 27 |
|
| 28 | Run `gatsby --help` for full help.
|
| 29 |
|
| 30 | ## Commands
|
| 31 |
|
| 32 | ### `new`
|
| 33 |
|
| 34 | `gatsby new gatsby-site`
|
| 35 |
|
| 36 | See the [Gatsby starters docs](https://www.gatsbyjs.org/docs/gatsby-starters/)
|
| 37 | for more.
|
| 38 |
|
| 39 | ### `develop`
|
| 40 |
|
| 41 | At the root of a Gatsby app run `gatsby develop` to start the Gatsby
|
| 42 | development server.
|
| 43 |
|
| 44 | #### Options
|
| 45 |
|
| 46 | | Option | Description | Default |
|
| 47 | | :-------------: | ----------------------------------------------- | :---------: |
|
| 48 | | `-H`, `--host` | Set host. | `localhost` |
|
| 49 | | `-p`, `--port` | Set port. | `8000` |
|
| 50 | | `-o`, `--open` | Open the site in your (default) browser for you | |
|
| 51 | | `-S`, `--https` | Use HTTPS | |
|
| 52 |
|
| 53 | Follow the [Local HTTPS guide](https://www.gatsbyjs.org/docs/local-https/)
|
| 54 | to find out how you can set up an HTTPS development server using Gatsby.
|
| 55 |
|
| 56 | ### `build`
|
| 57 |
|
| 58 | At the root of a Gatsby app run `gatsby build` to do a production build of a site.
|
| 59 |
|
| 60 | #### Options
|
| 61 |
|
| 62 | | Option | Description | Default |
|
| 63 | | :--------------------------: | ---------------------------------------------------------------------------------------------------------- | :-----: |
|
| 64 | | `--prefix-paths` | Build site with link paths prefixed (set pathPrefix in your config) | `false` |
|
| 65 | | `--no-uglify` | Build site without uglifying JS bundles (for debugging) | `false` |
|
| 66 | | `--open-tracing-config-file` | Tracer configuration file (OpenTracing compatible). See https://www.gatsbyjs.org/docs/performance-tracing/ | |
|
| 67 |
|
| 68 | ### `serve`
|
| 69 |
|
| 70 | At the root of a Gatsby app run `gatsby serve` to serve the production build of the site
|
| 71 |
|
| 72 | #### Options
|
| 73 |
|
| 74 | | Option | Description |
|
| 75 | | :--------------: | ---------------------------------------------------------------------------------------- |
|
| 76 | | `-H`, `--host` | Set host. Defaults to localhost |
|
| 77 | | `-p`, `--port` | Set port. Defaults to 9000 |
|
| 78 | | `-o`, `--open` | Open the site in your (default) browser for you |
|
| 79 | | `--prefix-paths` | Serve site with link paths prefixed (if built with pathPrefix in your gatsby-config.js). |
|
| 80 |
|
| 81 | ### `clean`
|
| 82 |
|
| 83 | At the root of a Gatsby app run `gatsby clean` to wipe out the cache (`.cache` folder) and `public` directories. 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:
|
| 84 |
|
| 85 | - Stale data, e.g. this file/resource/etc. isn't appearing
|
| 86 | - GraphQL error, e.g. this GraphQL resource _should_ be present but is not
|
| 87 | - Dependency issues, e.g. invalid version, cryptic errors in console, etc.
|
| 88 | - Plugin issues, e.g. developing a local plugin and changes don't seem to be taking effect
|
| 89 |
|
| 90 | ### `plugin`
|
| 91 |
|
| 92 | Run commands pertaining to gatsby plugins.
|
| 93 |
|
| 94 | #### `docs`
|
| 95 |
|
| 96 | `gatsby plugin docs`
|
| 97 |
|
| 98 | Directs you to documentation about using and creating plugins.
|
| 99 |
|
| 100 | ### `info`
|
| 101 |
|
| 102 | At the root of a Gatsby site run `gatsby info` to get helpful environment information which will be required when reporting a bug.
|
| 103 |
|
| 104 | #### Options
|
| 105 |
|
| 106 | | Option | Description | Default |
|
| 107 | | :-----------------: | ------------------------------------------------------- | :-----: |
|
| 108 | | `-C`, `--clipboard` | Automagically copy environment information to clipboard | `false` |
|
| 109 |
|
| 110 | ### `repl`
|
| 111 |
|
| 112 | Get a node repl with context of Gatsby environment
|
| 113 |
|
| 114 |
|