New Netlify command line tool, now in beta
Clone or download
Latest commit b4f3b0d Sep 21, 2018

README.md

netlify-cli [beta]

npm version build status windows build status coverage dependencies downloads

Welcome to the Netlify CLI! The new 2.0 version (now in beta) was rebuilt from the ground up to help improve the site building experience.

Table of Contents

Click to expand

Install & Setup

Prerequisites

To install the Netlify CLI, run the following command in your terminal window:

npm install netlify-cli@next -g

After installing the CLI globally, connect the CLI to your Netlify account with the following command:

netlify login

This will open a browser window, asking you to log in with Netlify and grant access to Netlify CLI. This will store your Netlify access token in your home folder, under ~/.netlify/config.json.

Usage

netlify [command]

# Run `help` for detailed information about CLI commands
netlify [command] help

Getting Started

Netlify's continuous deployment will automatically deploy new versions of your site when you push commits to your connected Git repository.

To setup continuous deployment with the CLI, run:

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 github 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 your home folder, under .netlify/config.json. Your login password will never be stored. You can revoke the access token at any time from your GitHub account settings.

Link to an existing site

Linking to a site tells Netlify CLI which site the current directory should deploy to. To do this, run the following command from the base of your project directory:

netlify link

This will add a siteId field to a new file inside your project folder, at .netlify/state.json. To unlink your folder from the site, you can remove this field, or you can run the following command from inside the project folder:

netlify unlink

Create a new site

To create a new Netlify site with the CLI, run the netlify init command in your site folder.

netlify init

Then Choose "Create & configure a new site in Netlify"

Proceed through the prompts to finish configuring your site.

Deploying a site

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.

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 do a manual deployment with the CLI run:

netlify deploy

# Optionally pass in the build directory
netlify deploy --dir your-build-directory

# Deploying to production with --prod flag
netlify deploy --dir your-build-directory --prod

This deploy command needs to know which folder to publish, and if your project includes functions, a functions folder to deploy. It will look for this information in three places, in the following order:

  • in flags specified in the command itself
  • in a netlify.toml file stored at the base of your project directory.
  • in your site settings in the Netlify UI.

Production Deploys

By default, all deploys are set to a draft preview URL.

To do a manual deploy to production, use the --prod flag:

# Deploy build folder to production
netlify deploy --prod

# Shorthand -p
netlify deploy -p

Deploying to production will publish the build directory at the live URL of your Netlify site.

Full Command Reference

deploy

Create a new deploy from the contents of a folder

init

Configure continuous deployment for a new or existing site

link

Link a local repo or project folder to an existing site on Netlify

login

Login to your Netlify account

logout

Logout of your Netlify account

open

Open settings for the site linked to the current folder

Subcommand description
open:admin Opens current site admin UI in Netlify
open:site Opens current site url in browser

sites

Handle various site operations

Subcommand description
sites:create Create an empty site (advanced)
sites:list List all sites you have access too

status

Print status information

Subcommand description
status:hooks Print hook information of the linked site

unlink

Unlink a local folder from a Netlify site

watch

Watch for site deploy to finish

telemetry

By default, the CLI collects usage stats from logged in Netlify users. This is to constantly improve the developer experience of the tool and bake in better features.

If you'd like to opt out of sending telemetry data, you can do so with the --telemetry-disable flag

# opt out of telemetry
netlify --telemetry-disable

# turn on telemetry
netlify --telemetry-enable

Or edit the telemetryDisabled property of the ~/.netlify/config.json file in your computers root directory.

Local Development

  1. Clone down the repo
$ git clone git@github.com:netlify/cli.git
  1. Install dependencies
$ npm install
  1. Run CLI locally during development
$ ./bin/run [command]

When developing, you can use watch mode which will automatically run ava tests:

$ npm run watch