Netlify CLI

The documentation site is an Astro Starlight project that uses an automated pipeline to keep command references in sync with the CLI source code. The flow is as follows:

1. Extraction: The docs.js script extracts command information from the CLI code and replaces content between auto-generation marker comments in the manual files located in ../docs/.
2. Synchronization: The sync.js script copies these generated files into the Astro site's content directory at src/content/docs/, performing minor transformations if necessary.
3. Rendering: The Astro/Starlight engine renders the files into the final documentation site.

Use the netlify login command to authenticate the CLI with your Netlify account. This command opens a web browser to facilitate an OAuth flow, which allows the CLI to acquire an access token.

If you need to authenticate without a browser (e.g., in a remote environment or for agent-based authentication), you can use the --request flag to create a login ticket, or provide an existing token directly using the --auth flag.

Use the following commands to generate and build the documentation site:

• npm run build:docs-md: Generates the Markdown command pages directly from the CLI source code.
• npm run build:docs-md: (Note: The README lists this same command for two actions) Generates Markdown command pages from code and syncs them into the site's pages.
• npm run build: Builds the production version of the site into the ./dist/ directory.
• npm run preview: Allows you to preview the production build locally before deploying.

The netlify serve command builds your project for production and serves it locally.

Important Note: This command does not watch your code for changes. If you modify your code and need to rebuild, you must exit the current process and run netlify serve again.

The Netlify CLI requires Node.js version 22.13.0 or above. You can install it globally for general use or locally as a development dependency for CI/CD environments.

Global Installation

Use this for interactive development on your local machine:

npm install netlify-cli -g

Local Installation (Recommended for CI)

To ensure reproducible builds in CI environments, install the CLI as a development dependency in your project root. This allows you to use a lock file to prevent unexpected breaking changes from automatic updates.

npm install --save-dev netlify-cli

Homebrew Installation

On macOS, you can also use Homebrew:

brew install netlify-cli

To explore the available commands in the Netlify CLI, use the help command.

• Run netlify help to see a top-level list of all available commands.
• Run netlify [command] help to see specific sub-commands, arguments, and flags for a particular command.

Use the netlify create command to scaffold a new Netlify project using an AI agent. You can provide a natural language description of the site you want to build as a prompt. The command can be configured to use specific AI agents (like claude, codex, or gemini), target specific Netlify accounts, or automatically initialize a Git repository.

netlify create "a portfolio site"

Use the netlify init command to configure continuous deployment for a new or existing project. This command sets up the necessary links between your local project and Netlify to enable automated deployments via Git.

Note: If you want to create a new project without continuous deployment, use netlify sites:create instead.

Once installed globally, you can interact with Netlify using the netlify command. To see a list of available commands and their details, use the help command.

Basic syntax:

netlify [command]

To get detailed information about a specific command:

netlify [command] help

netlify [command]

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

When running netlify database init, the CLI scaffolds a starter database setup using a planets table. This includes a SQL migration for table creation and data insertion, as well as a Drizzle ORM schema definition. The setup is designed to work with PostgreSQL and uses the NETLIFY_DATABASE_URL environment variable for credentials.

-- Starter migration scaffolded by "netlify database init".
CREATE TABLE IF NOT EXISTS planets (
  id SERIAL PRIMARY KEY,
  name TEXT NOT NULL,
  mass_kg DOUBLE PRECISION NOT NULL,
  temperature_celsius INTEGER NOT NULL
);

INSERT INTO planets (name, mass_kg, temperature_celsius) VALUES
  ('Mercury', 3.30e23, 167),
  ('Venus', 4.87e24, 464),
  ('Earth', 5.97e24, 15),
  ('Mars', 6.42e23, -65),
  ('Jupiter', 1.898e27, -110),
  ('Saturn', 5.68e26, -140),
  ('Uranus', 8.68e25, -195),
  ('Neptune', 1.02e26, -200);

The CLI resolves the absolute path for migrations using the following priority:

1. The db.migrations.path value defined in your netlify.toml.
2. The default path: <project-root>/netlify/database/migrations.

If the CLI cannot determine the project root directory, it will throw an error: Could not determine the project root directory.