Netlify’s command line interface (CLI) lets you configure continuous deployment straight from the command line. You can use Netlify CLI to run a local development server that you can share with others, run a local build and plugins, and deploy your site.
To install Netlify CLI, make sure you have Node.js version 10 or later, then run this command from any directory in your terminal:
npm install netlify-cli -g
This installs 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:
Global versus local
Installing Netlify CLI globally means that your system always has the latest version, including any breaking changes. While global installation is appropriate for initial development and experimentation, for managing builds in a continuous integration (CI) environment, use local CLI installation instead.
# Installation in a CI environment
When using Netlify CLI in a continuous integration (CI) environment such as GitHub Actions, CircleCI, or Travis CI, we recommend installing it locally as a development dependency instead of globally. This binds a specific CLI version to your project repository. To install Netlify CLI locally, run the following command from the root directory of your project:
npm install netlify-cli --save-dev
Netlify CLI uses an access token to authenticate with Netlify. You can obtain this token using the command line or in the Netlify UI.
If your team requires you to log in with single sign-on (SSO), your tokens will be denied access to the team by default. You can choose to grant access to the team when you obtain a new token. You must be logged in to the team with SSO to grant access to it.
# Obtain a token with the command line
To authenticate and obtain an access token using the command line, enter the following command from any directory:
This will open a browser window, asking you to log in with Netlify and grant access to Netlify CLI.
Once authorized, Netlify CLI stores your access token in a
config.json global configuration file. The Netlify CLI uses the token in this file automatically for all future commands.
You can find the Netlify CLI global configuration file,
config.json, under your user in these OS-specific locations:
# Obtain a token in the Netlify UI
You can generate an access token manually in your Netlify user settings for Personal access tokens.
Under Personal access tokens, select New access token.
Enter a description.
Select Generate token.
Copy the generated token to your clipboard. Once you navigate from the page, the token cannot be seen again.
Save the token as a
NETLIFY_AUTH_TOKENenvironment 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.
- For access granted using the
netlify logincommand, scroll to the Authorized applications section, and find Netlify CLI. Select Options > Revoke access.
- If you manually created a personal access token, you can find it in the Personal access tokens section. Select Options > Delete personal token.
# 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 CLI
config.json. You can also do this with 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.com, you can use Netlify CLI to connect your repository by running the following command from your local repository:
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 the Netlify CLI
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 using ssh for building and deploying. 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. 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.
# Run a local development environment
Netlify Dev brings the functionality of your Netlify production environment directly to your local machine. It provides a proxy server that includes edge logic for custom headers and redirects, environment variables, Netlify Functions, and Edge Handlers. It automatically detects tools and frameworks like Gatsby, Hugo, Eleventy, Next.js, and more to configure a local development server that mimics the Netlify production environment.
# Get started with Netlify Dev
Before using Netlify Dev, you must authenticate and make sure your site is linked to a Netlify
siteID. You can do that by setting up continuous deployment with
netlify init or linking your site with
To start a local development server for the build tool you’re using, run the following command from the root of your linked repository:
To run a shell command within the Netlify Dev environment, use
netlify dev:exec YOUR_SHELL_COMMAND
# Share a live development server
You can run the following command to share your live development server over HTTPS. This creates a tunnel from your local development server over the internet and allows you to work with collaborators anywhere in the world.
netlify dev --live
Anyone can access the resulting URL as long as the session is open.
# Configuration and more resources
Netlify Dev works without configuration for the majority of users, but you can customize Netlify Dev settings in the
[dev] section of the Netlify configuration file.
For information about Netlify Dev port handling, local Functions development, and more, visit the Netlify Dev page in the netlify-cli repository.
For more Netlify Functions local development options in addition to Netlify Dev, check out our docs on how to simulate and debug Functions in a standalone server.
# Run builds locally
You can run builds in Netlify CLI to mimic the behavior of running a build on Netlify — including Build Plugins. To execute a build locally, run the following command from the root of your linked repository:
If you’d like to get a summary of what a build will do without taking the time to do a full build, you can use the
netlify build --dry
This command will output a list of all the stages of the build and the behaviors that are configured to run during each stage.
You can also run a build in a specific deploy context by using the
--context flag followed by the name of the context.
netlify build --context deploy-preview
This command will run the build as if it is a Deploy Preview, applying any settings specific to that context.
# 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. If builds are stopped, manual deploys are the only way you can update your site.
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:
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
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
netlify deploy command, Netlify CLI looks through a function file to note dependencies. It pulls the required dependencies from the associated
node_modules folder and zips them with the function file for deployment.
package.json does not have to be in the same folder as the function file. To optimize build performance, we recommend specifying function dependencies in the top-level
package.json file in the site’s base directory.
node_modules before deploy
node_modules folders by running
npm install or
yarn in any folder containing
Bundle with esbuild
node_bundler = "esbuild" to your Netlify configuration file
# Link and unlink sites
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:
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:
# Link with an environment variable
Alternatively, you can link to a site by finding the site ID in the Netlify UI, then adding it to your local terminal environment:
- Go to Site settings > General > Site details > Site information, and copy the value for API ID.
- Assign the ID to a
NETLIFY_SITE_IDenvironment variable, in your terminal settings or in the UI of a Continuous Integration (CI) tool.
# Print debugging output
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:
# Get help
To get usage tips and learn more about available commands from within Netlify CLI, run the following:
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 our Support Forums to start or join a conversation. We’d love to hear from you!
Did you find this doc useful?
Your feedback helps us improve our docs.