netlify init: What the Command Does, What It Writes, and When to Use link or sites:create Instead

netlify init connects the repository in your current directory to a site on Netlify and configures continuous deployment, so that pushes to the linked branch build and deploy automatically. It asks a handful of questions, writes a small state file locally, and registers a deploy key and a webhook with your git provider. If you only want to attach a directory to a site that already exists, netlify link does that without touching continuous deployment.

The command reference tells you what init is for in one sentence. What it does not tell you is what the prompts mean, what ends up on disk, why it sometimes fails at the git step, and which of the four similarly named commands you actually wanted. That is this post.

Table of contents

• Install, log in, and the command not found problem
• What netlify init asks, prompt by prompt
• What it writes, locally and remotely
• init, link, sites:create and deploy: which one you wanted
• Common failures and the fix for each
• The pattern underneath: repository, build command, publish directory
• How this fits the rest of the stack
• FAQ

Install, log in, and the command not found problem

The CLI is a global npm package. Install it, then authenticate once; the login opens a browser and stores a token locally.

npm install -g netlify-cli
netlify login
netlify status   # confirms who you are logged in as and which site, if any, the directory is linked to

The most common first failure is that the install succeeds and the netlify command is not found. The cause is nearly always that npm’s global bin directory is not on your PATH, which is common on Windows with Git Bash and on any machine where Node was installed through a version manager. Run npm prefix -g to find the directory, add its bin subfolder to PATH, and open a new shell.

If you would rather not fix PATH on a machine you are only borrowing, npx netlify-cli followed by the command runs the same thing without a global install.

What netlify init asks, prompt by prompt

Run it from the root of a repository that has a remote and at least one commit pushed. The order of the prompts:

1. Create and configure a new site, or connect this directory to an existing one. New site is the usual answer on a fresh project.
2. Team. Only matters if your account belongs to more than one.
3. Site name. Optional; a random name is generated if you leave it blank, and it becomes the default subdomain.
4. Build command. It tries to detect this from package.json. Check it: npm run build is right for most frameworks, and a wrong guess here is the top cause of the first failed deploy.
5. Directory to deploy. The build output folder: dist for Vite, build for Create React App, out or .next depending on the Next.js mode, public for many static generators. This is the second most common thing to get wrong.
6. Functions directory, if you use serverless functions. Skip if not.

It then reads the git remote, and here it needs access to the provider. It creates a deploy key so the build can clone the repository and a webhook so a push triggers a build. If the CLI cannot reach your provider, or the repository is under an organisation whose permissions block it, the run fails at this step, and that is what the manual flag is for.

netlify init --manual

Manual mode prints the deploy key and the webhook URL and asks you to add them to the repository yourself. It is the answer for self-hosted git, for repositories where you do not have admin rights, and for the occasional provider permission tangle that is not worth debugging.

What it writes, locally and remotely

Locally, init writes one file: .netlify/state.json, containing the site ID. That is how later commands know which site this directory belongs to. It is per-clone state rather than project configuration, so add .netlify to .gitignore; committing it means every collaborator’s clone points at your site.

It does not write netlify.toml unless you ask it to. The build command and publish directory you answered go to the site’s settings in the dashboard. If you want those settings versioned with the code, which you do on any project with more than one contributor, create the file yourself and the file takes precedence over the dashboard.

[build]
  command = "npm run build"
  publish = "dist"

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

Remotely, it creates the site, stores the build settings, links the repository and branch, and installs the deploy key and webhook on the git provider. That last pair is what makes continuous deployment work, and it is also what you have to remove by hand if you delete the site and re-create it, or the old webhook keeps firing at nothing.

init, link, sites:create and deploy: which one you wanted

Four commands share the territory and the names are close enough to pick the wrong one.

• init: create or connect a site and set up continuous deployment from git. Use it once per repository, at the start.
• link: connect this directory to a site that already exists, and nothing else. Use it on a fresh clone of a project that was already initialised, or on a second machine.
• sites:create: create a site with no repository and no continuous deployment. Use it when you intend to deploy manually from the CLI or from your own CI.
• deploy: upload a built directory right now, from this machine, to a linked site. netlify deploy alone makes a draft at a preview URL; netlify deploy —prod publishes to the live site. Use it for a one-off or when you deliberately do not want git-triggered builds.

The common mistake is running init on a second clone of a project that already has a site, and creating a duplicate. On any clone after the first, link is the command.

Common failures and the fix for each

• Build succeeds locally and fails remotely with a missing command. The build environment does not have your global tools. Add the tool to devDependencies and call it through an npm script.
• Deploy succeeds and the site is blank or shows the wrong files. The publish directory is wrong. Check what your build actually writes and match it exactly.
• Monorepo builds the wrong package. Set the base directory, in netlify.toml or the site settings, so the build runs from the right subfolder.
• Pushes do not trigger a build. The linked branch is not the one you pushed, or the webhook was removed. netlify status shows the branch; the provider’s repository settings show the webhook.
• Deep links 404 after deploy. The single-page-app redirect above is missing. Add it to netlify.toml or a _redirects file in the publish directory.
• Site already linked. The directory has a .netlify/state.json from a previous run. netlify unlink clears it.

The pattern underneath: repository, build command, publish directory

Once you have run init, notice how little it actually needed: a repository, a branch, a build command and an output directory. Every git-driven deployment platform is that same set of four fields with a different form around it, and a project that has them written down in one place moves between platforms in an afternoon.

On RunxBuild those four fields are the create form for a static site: pick the repository from GitHub, name the branch, set the build command and the output directory, and the first build starts with a log you can read. Custom domains, headers, redirects and the SPA fallback are settings on the site, and 120GB of bandwidth is included with $0.10 per gigabyte after. The GitHub setup docs cover the connection and the builds docs cover what happens on each push.

How this fits the rest of the stack

A static site’s cost is almost entirely bandwidth, and a site that grows a backend adds a service plan and a database to the bill. The RunxBuild hosting calculator lays those out as separate line items, so the number you compare between platforms is the one that arrives every month rather than the one on the sign-up page.

Useful related references:

• Django on Netlify: Why It Does Not Work, and What To Do Instead
• Branch Deploy on Netlify: How It Works and When to Use One
• Netlify Templates: What Starter Templates Give You and What They Do Not
• Services on RunxBuild

FAQ

What does netlify init do?

It creates a new site or connects the current directory to an existing one, records the build command and publish directory, and sets up continuous deployment by adding a deploy key and a webhook to your git repository. Locally it writes .netlify/state.json with the site ID.

What is the difference between netlify init and netlify link?

init creates or connects a site and configures continuous deployment from git. link only associates the current directory with a site that already exists, without touching git or build settings. Use init once per project and link on every subsequent clone.

Why does netlify init fail at the git step?

The CLI could not reach your git provider or lacks permission to add a deploy key and webhook, which is common for organisation-owned repositories and self-hosted git. Run netlify init —manual, and it prints the key and webhook URL for you to add by hand.

Should I commit the .netlify folder?

No. It holds per-clone state, specifically the site ID this directory is linked to. Add .netlify to .gitignore. Project configuration that should be shared belongs in netlify.toml, which you do commit.

Why does my site work locally but show a blank page after netlify init?

The publish directory is almost certainly wrong. The build writes to a folder such as dist, build or out depending on the framework, and the site setting has to match it exactly. Check the build log for the output path, then correct the setting in netlify.toml or the dashboard.