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 | Lets you create new Gatsby apps using
|
6 | [Gatsby starters](https://www.gatsbyjs.org/docs/gatsby-starters/). It also lets you run commands on sites. The tool runs code from the `gatsby` package installed locally.
|
7 |
|
8 | The Gatsby CLI (`gatsby-cli`) is packaged as an executable that can be used globally. 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.
|
9 |
|
10 | Run `gatsby --help` for full help.
|
11 |
|
12 | You can also use the `package.json` script variant of these commands, typically exposed _for you_ with most [starters](/docs/starters/). 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=package.json
|
15 | {
|
16 | "scripts": {
|
17 | "develop": "gatsby develop"
|
18 | }
|
19 | }
|
20 | ```
|
21 |
|
22 | ## CLI Commands
|
23 |
|
24 | 1. [new](#new)
|
25 | 2. [develop](#develop)
|
26 | 3. [build](#build)
|
27 | 4. [serve](#serve)
|
28 | 5. [clean](#clean)
|
29 | 6. [plugin](#plugin)
|
30 | 7. [info](#info)
|
31 | 8. [repl](#repl)
|
32 |
|
33 | ### `new`
|
34 |
|
35 | ```
|
36 | gatsby new [<site-name> [<starter-url>]]
|
37 | ```
|
38 |
|
39 | | Argument | Description |
|
40 | | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
41 | | site-name | Your Gatsby site name, which is also used to create the project directory. |
|
42 | | starter-url | A Gatsby starter URL or local file path. Defaults to [gatsby-starter-default](https://github.com/gatsbyjs/gatsby-starter-default); see the [Gatsby starters](/docs/gatsby-starters/) docs for more information. |
|
43 |
|
44 | > Note: The `site-name` should only consist of letters and numbers. If you specify a `.`, `./` or a `<space>` in the name, `gatsby new` will throw an error.
|
45 |
|
46 | #### Examples
|
47 |
|
48 | - Create a Gatsby site named `my-awesome-site`, using the [default starter](https://github.com/gatsbyjs/gatsby-starter-default):
|
49 |
|
50 | ```bash
|
51 | gatsby new my-awesome-site
|
52 | ```
|
53 |
|
54 | - Create a Gatsby site named `my-awesome-blog-site`, using [gatsby-starter-blog](https://www.gatsbyjs.org/starters/gatsbyjs/gatsby-starter-blog/):
|
55 |
|
56 | ```bash
|
57 | gatsby new my-awesome-blog-site https://github.com/gatsbyjs/gatsby-starter-blog
|
58 | ```
|
59 |
|
60 | - If you leave out both of the arguments, the CLI will run an interactive shell asking for these inputs:
|
61 |
|
62 | ```bash
|
63 | gatsby new
|
64 | ? What is your project called? › my-gatsby-project
|
65 | ? What starter would you like to use? › - Use arrow-keys. Return to submit.
|
66 | ❯ gatsby-starter-default
|
67 | gatsby-starter-hello-world
|
68 | gatsby-starter-blog
|
69 | (Use a different starter)
|
70 | ```
|
71 |
|
72 | See the [Gatsby starters docs](https://www.gatsbyjs.org/docs/gatsby-starters/) for more details.
|
73 |
|
74 | ### `develop`
|
75 |
|
76 | At the root of a Gatsby app run `gatsby develop` to start the Gatsby
|
77 | development server.
|
78 |
|
79 | #### Options
|
80 |
|
81 | | Option | Description | Default |
|
82 | | :-------------: | ----------------------------------------------- | :---------: |
|
83 | | `-H`, `--host` | Set host. | `localhost` |
|
84 | | `-p`, `--port` | Set port. | `8000` |
|
85 | | `-o`, `--open` | Open the site in your (default) browser for you | |
|
86 | | `-S`, `--https` | Use HTTPS | |
|
87 |
|
88 | Follow the [Local HTTPS guide](https://www.gatsbyjs.org/docs/local-https/)
|
89 | to find out how you can set up an HTTPS development server using Gatsby.
|
90 |
|
91 | ### `build`
|
92 |
|
93 | At the root of a Gatsby app run `gatsby build` to do a production build of a site.
|
94 |
|
95 | #### Options
|
96 |
|
97 | | Option | Description | Default |
|
98 | | :--------------------------: | ---------------------------------------------------------------------------------------------------------- | :-----: |
|
99 | | `--prefix-paths` | Build site with link paths prefixed (set pathPrefix in your config) | `false` |
|
100 | | `--no-uglify` | Build site without uglifying JS bundles (for debugging) | `false` |
|
101 | | `--open-tracing-config-file` | Tracer configuration file (OpenTracing compatible). See https://www.gatsbyjs.org/docs/performance-tracing/ | |
|
102 | | `--no-color`, `--no-colors` | Disables colored terminal output | `false` |
|
103 |
|
104 | ### `serve`
|
105 |
|
106 | At the root of a Gatsby app run `gatsby serve` to serve the production build of the site
|
107 |
|
108 | #### Options
|
109 |
|
110 | | Option | Description |
|
111 | | :--------------: | ---------------------------------------------------------------------------------------- |
|
112 | | `-H`, `--host` | Set host. Defaults to localhost |
|
113 | | `-p`, `--port` | Set port. Defaults to 9000 |
|
114 | | `-o`, `--open` | Open the site in your (default) browser for you |
|
115 | | `--prefix-paths` | Serve site with link paths prefixed (if built with pathPrefix in your gatsby-config.js). |
|
116 |
|
117 | ### `clean`
|
118 |
|
119 | 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:
|
120 |
|
121 | - Stale data, e.g. this file/resource/etc. isn't appearing
|
122 | - GraphQL error, e.g. this GraphQL resource _should_ be present but is not
|
123 | - Dependency issues, e.g. invalid version, cryptic errors in console, etc.
|
124 | - Plugin issues, e.g. developing a local plugin and changes don't seem to be taking effect
|
125 |
|
126 | ### `plugin`
|
127 |
|
128 | Run commands pertaining to gatsby plugins.
|
129 |
|
130 | #### `docs`
|
131 |
|
132 | `gatsby plugin docs`
|
133 |
|
134 | Directs you to documentation about using and creating plugins.
|
135 |
|
136 | ### `info`
|
137 |
|
138 | At the root of a Gatsby site run `gatsby info` to get helpful environment information which will be required when reporting a bug.
|
139 |
|
140 | #### Options
|
141 |
|
142 | | Option | Description | Default |
|
143 | | :-----------------: | ------------------------------------------------------- | :-----: |
|
144 | | `-C`, `--clipboard` | Automagically copy environment information to clipboard | `false` |
|
145 |
|
146 | ### `repl`
|
147 |
|
148 | Get a node repl with context of Gatsby environment
|
149 |
|
150 |
|