Netlify CLI lets you build and deploy your site locally, simulating Netlify’s production environment so you can catch issues before pushing.
Let’s see it in action. Imagine you’re working on a new Gatsby site.
First, you’ll need to install the CLI:
npm install netlify-cli -g
Once installed, navigate to your project’s root directory. If you haven’t already linked your project to a Netlify site, run:
netlify link
This command will prompt you to log in to your Netlify account and select an existing site or create a new one. For a new project, you might run:
netlify init
This command guides you through setting up a new Netlify project, often detecting your framework and suggesting build settings. It will ask you about your build command (e.g., gatsby build), your publish directory (e.g., public), and if you’re using a deploy key.
Now, the magic: running your site locally.
netlify dev
This command starts a local development server. It does more than just serve your files; it emulates Netlify’s Edge Functions, redirects, and header rules. You’ll see output like this:
◈ Netlify CLI: Version 10.10.0
◈ Starting Netlify Dev with watch mode enabled...
◈ Functions server listening on 3000
◈ App server listening on 8888
◈ Loading Netlify configuration file...
◈ A site with ID 12345678-abcd-1234-abcd-1234567890ab is linked to this folder.
◈ Running build command: gatsby build
◈ Build complete.
◈ Starting server from public directory.
◈ Server now available on http://localhost:8888
Your site will be available at http://localhost:8888. If you have Netlify Functions (serverless functions), they’ll be accessible at http://localhost:3000/api/<your-function-name>. The CLI watches for changes in your project files and automatically rebuilds and reloads your site.
The netlify dev command is incredibly powerful because it reads your netlify.toml configuration file. This file dictates how Netlify builds and deploys your site in production. By using netlify dev, you’re ensuring that your local development mirrors your production environment as closely as possible.
Here’s an example netlify.toml:
[build]
command = "gatsby build"
publish = "public"
[functions]
directory = "netlify/functions"
[[redirects]]
from = "/old-path"
to = "/new-path"
status = 301
When netlify dev runs, it respects these settings. The command is executed locally, and the publish directory is served. Any functions in the specified directory are also started and made available. The redirects are applied to your local development server.
You can also deploy your site directly from the CLI:
netlify deploy --prod
This command will build your site using the settings from netlify.toml and deploy it to your Netlify production environment. If you want to deploy a draft or preview, you can use:
netlify deploy
This will prompt you to choose between deploying a draft or a production build.
One of the most useful, yet often overlooked, aspects of netlify dev is its ability to simulate Netlify’s edge network. This means that features like Edge Functions, which run at the edge of Netlify’s network, are executed locally. If you have complex logic in your Edge Functions, testing them with netlify dev ensures they behave as expected before you ever hit a production server. This local simulation is crucial for debugging and for understanding the full scope of Netlify’s deployment capabilities without needing to push code for every small change.
The CLI also provides commands for managing your Netlify sites, such as netlify status to see your linked site and deployment history, and netlify logs to view live logs from your deployed functions.
Understanding netlify dev is key to a streamlined Netlify workflow, bridging the gap between local development and production deployment.
The next step is to explore how Netlify’s Edge Functions can be integrated and tested with the CLI.