Netlify CLI

Netlify CLI cheatsheet — deploy sites, run local dev, manage env vars, functions. netlify deploy, netlify dev, netlify env:set, netlify functions:invoke. Full reference.

6 min read

What it is

The Netlify CLI allows you to deploy and manage your Netlify sites directly from your command line, enabling local development with live previews and seamless deployments.

Installation

Linux / macOS:

npm install netlify-cli -g

Windows:

npm install netlify-cli -g

(Requires Node.js and npm to be installed.)

Core Concepts

Site: A project deployed to Netlify. Each site has a unique name and can be associated with a Git repository.
Deploy: A specific version of your site deployed to Netlify. Deploys can be linked to Git commits.
Context: The environment in which a command is run. The CLI supports production and deploy-preview contexts, as well as arbitrary custom contexts.
Netlify.toml: A configuration file that lives in the root of your project. It allows you to define build settings, environment variables, redirects, and more, making your deployments reproducible and portable.

Commands / Usage

Authentication

Log in to Netlify:
```
netlify login
```
Opens a browser window to authenticate your Netlify account.
Log out of Netlify:
```
netlify logout
```
Logs out of your Netlify account on the CLI.

Site Management

Link a local directory to a Netlify site:
```
netlify link
```
Prompts you to choose an existing site or create a new one to associate with your current directory.
Unlink a local directory from a Netlify site:
```
netlify unlink
```
Removes the association between the current directory and its linked Netlify site.
View linked site information:
```
netlify status
```
Shows the current Netlify site linked to your directory, its ID, and recent deploys.

Local Development and Preview

Start a local development server with live previews:
```
netlify dev
```
Starts a local server, watches for file changes, and deploys previews to Netlify. Uses your netlify.toml for configuration.
- Specify a different port:
```
netlify dev --port 8888
```
  Starts the development server on port 8888.
- Specify the directory to serve:
```
netlify dev --dir public
```
  Serves files from the public directory.
- Specify the build command:
```
netlify dev --command "npm run build"
```
  Runs npm run build before starting the server.
- Set environment variables for local development:
```
netlify dev --env MY_VARIABLE=my_value --env ANOTHER_VAR=another_value
```
  Sets environment variables for the local development server.

Deploying to Netlify

Deploy the current directory to Netlify:
```
netlify deploy
```
Initiates a deployment. Prompts for site selection and deploy type (draft or production).
Deploy as a draft (preview):
```
netlify deploy --draft
```
Creates a deployable preview URL that is not the live production version.
Deploy to production:
```
netlify deploy --prod
```
Deploys the current version of your site to your production URL.
Deploy with a specific message:
```
netlify deploy --message "Deploying new feature X"
```
Adds a descriptive message to the deploy log.
Deploy from a specific directory:
```
netlify deploy --dir dist --prod
```
Deploys the contents of the dist directory as a production build.
Deploy with specific build settings (overriding netlify.toml):
```
netlify deploy --build --command "yarn build:prod" --functions src/functions
```
Runs a custom build command and specifies a functions directory.

Managing Deploys

List deploys for the linked site:
```
netlify deploys
```
Shows a list of recent deploys for the current Netlify site.
Open a specific deploy in the browser:
```
netlify deploys --open
```
Opens the most recent deploy in your browser.
Open a production deploy in the browser:
```
netlify deploys --prod --open
```
Opens the current production deploy in your browser.
Set a specific deploy as production:
```
netlify deploy --prod --id <deploy-id>
```
Promotes a specific deploy ID to production.
List deploy previews:
```
netlify deploy --list-drafts
```
Shows all deploy previews.

Delete a deploy:

netlify deploy --delete --id <deploy-id>

Deletes a specific deploy.

Environment Variables

View environment variables for the linked site:
```
netlify env
```
Displays environment variables for the currently linked Netlify site.
Set environment variables for a site:
```
netlify env:set MY_API_KEY YOUR_SECRET_KEY --site <site-id>
```
Sets a specific environment variable for a given site ID.
Unset environment variables for a site:
```
netlify env:unset MY_API_KEY --site <site-id>
```
Removes a specific environment variable from a given site ID.
Set environment variables for a specific context:
```
netlify env:set MY_CONFIG production --context production
```
Sets MY_CONFIG to production specifically for the production context.

Functions

Deploy Netlify Functions:
```
netlify deploy --functions <path-to-functions-dir>
```
Deploys functions located in the specified directory. This is often handled automatically by netlify dev and netlify deploy if configured in netlify.toml.

Other Utilities

Get help for a command:
```
netlify help <command>
```
Provides detailed help for a specific Netlify CLI command.
View Netlify CLI configuration:
```
netlify config
```
Shows the current Netlify CLI configuration.

Common Patterns

Local development with a specific build command and output directory:
```
netlify dev --command "npm run build:dev" --dir build
```
Starts local development, running your dev build command and serving from the build directory.
Deploying a static site generator (e.g., Hugo): Assuming netlify.toml is configured with command = "hugo" and publish = "public":
```
netlify deploy --prod
```
This will build and deploy your Hugo site to production.
Deploying a React app built with Create React App: Assuming netlify.toml is configured with command = "npm run build" and publish = "build":
```
netlify deploy --prod
```
This will build and deploy your React app to production.
Setting a production deploy with a Git branch: If your Netlify site is linked to a Git repository, pushing to main might automatically trigger a production deploy. Manually:
```
netlify deploy --prod --branch main
```
This command is more for manual CLI deployments tied to a branch, though Netlify’s Git integration often handles this automatically.
Managing environment variables for different contexts:
```
netlify env:set STRIPE_SECRET_KEY test_sk_123 --context dev
netlify env:set STRIPE_SECRET_KEY live_sk_abc --context production
netlify deploy --prod
```
Sets different Stripe secret keys for development and production contexts and then deploys to production.
Viewing logs for a specific deploy:
```
netlify logs <deploy-id>
```
Retrieves build logs for a specific deploy ID.

Gotchas

netlify dev vs. netlify deploy: netlify dev is for local development and testing, providing live previews and a local server. netlify deploy pushes your site to Netlify.
netlify.toml precedence: Settings in netlify.toml generally override command-line flags for build commands and publish directories, making it the source of truth for your build.
Contextual Environment Variables: Environment variables set for specific contexts (e.g., production, deploy-preview) are only active in those contexts. netlify dev might use a default or development context unless explicitly configured.
Site Linking: Ensure you are in the correct directory when running netlify link or netlify deploy. If you run these commands in a directory not associated with a Netlify site, you’ll be prompted to link or create one.
Global vs. Local Installation: While installing netlify-cli globally (-g) is common, it’s good practice to also have it as a dev dependency in your package.json (npm install netlify-cli --save-dev) for project-specific versioning and consistency. You can then run commands using npx netlify <command>.
Build Output Directory: If netlify.toml specifies a publish directory, netlify deploy will upload the contents of that directory. If netlify dev is used without specifying a dir flag, it often infers this from netlify.toml or a default like public or dist.