Recommended for you: Functions
Use serverless functions to run on-demand, server-side code without having to manage a dedicated server.
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.
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.
To install Netlify CLI, make sure you have Node.js version 18.14.0 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:
netlify
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.
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
For CI environments, we also recommend using a lock file to guarantee reproducible builds and relying on an automated tool like renovate or dependabot to manage Netlify CLI version updates.
Netlify CLI uses an access token to authenticate with Netlify. You can obtain this token using the command line or in the Netlify UI.
SAML SSO
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.
To authenticate and obtain an access token using 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 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.
config.json
locationYou can find the Netlify CLI global configuration file, config.json
, under your user in these OS-specific locations:
Library/Preferences/netlify/config.json
.config/netlify/config.json
AppData\Roaming\netlify\Config\config.json
You can generate a personal access token (PAT) manually in your Netlify user settings:
NETLIFY_AUTH_TOKEN
environment variable in your terminal settings or in the UI of a Continuous Integration (CI) tool.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.
netlify login
command, scroll to the Authorized applications section, and find Netlify CLI. Select .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
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.)
To connect your local project to an existing Netlify site, use link
If your site already has continuous deployment set up and you just want to associate a project on your local machine to an existing site on Netlify, use netlify link
instead of netlify init
or netlify init --manual
.
For repositories stored on GitHub.com, 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 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.
For repositories stored on GitLab, Bitbucket, or Azure DevOps, you can connect your repository manually with the --manual
flag.
For repositories on GitHub, you can also connect your repository manually, if you prefer to give more limited, repository-only access for your repositories on GitHub.
From your local repository, run the following command:
netlify init --manual
The Netlify CLI will prompt you to set your deploy settings and then provide you with a deploy/access key and a webhook URL. You’ll need to manually add the key and webhook URL to your Git provider.
Netlify uses a deploy or access key to fetch your repository using ssh for building and deploying. The deploy key does not require write access.
Copy the key printed in the command line, then add it to your Git provider.
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 the URL and webhook details to your Git provider. If available, the Content type should be set to application/json
.
GitHub, GitLab, or Bitbucket. Add the webhook address as the Payload URL for a new webhook in your repository’s settings. 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.
Azure DevOps. In your project’s settings under Service hooks, add webhooks for these Azure DevOps events using the Netlify webhook address as the Payload URL:
Ensure that you set webhooks for your repository with the default [Any]
branch setting. Once configured, these webhook events can trigger production and branch deploys on your watched branches.
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, and Netlify Functions. 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.
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 netlify link
.
To start a local development server for the build tool you’re using, run the following command from the root of your linked repository:
netlify dev
By default, Netlify Dev runs your project using the configuration and environment variables set for local development with the Netlify CLI. For environment variables, that means those with values set for dev
or all
deploy contexts. You can use the --context
flag to run your project with a different deploy context’s settings and variables.
netlify dev --context production
Note that environment variables apply to all scopes when running netlify dev
.
To run a shell command within the Netlify Dev environment, use exec
:
netlify dev:exec YOUR_SHELL_COMMAND
By default, netlify dev
starts an HTTP server. If you require HTTPS, you can configure a certificate and key file for
use by netlify dev
in your netlify.toml
:
[dev]
[dev.https]
certFile = "cert.pem"
keyFile = "key.pem"
Self-signed certificates require extra configuration
If you’re using a self-signed certificate, you might need to configure your browser to accept it when running on localhost
. To enable this setting for Chrome, visit chrome://flags/#allow-insecure-localhost
in your browser.
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.
Netlify Dev attempts to detect the site generator or build command that your project uses and run these on your behalf, while adding other development utilities. If you have a JavaScript project, it uses simple heuristics to look for the best package.json
script to run for you, so you can use the full flexibility of npm scripts.
You also have the option to override framework detection, if needed.
The number of frameworks that Netlify Dev can detect is growing but, if the framework you use is not yet supported, you can instruct Netlify Dev to run the project on your behalf. Configure your project’s build command, port, and publish directory with the [dev]
block in your netlify.toml
file.
# sample dev block in the toml
# note: each of these fields are optional and should only be used if you need an override
[dev]
command = "yarn start" # Command to start your dev server
targetPort = 3000 # The port for your application server, framework or site generator
port = 8888 # The port that the netlify dev will be accessible on
publish = "dist" # If you use a _redirect file, provide the path to your static content folder
If the CLI detects your project incorrectly or detects multiple frameworks, you can specify a framework
option to test only one detector against your project.
[dev]
framework = "create-react-app" # or "#static" to force a static server
Possible values of framework
:
#auto
(default) to check all available frameworks..json
file for that framework in the Netlify Build repository.#static
for a static file server#custom
to use the command
option to run an app server and targetPort
option to connect to itWhen you use Netlify Dev, you may encounter a few different ports — especially if your project uses a static site generator like Gatsby that has its own dev server. Keep the following in mind when working with Netlify Dev:
netlify dev
. Netlify Dev will connect to that port and route requests successfully to the site generator along with the rest of the local Netlify environment.netlify dev
.As for which port to use while doing local development in Netlify Dev, search for this box in your console output and use the port mentioned:
┌──────────────────────────────────────────────────────────────┐
│ │
│ [Netlify Dev] Server now ready on http://localhost:8888 │
│ │
└──────────────────────────────────────────────────────────────┘
Netlify Dev allows you to specify custom ports using the following parameters as flags or in a Netlify configuration file (netlify.toml
):
targetPort
: the port for your application server, framework, or site generatorport
: the port for the Netlify Dev server that you will open in the browserNetlify Dev tries to acquire these ports but if they are already in use by another application, it will throw an error and let you know.
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 on how to create and serve functions locally with the Netlify CLI, review our Manage Functions with Netlify CLI documentation.
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:
netlify build
The command will build your project using environment variables set in netlify.toml
and those set using the Netlify UI, CLI, or API. Note that environment variables apply to all scopes when running netlify build
locally.
Make sure your Node.js versions match
If you are using the Netlify CLI to run a build locally, make sure the Node.js version installed in your local environment matches the version set for your build on Netlify. If the versions don’t match, you may encounter errors.
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 --dry
flag:
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.
The default deploy context is production
but you can also use the --context
flag to run a build for a different deploy context.
netlify build --context deploy-preview
This command will run the build as if it is a Deploy Preview, applying any settings and environment variable values specific to that context.
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:
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.
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:
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.
By default, the deploy
command deploys to a unique draft URL for previewing and testing.
The default draft URL uses random alphanumeric characters for the subdomain. To customize the subdomain of your draft URL with a unique string, use the --alias
flag with the deploy
command.
netlify deploy --alias=YOUR_ALIAS
Avoid using --alias
with any of your branch names
Ensure the string you use after --alias=
doesn’t match any existing branch names from your site’s repository. The --alias
flag is designed to support draft deploy URLs only and doesn’t create a branch deploy or support our branch subdomains feature. Learn more about this flag in the CLI reference docs.
To do a production deploy to your main site URL, use the --prod
flag (or -p
for short):
netlify deploy --prod
Before manually deploying TypeScript or JavaScript functions with Netlify CLI, populate node_modules
folders with your dependencies by running the following command in any folder containing package.json
.
npm install
yarn
When you deploy TypeScript or JavaScript functions using the netlify deploy
command, Netlify CLI parses each function file to note its dependencies. For each function, the CLI then pulls the required dependencies from the associated node_modules
folder and zips them with the function file for deployment.
If your site isn’t already on Netlify, use init
or deploy
instead
If your site is not already on Netlify, you need to either set up continuous deployment or manually deploy the site before you can link your local project to it. If you use the Netlify CLI to deploy your site, the CLI will automatically link the project on your local machine to the site on Netlify.
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:
NETLIFY_SITE_ID
environment variable, in your terminal settings or in the UI of a Continuous Integration (CI) tool.You can create and update site environment variables stored on Netlify with the CLI’s env
command. Any changes made using the CLI will be reflected in the Netlify UI. Environment variable changes require a build and deploy to take effect.
By default, the Netlify CLI deploy context is the local development context (dev
). Unless a different deploy context is specified, CLI commands will get and use variables that have values set specifically for use with the dev
deploy context and variables that have a single value for use across all
deploy contexts.
Use the --context
and --scope
flags with your CLI commands to set contextual or scope values, or to filter results. You can use both flags in the same command, for example:
netlify env:set API_KEY someValue --scope functions --context production branch-deploy
netlify env:list --scope builds --context deploy-preview
To create or update a site environment variable on Netlify, use env:set
with the key followed by a space and then the value. You can only set one value at a time, but you can specify multiple deploy contexts and scopes in a space-separated list (no commas) using the --context
and --scope
flags.
netlify env:set API_KEY someValue
netlify env:set ANOTHER_API_KEY someValue --scope builds --context dev
If you omit the --scope
or --context
flags when running the env:set
command, the variable is set to all scopes and with the same value for all deploy contexts.
To set one value for production
and deploy-preview
and another value for a branch named staging
, run the command twice:
netlify env:set API_KEY someValue --context production deploy-preview
netlify env:set API_KEY someOtherValue --context branch:staging
You can also import environment variables from a .env
file into Netlify using env:import
followed by the filename. The imported variables are set to all scopes and with the same value for all deploy contexts.
netlify env:import .env
To copy environment variables from one site to another, use env:clone
.
netlify env:clone --to destinationSiteId --from sourceSiteID
If you are using environment variable secrets with Netlify’s Secrets Controller, you can flag that an environment variable value is secret using the --secret
flag when creating or modifying a value.
netlify env:set API_KEY someValue --context production --secret
To retrieve a list of site environment variables stored on Netlify, use env:list
. The CLI gets all variables that have values set for local development with the Netlify CLI (deploy contexts dev
or all
) and outputs a list of keys with an option to display their values.
You can request other contextual values using the --context
flag and filter the list using the --scope
flag. You can also use the --json
and --plain
flags to retrieve the list in JSON or plain text format, which can be helpful if you want to copy the values into a .env
file locally.
The list will only include shared environment variables if the command is run by a team Owner.
This list will not include raw, unmasked values of any environment variables marked as secret unless the --context
is dev
. Review the environment variable secrets policy for more details on the access restrictions.
netlify env:list
netlify env:list --context branch:staging
netlify env:list --scope functions
netlify env:list --plain
To retrieve an individual environment variable’s value, use env:get
. The CLI gets the values set for local development with the Netlify CLI (deploy contexts dev
or all
). You can use the --context
flag to retrieve a value from another context or the --scope
flag to retrieve a value only if the variable is available to a specific scope.
netlify env:get API_KEY
netlify env:get API_KEY --context production
To delete environment variables from Netlify, use env:unset
. This command deletes the specified variable and its values from all deploy contexts. Once unset, these variables will no longer be stored on Netlify or appear in the UI. You can use the --context
flag to delete one value from a specific deploy context instead.
netlify env:unset API_KEY
netlify env:unset API_KEY --context dev
Commands execute from the workspace root
Starting with Netlify CLI version 16, all commands execute from the workspace root to mimic the build system behavior on Netlify. The workspace root is the directory that contains the highest-level package.json
in your monorepo. Make sure any paths declared in netlify.toml
are absolute paths relative to the base directory.
A monorepo is a repository that contains multiple sites or apps, each in its own subdirectory.
When you use the Netlify CLI, Netlify automatically scans the repository to detect if you are using a monorepo. If you are, the Netlify CLI will ask you to specify the site to run a command on and you can choose from the list of detected sites.
You also have the option to manually set the following flag:
--filter
: to specify which site in your monorepo to use for a command. You can use the package name or the path to the package. This way you can run commands directly from the repository root for all projects in your monorepo.
netlify dev --filter website
netlify dev --filter packages/website
Note that selecting a site with the Netlify CLI only applies to the command you are running and doesn’t influence the build settings in the Netlify UI. Learn more about how to set up a site from a monorepo.
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
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 our Support Forums to start or join a conversation. We’d love to hear from you!
Recommended for you: Functions
Use serverless functions to run on-demand, server-side code without having to manage a dedicated server.
Your feedback helps us improve our docs.