| | |

Netlify 04 ๐ŸŒ Netlify CLI & Local Dev โ€” Running netlify dev, linking sites, emulating primitives, and manual deploys

โฑ๏ธ Estimated read: 11 min | |

The Netlify Command Line Interface (CLI) serves as the primary bridge between a developer’s local workstation and Netlifyโ€™s global orchestration engine. While Netlifyโ€™s core value proposition is centered around automated Git-based workflows, the CLI provides the necessary tooling to emulate that cloud environment locally, manage project configuration without leaving the terminal, and execute manual deployments when Git-based triggers are insufficient or undesirable.

At the heart of the CLI is netlify dev, a powerful local development server that does more than just serve files. It detects the framework you are using, starts your site’s local build tool, and wraps it in a proxy server that injects Netlifyโ€™s primitivesโ€”such as environment variables, serverless functions, and redirect rulesโ€”directly into the local runtime. This ensures that the code you write and test on your machine behaves identically to the code running in the production cloud environment.

This chapter covers the installation and authentication of the CLI, the process of linking local directories to remote Netlify sites, and the deep technical mechanics of the netlify dev proxy. We will also explore how to use the CLI for manual “drag-and-drop” style deployments and how to share local work-in-progress via live tunnels for immediate stakeholder feedback.

Key point: The Netlify CLI is an emulation and orchestration layer that synchronizes local development with cloud infrastructure, providing identical environment variable injection, serverless function execution, and routing logic before code is committed to Git.


Why X exists

The local-cloud parity problem. Most modern web applications rely on platform-specific features like serverless functions, redirects, and environment variables. Without a tool to emulate these features locally, developers are often forced to “push and pray,” committing code to Git just to see if a function or a redirect works correctly in the cloud.

The environment variable synchronization problem. Manually copying environment variables from a web dashboard into local .env files is tedious and insecure. The CLI automates this by fetching encrypted variables from Netlifyโ€™s servers and injecting them directly into the local process memory, ensuring your local environment is always up to date with the “source of truth.”

The framework detection overhead. Developers work with a multitude of frameworksโ€”Vite, Next.js, Hugo, Eleventy, and moreโ€”each with different default ports and build commands. The CLI abstracts this complexity by automatically detecting the underlying framework and configuring the local proxy to match its specific requirements.

The feedback loop latency. Waiting for a full CI/CD build to finish just to show a small CSS change to a teammate is inefficient. The CLI allows for “Live” sharing, which tunnels your local port to a public URL, enabling instant feedback from anyone in the world without requiring a deployment.

The Git-less deployment requirement. Not every project uses a Git-centric workflow. Some specialized use casesโ€”such as automated scripts, CLI-based CI/CD pipelines (like Jenkins or CircleCI), or quick proof-of-conceptsโ€”require the ability to deploy raw build artifacts directly from a local folder or a build runner to Netlifyโ€™s CDN.


a. Installation, Authentication, and Site Linking

The Netlify CLI is distributed as a global Node.js package. Once installed, it must be authenticated with your Netlify account to gain access to your sites and configurations. This authentication creates a secure token stored in your local configuration, allowing the CLI to communicate with the Netlify API on your behalf.

# Install the CLI globally via npm
npm install netlify-cli -g

# Authenticate with your Netlify account
# This opens a browser window for OAuth login
netlify login

After authentication, the CLI needs to know which cloud site corresponds to your local project directory. This is handled via the link command. You can link to an existing site by searching your account or by providing a specific Site ID found in the dashboard. Linking creates a .netlify/state.json file (which should be git-ignored) that stores the association.

# Link the current directory to a Netlify site
netlify link

# Check the current link status and site details
netlify status

Linking is the prerequisite for most advanced CLI features. Once linked, the CLI can pull site-specific environment variables, manage serverless functions, and trigger remote builds. It also enables the netlify open command, which provides quick terminal shortcuts to open the siteโ€™s admin dashboard or the live production URL in your default browser.


b. Local Emulation with netlify dev

netlify dev is the flagship feature of the CLI. When executed, it starts a local development server (usually on port 8888) that acts as a proxy for your application. It performs “detector” logic to find your framework’s development server (like Vite on port 5173), starts it, and routes all traffic through the Netlify proxy.

# Start the local development environment
netlify dev

The proxy adds several critical capabilities that a standard framework dev-server lacks. First, it handles Netlify Redirects and Rewrites defined in netlify.toml or _redirects. Second, it hosts your local Serverless Functions (from the netlify/functions folder) at the /.netlify/functions/ endpoint. Third, it injects all environment variables configured in the Netlify Dashboard into the local environment, making them accessible via process.env.

# Start dev with a specific context (e.g., emulate production variables)
netlify dev --context production

One of the most powerful aspects of netlify dev is its ability to share your local environment. By using the --live flag, the CLI sets up a temporary tunnel that provides a public URL (e.g., https://random-name.netlify.live). Anyone with this link can view your local site exactly as it appears on your machine, including functional serverless endpoints, which is invaluable for testing webhooks from third-party services like Stripe or GitHub.


c. Manual Deploys and Live Previews

While automated Git deployments are the standard, the CLI provides the deploy command for manual control. This is particularly useful for deploying from a local build or a custom CI environment. Manual deployments are “atomic,” meaning Netlify uploads all files, hashes them, and prepares the deploy before making it live.

# Deploy a draft (creates a unique preview URL)
netlify deploy

# Deploy to production (updates the main site URL)
netlify deploy --prod

When you run netlify deploy without the --prod flag, Netlify creates a “Draft Deploy.” You receive a unique URL to preview the changes. This allows you to verify the build in the actual cloud infrastructure before committing to the production URL. The CLI will prompt you for the “Publish directory” (e.g., dist or build) if it isn’t defined in your netlify.toml.

# Deploy specifying the folder and skipping the prompt
netlify deploy --dir=dist --prod

Manual deployments are also useful for “rolling back” or testing specific versions of a site. Every netlify deploy command results in a permanent, immutable URL for that specific version of the site. You can also view the logs of these deployments directly in the terminal using the --message flag to annotate the deploy, making it easier to track changes within the Netlify Dashboard history.


Complete Example Session

# ============================================
# PART 1: INSTALLATION & LOGIN
# ============================================
npm install netlify-cli -g
netlify login

# ============================================
# PART 2: INITIALIZING A NEW PROJECT
# ============================================
mkdir my-new-site && cd my-new-site
npm init -y
npm install vite # Example framework

# ============================================
# PART 3: LINKING TO THE CLOUD
# ============================================
# Connect local folder to an existing Netlify site
netlify link

# ============================================
# PART 4: RUNNING THE DEV PROXY
# ============================================
# Starts Vite + Netlify Function emulation + Env Var injection
netlify dev

# ============================================
# PART 5: CREATING A SERVERLESS FUNCTION
# ============================================
# Creates a template function in netlify/functions/hello.js
netlify functions:create hello

# ============================================
# PART 6: TESTING FUNCTIONS LOCALLY
# ============================================
# Access via http://localhost:8888/.netlify/functions/hello
# (Assuming netlify dev is running)

# ============================================
# PART 7: TUNNELING LOCAL WORK
# ============================================
# Shares local port 8888 with a public .netlify.live URL
netlify dev --live

# ============================================
# PART 8: FETCHING REMOTE ENV VARS
# ============================================
# Lists variables currently set in the Netlify Dashboard
netlify env:list

# ============================================
# PART 9: DRAFT DEPLOYMENT
# ============================================
# Build the site and upload as a preview
npm run build
netlify deploy --dir=dist

# ============================================
# PART 10: PRODUCTION DEPLOYMENT
# ============================================
# Finalize and push to the live production URL
netlify deploy --dir=dist --prod

The steps above guide a developer from the initial installation and project setup through local emulation, serverless function creation, live sharing, and finally, a manual production deployment.


Quick Reference

Essential CLI Commands

CommandAction
netlify loginAuthenticates the CLI with your account
netlify linkAssociates local folder with a Netlify site
netlify devStarts local proxy, functions, and env var injection
netlify deployUploads local build artifacts to Netlify (Draft)
netlify deploy --prodUploads and makes the build live on the main URL
netlify statusShows info about the linked site and user

netlify dev Flags

FlagDescription
--liveCreates a public tunnel for your local dev server
--context <name>Emulates a specific deploy context (e.g., staging)
--port <number>Specifies the port for the Netlify proxy
--targetPort <number>Specifies the port where the framework is running
--offlineRuns dev without connecting to Netlify API

Function Management Commands

CommandAction
netlify functions:createGenerates a new function from a template
netlify functions:listLists all local functions
netlify functions:serveStarts only the function server (no frontend)

Best Practices

โœ… Do This:

# Use 'netlify dev' as your primary dev command
netlify dev                                                   # โœ…

# Git-ignore the .netlify folder
echo ".netlify" >> .gitignore                                 # โœ…

# Use --live to test third-party webhooks locally
netlify dev --live                                            # โœ…

# Always verify a draft deploy before pushing to --prod
netlify deploy                                                # โœ…

# Use 'netlify env:list' to check synced variables
netlify env:list                                              # โœ…

โŒ Don’t Do This:

# Don't manually copy secrets into .env files
# (Let 'netlify dev' inject them for you)                     # โŒ

# Don't commit .netlify/state.json to Git
# (Contains local machine site associations)                 # โŒ

# Don't use 'netlify deploy --prod' for every minor change
# (Prefer Git-based CI/CD for traceability)                  # โŒ

# Don't run 'netlify dev' without linking first
# (You'll miss cloud-synced environment variables)            # โŒ

Common Pitfalls

PitfallWhy It HappensFix
Port CollisionAnother process is using port 8888Use netlify dev --port <new_port>
Missing Env VarsSite is not linked or vars not in DashboardRun netlify link and verify variables in UI
Function 404Function path or folder is incorrectCheck netlify.toml for functions directory
Proxy LoopCLI tries to proxy to its own portDefine targetPort explicitly in netlify.toml
Link FailureUser lacks permissions or site doesn’t existRun netlify login to refresh token
CLI Version LagOutdated CLI doesn’t support new featuresRun npm install netlify-cli -g to update

Real-World Examples

1. Checking link status

netlify status

2. Opening the Netlify Admin UI

netlify open --admin

3. Listing remote environment variables

netlify env:list

4. Importing local .env to Netlify

netlify env:import .env

5. Creating a background function

netlify functions:create --name sync-db --template background

6. Deploying a specific subfolder

netlify deploy --dir=packages/app/dist

7. Emulating staging variables locally

netlify dev --context staging

8. Checking build logs from CLI

netlify watch

9. Logging out of the CLI

netlify logout

10. Manual deploy with a custom message

netlify deploy --prod --message "Emergency fix for header"

Visual

The netlify dev Proxy Architecture

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚ LOCAL MACHINE                                           โ”‚
โ”‚                                                         โ”‚
โ”‚  User Request (localhost:8888)                          โ”‚
โ”‚          โ”‚                                              โ”‚
โ”‚          โ–ผ                                              โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”‚
โ”‚  โ”‚ NETLIFY CLI PROXY                                 โ”‚  โ”‚
โ”‚  โ”‚                                                   โ”‚  โ”‚
โ”‚  โ”‚ 1. Inject Environment Variables                   โ”‚  โ”‚
โ”‚  โ”‚ 2. Handle _redirects / netlify.toml               โ”‚  โ”‚
โ”‚  โ”‚ 3. Route /.netlify/functions to Local Server      โ”‚  โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ”‚
โ”‚             โ”‚                            โ”‚              โ”‚
โ”‚             โ–ผ                            โ–ผ              โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”      โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚
โ”‚  โ”‚ FRAMEWORK DEV SERVER โ”‚      โ”‚ LOCAL FUNCTION SERVERโ”‚ โ”‚
โ”‚  โ”‚ (e.g. Vite :5173)    โ”‚      โ”‚ (Port 9999)          โ”‚ โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜      โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

The Site Linking Relationship

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”         โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚ LOCAL PROJECT FOLDER    โ”‚         โ”‚ NETLIFY CLOUD SITE      โ”‚
โ”‚                         โ”‚         โ”‚                         โ”‚
โ”‚ .netlify/state.json  โ—„โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค Site ID: 123456         โ”‚
โ”‚                         โ”‚  Link   โ”‚ Environment Variables   โ”‚
โ”‚ netlify.toml            โ”‚         โ”‚ Serverless Functions    โ”‚
โ”‚ Source Code             โ”‚         โ”‚ Deployment History      โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜         โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

The netlify dev --live Tunnel

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”         โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚ LOCAL DEV (Port 8888)   โ”‚         โ”‚ PUBLIC INTERNET         โ”‚
โ”‚                         โ”‚ Tunnel  โ”‚                         โ”‚
โ”‚ [ My Website ]          โ”‚โ—„โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค site.netlify.live       โ”‚
โ”‚ [ Local Functions ]     โ”‚         โ”‚ (Shared Preview)        โ”‚
โ”‚ [ Local DB/State ]      โ”‚         โ”‚                         โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜         โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Manual vs Git Deployment Flows

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚ DEPLOYMENT FLOWS                                        โ”‚
โ”‚                                                         โ”‚
โ”‚ 1. GIT FLOW (Standard)                                  โ”‚
โ”‚    Local Push โ”€โ”€โ–บ GitHub โ”€โ”€โ–บ Netlify Build โ”€โ”€โ–บ CDN      โ”‚
โ”‚                                                         โ”‚
โ”‚ 2. CLI FLOW (Manual)                                    โ”‚
โ”‚    Local Build โ”€โ”€โ–บ netlify deploy --prod โ”€โ”€โ–บ CDN        โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Summary

ItemValue
CLI Package Namenetlify-cli
Primary Dev Commandnetlify dev
Default Proxy Port8888
Config Folder.netlify (Git-ignore this)
Auth MethodOAuth via Browser (netlify login)
Site Associationnetlify link
Production Flag--prod
Functions Endpoint/.netlify/functions/

Key takeaways:

  • The CLI bridges the gap between local code and cloud features. By emulating redirects, functions, and environment variable injection, it ensures that your local development environment matches the production environment.
  • netlify dev is a smart proxy. It automatically detects your framework, runs its development server, and wraps it with Netlify-specific capabilities like environment variable injection.
  • Linking is essential for cloud synchronization. A linked site allows the CLI to fetch your siteโ€™s specific configurations and secrets, providing a seamless “it works on my machine” experience.
  • The CLI supports manual deployment workflows. While Git is preferred, the deploy command allows for atomic, manual uploads from any folder, which is ideal for custom CI pipelines or non-Git projects.
  • Sharing is built-in. Use the --live flag to create instant public tunnels of your local work for stakeholders or to test external webhooks.

Remember: The Netlify CLI is not just a deployment tool; it is a full local development suite. By utilizing netlify dev and netlify link, you eliminate configuration drift and ensure that your serverless functions and routing logic are fully tested and validated before they ever touch your production infrastructure.

Was this helpful?


Stop using slow, ad-bloated tool sites! ๐Ÿคฎ

๐Ÿ”Ž Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
โœ… Finance (Mortgage, Interest, Inflation)
โœ… Tech (Base64, JSON, Dev Suite, IP)
โœ… Health (BMI, BMR, TDEE)
โœ… Productivity (Timer, Workspace, QR)

โšก๏ธ Fast & Private
๐Ÿ”’ No data leaves your device
๐Ÿ’Ž 100% Free

๐Ÿ”— Use it now: https://tools.kandz.me
๐Ÿ”– Bookmark itโ€”youโ€™ll need it later!