forked from netlify/cli
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Moving the usage docs to the docs website
- Loading branch information
Showing
3 changed files
with
57 additions
and
110 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -5,20 +5,53 @@ please read the [code of conduct](CODE_OF_CONDUCT.md). | |
|
|
||
| ## Setup | ||
|
|
||
| > Install NPM on your system: https://docs.npmjs.com/getting-started/installing-node | ||
| Install Node.js 8+ on your system: https://nodejs.org/en/download/ | ||
|
|
||
| ```sh | ||
| $ git clone https://github.com/netlify/netlify-cli | ||
| $ cd netlify-cli | ||
| 1. Clone down the repo | ||
|
|
||
| ```sh-session | ||
| $ git clone [email protected]:netlify/cli.git | ||
| ``` | ||
|
|
||
| 2. Install dependencies | ||
|
|
||
| ```sh-session | ||
| $ npm install | ||
| ``` | ||
|
|
||
| ## Building | ||
| 3. Run CLI locally during development | ||
|
|
||
| ```sh | ||
| $ npm build | ||
| ```sh-session | ||
| $ ./bin/run [command] | ||
| ``` | ||
|
|
||
| When developing, you can use watch mode which will automatically run ava tests: | ||
|
|
||
| ```sh-session | ||
| $ npm run watch | ||
| ``` | ||
|
|
||
| ## Architecture | ||
|
|
||
| The CLI is written using the [oclif](https://oclif.io/) cli framework and the [netlify/js-client](https://github.com/netlify/js-client) open-api derived API client. | ||
|
|
||
| - Commands live in the [`src/commands`](src/commands) folder. | ||
| - The base command class which provides consistent config loading and an API client lives in [`src/base`](src/base). | ||
| - Small utilities and other functionality live in [`src/utils`](src/utils). | ||
|
|
||
| A good place to start is reading the base command README and looking at the commands folder. | ||
|
|
||
| ### Testing | ||
|
|
||
| This repo uses [ava](https://github.com/avajs/ava) for testing. Any files in the `src` directory that have a `.test.js` file extension are automatically detected and run as tests. | ||
|
|
||
| We also test for a few other things: | ||
|
|
||
| - Dependencies (used an unused) | ||
| - Linting | ||
| - Test coverage | ||
| - Must work with Windows + Unix environments. | ||
|
|
||
| ## Pull Requests | ||
|
|
||
| We actively welcome your pull requests. | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -34,19 +34,21 @@ Welcome to the Netlify CLI! The new 2.0 version (now in beta) was rebuilt from t | |
| </details> | ||
| <!-- AUTO-GENERATED-CONTENT:END --> | ||
|
|
||
| ## Install & Setup | ||
| ## Installation | ||
|
|
||
| **Prerequisites** | ||
|
|
||
| - [Node.js](https://nodejs.org/en/download/) 8+. | ||
| - [Netlify User Account](http://app.netlify.com/) | ||
|
|
||
| To install the Netlify CLI, run the following command in your terminal window: | ||
| To install the Netlify CLI, run the following command in your terminal: | ||
|
|
||
| ```sh-session | ||
| npm install netlify-cli@next -g | ||
| ``` | ||
|
|
||
| ## Usage | ||
|
|
||
| After installing the CLI globally, connect the CLI to your Netlify account with the following command: | ||
|
|
||
| ```sh-session | ||
|
|
@@ -55,97 +57,27 @@ netlify login | |
|
|
||
| This will open a browser window, asking you to log in with Netlify and grant access to **Netlify CLI**. This will store your Netlify access token in your home folder, under `~/.netlify/config.json`. | ||
|
|
||
| ## Usage | ||
|
|
||
| ```sh-session | ||
| netlify [command] | ||
|
|
||
| # Run `help` for detailed information about CLI commands | ||
| netlify [command] help | ||
| ``` | ||
|
|
||
| ## Getting Started | ||
|
|
||
| [Netlify's continuous deployment](https://www.netlify.com/docs/continuous-deployment) will automatically deploy new versions of your site when you push commits to your connected Git repository. | ||
|
|
||
| To setup continuous deployment with the CLI, run: | ||
|
|
||
| ```sh-session | ||
| netlify init | ||
| ``` | ||
|
|
||
| In order to connect your repository for continuous deployment, Netlify CLI will need access to create a deploy key and a webhook on the github repository. When you run the command above, you'll be prompted to log in to your GitHub account, which will create an account-level access token. | ||
|
|
||
| The access token will be stored in your home folder, under `.netlify/config.json`. Your login password will never be stored. You can revoke the access token at any time from your GitHub account settings. | ||
|
|
||
|
|
||
| ### Link to an existing site | ||
|
|
||
| Linking to a site tells Netlify CLI which site the current directory should deploy to. To do this, run the following command from the base of your project directory: | ||
|
|
||
| ```sh-session | ||
| netlify link | ||
| ``` | ||
|
|
||
| This will add a `siteId` field to a new file inside your project folder, at `.netlify/state.json`. To unlink your folder from the site, you can remove this field, or you can run the following command from inside the project folder: | ||
|
|
||
| ```sh-session | ||
| netlify unlink | ||
| ``` | ||
|
|
||
|
|
||
| ### Create a new site | ||
|
|
||
| To create a new Netlify site with the CLI, run the `netlify init` command in your site folder. | ||
|
|
||
| ```sh-session | ||
| netlify init | ||
| ``` | ||
|
|
||
| Then Choose "Create & configure a new site in Netlify" | ||
| ### CI and Environment Variables. | ||
|
|
||
| Proceed through the prompts to finish configuring your site. | ||
| The following environment variables can be used to override configuration file lookups and prompts: | ||
|
|
||
| ### Deploying a site | ||
| - `NETLIFY_AUTH_TOKEN` - an access token to use when authenticating commands. **KEEP THIS VALUE PRIVATE** | ||
| - `NETLIFY_SITE_ID` - force the cli to think the cwd is linked to this site id. This can be made public. | ||
|
|
||
| It's also possible to deploy a site manually, without continuous deployment. This method uploads files directly from your local project directory to your site on Netlify. | ||
| ## Getting Started + Docs | ||
|
|
||
| A common use case for this command is when you're using a separate Continuous Integration (CI) tool, deploying prebuilt files to Netlify at the end of the CI tool tasks. | ||
| Please see the getting started guide on our docs website: | ||
|
|
||
| **To do a manual deployment with the CLI run:** | ||
| - [netlify.com/docs/cli](https://www.netlify.com/docs/cli) | ||
|
|
||
| ```sh-session | ||
| netlify deploy | ||
|
|
||
| # Optionally pass in the build directory | ||
| netlify deploy --dir your-build-directory | ||
|
|
||
| # Deploying to production with --prod flag | ||
| netlify deploy --dir your-build-directory --prod | ||
| ``` | ||
|
|
||
| This `deploy` command needs to know which folder to publish, and if your project includes functions, a functions folder to deploy. It will look for this information in three places, in the following order: | ||
|
|
||
| * in flags specified in the command itself | ||
| * in a [netlify.toml file](https://www.netlify.com/docs/netlify-toml-reference) stored at the base of your project directory. | ||
| * in your site settings in the Netlify UI. | ||
|
|
||
|
|
||
| ### Production Deploys | ||
|
|
||
| By default, all `deploys` are set to a draft preview URL. | ||
|
|
||
| To do a manual deploy to production, use the `--prod` flag: | ||
|
|
||
| ```sh-session | ||
| # Deploy build folder to production | ||
| netlify deploy --prod | ||
|
|
||
| # Shorthand -p | ||
| netlify deploy -p | ||
| ``` | ||
|
|
||
| Deploying to production will publish the build directory at the live URL of your Netlify site. | ||
| <!-- TODO: Grab a screenshot to make it pop more --> | ||
|
|
||
| ## Full Command Reference | ||
|
|
||
|
|
@@ -226,32 +158,14 @@ netlify --telemetry-enable | |
|
|
||
| Or edit the `telemetryDisabled` property of the `~/.netlify/config.json` file in your computers root directory. | ||
|
|
||
| ## Contributing | ||
|
|
||
| # Local Development | ||
|
|
||
| 1. Clone down the repo | ||
|
|
||
| ```sh-session | ||
| $ git clone [email protected]:netlify/cli.git | ||
| ``` | ||
|
|
||
| 2. Install dependencies | ||
|
|
||
| ```sh-session | ||
| $ npm install | ||
| ``` | ||
| See [CONTRIBUTING.md](CONTRIBUTING.md) for more info on how to make contributions to this project. | ||
|
|
||
| 3. Run CLI locally during development | ||
| ## License | ||
|
|
||
| ```sh-session | ||
| $ ./bin/run [command] | ||
| ``` | ||
| MIT. See [LICENSE](LICENSE) for more details. | ||
|
|
||
| When developing, you can use watch mode which will automatically run ava tests: | ||
|
|
||
| ```sh-session | ||
| $ npm run watch | ||
| ``` | ||
| [npm-img]: https://img.shields.io/npm/v/netlify-cli.svg | ||
| [npm]: https://npmjs.org/package/netlify-cli | ||
| [travis-img]: https://img.shields.io/travis/netlify/cli/master.svg | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters