Get started with Netlify CLI

Netlify's command line interface (CLI) lets you deploy sites or configure continuous deployment straight from the command line. The new 2.0 version of our Node-based CLI was rebuilt from the ground up to help improve the site building experience. (We also continue to support our Go-based CLI, netlifyctl.)

The sections below describe how to perform common tasks with Netlify CLI. You can also access a full command reference online, or get help within Netlify CLI.

Installation

To install Netlify CLI, make sure you have Node.js version 8 or higher, then run this command from any directory in your terminal:

npm install netlify-cli -g

This will install Netlify CLI globally, so you can run netlify commands from any directory. You can check the version and find out some basic information about the tool with the following command:

netlify

Netlify Dev

This feature is in BETA.

Netlify Dev brings the functionality of your Netlify production environment directly to your local machine. This includes custom headers/redirects and environment variables. You can also live share your development server over HTTPS to anywhere in the world.

To give Netlify Dev a try, visit the Netlify Dev page in the netlify-cli repository for more information on how to get started.

As you test things out, visit the Netlify Dev category on Netlify Community to ask questions, share ideas and feature requests, and get inspired. We're looking forward to talking with you!

Authentication

Netlify CLI uses an access token to authenticate with Netlify. You can obtain this token via the command line or in the Netlify UI.

Obtain a token via the command line

To authenticate and obtain an access token via the command line, enter the following command from any directory:

netlify login

This will open a browser window, asking you to log in with Netlify and grant access to Netlify CLI.

Once authorized, Netlify CLI will store your access token in your home folder, under .netlify/config.json. Netlify CLI will use the token in this location automatically for all future commands.

Obtain a token in the Netlify UI

You can generate an access token manually in your Netlify user settings for Personal access tokens.

  1. Under Personal access tokens, select New access token.
  2. Enter a description and select Generate token.
  3. Copy the generated token to your clipboard. Once you navigate from the page, the token cannot be seen again.
  4. Save the token as a NETLIFY_AUTH_TOKEN environment variable in your terminal settings or in the UI of a Continuous Integration (CI) tool.

Cancel access tokens

To revoke your user access token for Netlify CLI, go to your Netlify user Applications settings. The procedure for revoking access depends on how access was granted.

Usage data collection

By default, Netlify collects data on usage of Netlify CLI commands. We do this to improve the reliability and performance of Netlify CLI, and to help drive new features and improvements.

If you'd like to opt out of sending usage data, you can do so by editing the telemetryDisabled property in the .netlify/config.json file in your home folder. You can also do this via the command line:

# opt out of sharing usage data
netlify --telemetry-disable

# allow your usage to help shape development
netlify --telemetry-enable

Continuous deployment

With continuous deployment, Netlify will automatically deploy new versions of your site when you push commits to your connected Git repository. This also facilitates features like Deploy Previews, branch deploys, and split testing. (Some of these features must be enabled in the Netlify UI.)

Automated setup

For repositories stored on GitHub, you can use Netlify CLI to connect your repository by running the following command from your local repository:

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 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; however, this will disable continuous deployment on all sites that were configured with that access token.

Manual setup

For repositories stored on other Git providers, or if you prefer to give more limited, repository-only access, you can connect your repository manually with the --manual flag. From your local repository, run the following command:

netlify init --manual

The tool will prompt you for your deploy settings, then provide you with two items you will need to add to your repository settings with your Git provider:

  • Deploy/access key: Netlify uses this key to fetch your repository via ssh for building and deploying. Sample terminal output reads: 'Give this Netlify SSH public key access to your repository,' and displays a key code. Copy the key printed in the command line, then add it as a deploy key in the repository settings on your Git Provider. The deploy key does not require write access. Note that if you have more than one site connected to a repo, you will need a unique key for each one.

  • Webhook: Your Git provider will send a message to this webhook when you push changes to your repository, triggering a new deploy on Netlify. Sample terminal output reads: 'Configure the following webhook for your repository,' and displays a URL. Copy the webhook address printed in the command line, then add it as the Payload URL for a new webhook in the repository settings on your Git provider. If available, the Content type should be set to application/json. When selecting events to trigger the webhook, Push events will trigger production and branch deploys on watched branches, and Pull/Merge request events will trigger deploy previews.

Manual deploys

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.

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.

To get started with manual deploys, run the following command from your project directory:

netlify deploy

The first time you run the command, Netlify CLI will prompt you to select an existing site or create a new one, linking the site for all future deploys.

The following sections describe the requirements and options for manual deploys.

Deploy directories

The deploy command needs to know which folder to publish. If your project includes serverless functions, it needs to know the location of the functions folder as well. Netlify CLI will look for this information in three places, in the following order:

  • in flags specified in the command itself.
  • in a netlify.toml file stored at the root of your project directory.
  • in your site settings in the Netlify UI.

Here is an example using command flags to set the publish folder and functions folder:

netlify deploy --dir=_site --functions=functions

In both cases, folder paths are relative to the current directory. Note that paths starting with / will begin at the computer's root directory — not the base of your project directory.

Draft and production deploys

By default, the deploy command deploys to a unique draft URL for previewing and testing.

To do a production deploy to your main site URL, use the --prod flag (or -p for short):

netlify deploy --prod

Unbundled JavaScript function deploys

Starting in CLI version 2.7.0, you can deploy unbundled JavaScript functions. This is in addition to the pre-bundled JavaScript functions (using a tool such as Netlify Lambda), JavaScript functions with no dependencies, and functions written in Go, all of which were also deployable in previous versions.

When you manually deploy unbundled JavaScript functions using the netlify deploy command, Netlify CLI looks through a function file's parent folders to find the nearest package.json, and uses that for dependency resolution. It pulls the required dependencies from the associated node_modules folder, and zips them with the function file for deployment.

Note that you need to populate the node_modules folder by running npm install or yarn in the folder containing the package.json before deploying.

An unbundled JavaScript function's package.json does not have to be in the same folder as the function file. For example, both of the following sample folder layouts are supported:

├─ my-serverless-functions
│  └─ foo.js
├─ package.json
└─ node_modules
└─ my-serverless-functions
   ├─ foo.js
   ├─ bar
   │  └─ bar.js
   ├─ package.json
   └─ node_modules

Also, different unbundled JavaScript functions can use different package.json files, based on proximity in the file tree. In the example below, foo.js uses the package.json at the root, while bar.js uses the one inside the bar folder. Note that npm install or yarn must be run in both folders in order to generate the associated node_modules folders.

├─ my-serverless-functions
│  ├─ foo.js
│  └─ bar
│     ├─ bar.js
│     ├─ package.json
│     └─ node_modules
├─ package.json
└─ node_modules

For more details about how this functionality works, visit the repository for the underlying module: @netlify/zip-it-and-ship-it.

If you want to connect your local project or repository to a site already on Netlify, you can skip the initial setup steps above and run the following command from the root of the local directory:

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:

netlify unlink

Alternatively, you can link to a site by finding the site ID in the Netlify UI, then adding it to your local terminal environment:

  1. From the site dashboard, go to Settings > General > Site details > Site information, and copy the value for API ID.
  2. Assign the ID to a NETLIFY_SITE_ID environment variable, in your terminal settings or in the UI of a Continuous Integration (CI) tool.

To print the full debugging output for a command to the terminal, set the DEBUG variable before running the command.

On Mac OS, Linux, and some common Windows terminals, add DEBUG=* to the beginning of the command:

DEBUG=* netlify deploy

If you are using the Windows command prompt (cmd.exe), use set to set the variable:

set DEBUG=* & netlify deploy

In Windows PowerShell, use $env: to set the variable:

$env:DEBUG='*';netlify deploy

Get help

To get usage tips and learn more about available commands from within Netlify CLI, run the following:

netlify help

For more information about a specific command, run help with the name of the command.

netlify help deploy

This also works for sub-commands.

netlify help sites:create

If you have additional questions or ideas for new features, you can start an issue on Netlify CLI's open source repository. You can also visit the Command Line Interface (CLI) category in our Community forum to start or join a conversation. We'd love to hear from you!