---
title: "Get started with Netlify CLI"
description: "Install our CLI (command line interface) and use it to run a local development environment, deploy your site, manage environment variables, and more."
---

Netlify's command line interface (CLI) lets you configure [continuous deployment](#continuous-deployment) straight from the command line. You can use Netlify CLI to [run a local development server](/api-and-cli-guides/cli-guides/local-development) that you can share with others, [run a local build and plugins](#run-builds-locally), and [deploy your site](#manual-deploys).

The sections below describe how to perform common tasks with Netlify CLI. You can also access a [full command reference](https://cli.netlify.com) online, or get help [within Netlify CLI](/api-and-cli-guides/cli-guides/get-started-with-cli#get-help).

## Installation

To install Netlify CLI, make sure you have [Node.js](https://nodejs.org/en/download/) version 18.14.0 or later.

Then, run this command from any directory in your terminal:

```bash
npm install -g netlify-cli
```

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:

```bash
netlify
```

### Tip - Global versus local

When using Netlify CLI in a continuous integration (CI) environment, use [local CLI installation](#installation-in-a-ci-environment) to maintain reproducible builds and avoid surprises due to breaking changes.

When developing locally, either local or global installation is appropriate.

### 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:

```bash
npm install netlify-cli --save-dev
```

For CI environments, we also recommend using a [lock file](https://docs.npmjs.com/cli/v7/commands/npm-ci) to guarantee reproducible builds and relying on an automated tool like [Renovate](https://github.com/renovatebot/renovate) or [Dependabot](https://dependabot.com/) to manage Netlify CLI version updates.

## Authentication

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

### Tip - SAML SSO

If your team requires you to log in with [single sign-on (SSO)](/manage/security/secure-netlify-access/configure-team-saml-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:

```bash
netlify login
```

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

![cli authorize ui](/images/cli-authorize-ui.png)

Once authorized, Netlify CLI stores your access token in a [`config.json`](#config-json-location) global configuration file. The Netlify CLI uses the token in this file automatically for all future commands.

#### `config.json` location

You can find the Netlify CLI global configuration file, `config.json`, under your user in these OS-specific locations:

- macOS: `Library/Preferences/netlify/config.json`
- Linux: `.config/netlify/config.json`
- Windows: `AppData\Roaming\netlify\Config\config.json`

### Obtain a token in the Netlify UI

You can generate a personal access token (PAT) manually in your Netlify user settings:

1. Go to 
### NavigationPath Component:

Applications > Personal access tokens
.
2. Select **New access token**.
3. Enter a descriptive name to help you remember what the token will be used for.
4. Select **Allow access to my SAML-based Netlify team** to authorize access to your SAML-based team data through the API.
5. Select an **Expiration** date for your token to help keep your information secure.
6. Select **Generate token**.
7. Copy the token to your clipboard and store it in a safe location. Once you navigate away from this page, you won't be able to access the value again.
8. Select **Done**.
9. 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**](https://app.netlify.com/user/applications). The procedure for revoking access depends on how access was granted.

- For access granted using the `netlify login` command, scroll to the [**Authorized applications**](https://app.netlify.com/user/applications#authorized-applications) section, and find **Netlify CLI**. Select 
### NavigationPath Component:

Options > Revoke access
.
- If you manually created a [personal access token](/api-and-cli-guides/cli-guides/get-started-with-cli#obtain-a-token-in-the-netlify-ui), you can find it in the [**Personal access tokens**](https://app.netlify.com/user/applications#personal-access-tokens) section. Select 
### NavigationPath Component:

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`](#config-json-location). You can also do this with the command line:

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

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

## Continuous deployment

With [continuous deployment](/deploy/create-deploys#deploy-with-git), 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](/deploy/deploy-types/deploy-previews), branch deploys, and [split testing](/manage/monitoring/split-testing/). (Some of these features must be enabled in the Netlify UI.)

### Tip

To connect your local project to an existing Netlify site, use <code>link</code></span>">
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`](#link-and-unlink-sites) instead of `netlify init` or `netlify init --manual`.

### 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:

```bash
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`](#config-json-location). 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 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:

```bash
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.

#### Add your deploy or access key

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.

![Sample terminal output reads: 'Give this Netlify SSH public key access to your repository,' and displays a key code.](/images/cli-deploy-key.png)

Copy the key printed in the command line, then add it to your Git provider.

- **GitHub, GitLab, or Bitbucket.** Add the deploy key to your repository's settings. If you have more than one site connected to a repository, you will need a unique key for each repository.
- **Azure DevOps.** Add the Netlify SSH public key to your Azure DevOps user settings under **SSH Public Keys**.

#### Add your webhook URL

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.](/images/cli-webhook.png)

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:

  - Code pushed
  - Pull request created
  - Pull request merge attempted
  - Pull request updated

  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.

## Run a local development environment

[Netlify Dev](https://www.netlify.com/products/dev) brings the functionality of your Netlify production environment directly to your local machine. 

For more information on how to configure and use Netlify Dev, refer to our [local development with Netlify Dev](/api-and-cli-guides/cli-guides/local-development) doc.

## Run builds locally

You can run builds in Netlify CLI to mimic the behavior of running a build on Netlify - including [Build Plugins](/extend/install-and-use/build-plugins). To execute a build locally, run the following command from the root of your linked repository:

```bash
netlify build
```

The command will build your project using [environment variables](/build/environment-variables/overview) 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.

### Caution - 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](/build/configure-builds/manage-dependencies#node-js-and-javascript). 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:

```bash
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](/deploy/deploy-overview#deploy-contexts).

```bash
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.

## 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](/build/configure-builds/stop-or-activate-builds), 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:

```bash
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](/build/functions/optional-configuration#directory) as well. Netlify CLI will look for this information in three places, in the following order:

- in [flags](https://cli.netlify.com/commands/deploy/) specified in the command itself.
- in a [netlify.toml file](/build/configure-builds/file-based-configuration) stored at the root of your project directory.
- in your project configuration in the Netlify UI, if continuous deployment is set up for the site.

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

```bash
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 deploys

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

![cli draft deploy](/images/cli-draft-deploy.png)

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.

```bash
netlify deploy --alias=YOUR_ALIAS
```

![cli draft deploy alias](/images/cli-draft-deploy-alias.png)

### Caution

--alias</code> 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](/deploy/deploy-overview#branches-and-deploys) or support our [branch subdomains](/manage/domains/domains-fundamentals/domains-glossary#branch-subdomain) feature. Learn more about this flag in the [CLI reference docs](https://cli.netlify.com/commands/deploy/). To create a branch deploy, use [continuous deployment](#continuous-deployment).

### Production deploys

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

```bash
netlify deploy --prod
```

### Node.js function dependencies

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`.

### Tabs Component:

<TabItem label="npm command">
``` sh
npm install
```
</TabItem>

<TabItem label="yarn command">
``` sh
yarn
```
</TabItem>

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.

## Link and unlink sites

### Tip

init</code> or <code>deploy</code> instead">
If your site is not already on Netlify, you need to either set up [continuous deployment](#continuous-deployment) or [manually deploy](#manual-deploys) 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:

```bash
netlify link
```

This will add a `siteId` field to a new file inside your project folder, at `.netlify/state.json`. 

> **Note - Site ID same as Project ID:** Your Site ID appears as the Project ID in the Netlify app UI at `app.netlify.com`. To find this ID in the Netlify UI, go to 
### NavigationPath Component:

Project configuration > General > Project information
, and copy the value for **Project ID**.

To unlink your folder from the site, you can remove this field, or you can run the following command from inside the project folder:

```bash
netlify unlink
```

### 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:

1. Go to 
### NavigationPath Component:

Project configuration > General > Project details > Project information
, and copy the value for **Project ID**. (Also known as Site 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.

## Manage environment variables

You can create and update site environment variables stored on Netlify with the CLI's [`env` command](https://cli.netlify.com/commands/env). 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 context is the [local development context](/build/environment-variables/overview#value-per-deploy-context) (`dev`). Unless a different context is specified, CLI commands will retrieve 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` 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:

```sh
netlify env:set API_KEY someValue --scope functions --context production branch-deploy
netlify env:list --scope builds --context deploy-preview
```

### Create or update environment variables

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.

```bash
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:

```sh
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.

```bash
netlify env:import .env
```

To copy environment variables from one project to another, use `env:clone`.

```bash
netlify env:clone --to destinationSiteId --from sourceSiteID
```

> **Note - Site ID same as Project ID:** Your Site ID appears as the Project ID in the Netlify app UI at `app.netlify.com`. To find this ID in the Netlify UI, go to 
### NavigationPath Component:

Project configuration > General > Project information
, and copy the value for **Project ID**.

If you are using environment variable secrets with Netlify's [Secrets Controller](/build/environment-variables/secrets-controller), you can flag that an environment variable value is secret using the `--secret` flag when creating or modifying a value.

```bash
netlify env:set API_KEY someValue --context production --secret
```

### Get environment variables

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](/build/environment-variables/overview#value-per-deploy-context) 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](/build/environment-variables/secrets-controller/#environment-variable-secrets-policy) policy for more details on the access restrictions.

```bash
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.

```bash
netlify env:get API_KEY
netlify env:get API_KEY --context production
```

### Delete environment variables

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.

```bash
netlify env:unset API_KEY
netlify env:unset API_KEY --context dev
```

## Work with monorepos

### Note - 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](/build/configure-builds/overview#definitions).

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.

![cli get started monorepos select](/images/cli-get-started-monorepos-select.png)

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.

  ```bash
  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](/build/configure-builds/overview) in the Netlify UI. Learn more about how to set up a site from a [monorepo](/build/configure-builds/monorepos).

## 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:

```bash
DEBUG=* netlify deploy
```

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

```bash
set DEBUG=* & netlify deploy
```

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

```bash
$env:DEBUG='*';netlify deploy
```

## Get help

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

```bash
netlify help
```

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

```bash
netlify help deploy
```

This also works for sub-commands.

```bash
netlify help sites:create
```

If you have additional questions or ideas for new features, you can [start an issue](https://github.com/netlify/cli/issues) on Netlify CLI's open source repository. You can also visit our [Support Forums](https://answers.netlify.com/categories) to start or join a conversation. We'd love to hear from you!