0
# Netlify CLI
1

2
Netlify CLI is a command-line interface tool that enables developers to interact with Netlify's platform for modern web development and deployment. It provides comprehensive commands for managing sites, deploying applications, running local development servers, handling serverless functions, managing environment variables, and integrating with Netlify's edge functions and build system.
3

4
## Package Information
5

6
- **Package Name**: netlify-cli
7
- **Package Type**: npm
8
- **Language**: TypeScript/JavaScript
9
- **Installation**: `npm install -g netlify-cli`
10
- **Node.js Version**: >=20.12.2
11

12
## Core Imports
13

14
The CLI provides both command-line binaries and programmatic APIs:
15

16
**Command-line binaries:**
17
```bash
18
netlify --help
19
ntl --help  # short alias
20
```
21

22
**Programmatic API (Node.js):**
23
```typescript
24
import { NetlifyAPI, methods } from "netlify-cli";
25
```
26

27
For CommonJS:
28
```javascript
29
const { NetlifyAPI, methods } = require("netlify-cli");
30
```
31

32
## Basic Usage
33

34
**Quick start:**
35
```bash
36
# Install globally
37
npm install -g netlify-cli
38

39
# Login to Netlify
40
netlify login
41

42
# Initialize a project
43
netlify init
44

45
# Start local development
46
netlify dev
47

48
# Deploy to production
49
netlify deploy --prod
50
```
51

52
**Common workflow:**
53
```bash
54
# Clone a project with the CLI
55
netlify clone [repository]
56

57
# Link to existing Netlify site
58
netlify link
59

60
# Set environment variables
61
netlify env:set API_KEY "your-api-key"
62

63
# Run local development server with Netlify features
64
netlify dev --port 3000
65

66
# Deploy with build
67
netlify deploy --build --prod
68
```
69

70
## Architecture
71

72
The Netlify CLI is built on several key components:
73

74
- **Command System**: Built using Commander.js with a base command class and 24 main commands
75
- **Authentication**: OAuth-based login with persistent token storage
76
- **Local Development**: Full dev server with proxy, redirects, and serverless functions
77
- **Build Integration**: Integration with Netlify Build system and local builds
78
- **API Client**: Direct access to Netlify's REST API through programmatic interface
79
- **Deployment Engine**: Handles file uploads, build triggers, and deployment management
80
- **Environment Management**: Context-aware environment variable handling
81

82
## Capabilities
83

84
### Site Management
85

86
Core project and site management functionality for creating, linking, and configuring Netlify projects.
87

88
```typescript { .api }
89
// Command: netlify sites:create
90
interface SiteCreateOptions {
91
  name?: string;           // Project name (max 63 chars)
92
  accountSlug?: string;    // Account slug
93
  withCi?: boolean;        // Initialize CI hooks
94
  manual?: boolean;        // Force manual CI setup
95
  disableLinking?: boolean; // Create without linking
96
}
97

98
// Command: netlify link
99
interface LinkOptions {
100
  id?: string;             // Project ID to link
101
  name?: string;           // Project name to link
102
  gitRemoteName?: string;  // Git remote name
103
}
104
```
105

106
[Site Management](./site-management.md)
107

108
### Local Development
109

110
Local development server with Netlify's proxy, redirect rules, and serverless function support.
111

112
```typescript { .api }
113
// Command: netlify dev
114
interface DevOptions {
115
  command?: string;        // Command to run
116
  context?: string;        // Deploy context (default: dev)
117
  port?: number;           // Netlify dev port
118
  targetPort?: number;     // Target app server port
119
  framework?: string;      // Framework to use (#auto for detection)
120
  dir?: string;           // Static files directory
121
  functions?: string;      // Functions folder
122
  live?: string | boolean; // Start public live session
123
  geo?: 'cache' | 'mock' | 'update'; // Geolocation mode
124
  country?: string;        // Two-letter country code
125
  offline?: boolean;       // Disable network features
126
}
127
```
128

129
[Local Development](./local-development.md)
130

131
### Deployment
132

133
Build and deployment functionality with support for various contexts and deployment options.
134

135
```typescript { .api }
136
// Command: netlify deploy
137
interface DeployOptions {
138
  dir?: string;            // Directory to deploy
139
  functions?: string;      // Functions folder
140
  prod?: boolean;          // Deploy to production
141
  prodIfUnlocked?: boolean; // Deploy to production if unlocked
142
  alias?: string;          // Deployment alias (max 37 chars)
143
  message?: string;        // Deploy log message
144
  json?: boolean;          // Output as JSON
145
  timeout?: number;        // Deployment timeout
146
  build?: boolean;         // Run build command
147
  createSite?: string;     // Create new site during deployment
148
}
149
```
150

151
[Deployment](./deployment.md)
152

153
### Environment Variables
154

155
Environment variable management with context support for different deployment environments.
156

157
```typescript { .api }
158
// Command: netlify env:set
159
interface EnvSetOptions {
160
  context?: string[];      // Deploy contexts (multiple)
161
  scope?: ('builds' | 'functions' | 'post-processing' | 'runtime' | 'any')[]; // Variable scopes
162
  secret?: boolean;        // Mark as secret variable
163
  json?: boolean;          // Output as JSON
164
}
165

166
// Command: netlify env:get
167
interface EnvGetOptions {
168
  context?: string;        // Deploy context (default: dev)
169
  scope?: 'builds' | 'functions' | 'post-processing' | 'runtime' | 'any'; // Variable scope
170
  json?: boolean;          // Output as JSON
171
}
172
```
173

174
[Environment Variables](./environment-variables.md)
175

176
### Functions
177

178
Serverless function management including creation, testing, and deployment of Netlify Functions.
179

180
```typescript { .api }
181
// Command: netlify functions:create
182
interface FunctionCreateOptions {
183
  name?: string;           // Function name
184
  url?: string;            // Template URL
185
  language?: string;       // Function language
186
  offline?: boolean;       // Disable network features
187
}
188

189
// Command: netlify functions:invoke
190
interface FunctionInvokeOptions {
191
  name?: string;           // Function name
192
  functions?: string;      // Functions folder
193
  querystring?: string;    // Query string
194
  payload?: string;        // POST payload
195
  identity?: boolean;      // Simulate Netlify Identity JWT
196
  noIdentity?: boolean;    // Simulate unauthenticated request
197
  port?: number;          // Netlify dev port
198
}
199
```
200

201
[Functions](./functions.md)
202

203
### Blobs Storage
204

205
Object storage management for Netlify Blobs with CRUD operations and metadata handling.
206

207
```typescript { .api }
208
// Command: netlify blobs:set
209
interface BlobSetOptions {
210
  input?: string;          // Read data from filesystem path
211
}
212

213
// Command: netlify blobs:get
214
interface BlobGetOptions {
215
  output?: string;         // Output path to save blob data
216
}
217

218
// Command: netlify blobs:list
219
interface BlobListOptions {
220
  directories?: boolean;   // Treat keys with '/' as directories
221
  prefix?: string;         // Filter entries by prefix
222
  json?: boolean;          // Output as JSON
223
}
224
```
225

226
[Blobs Storage](./blobs-storage.md)
227

228
### Build System
229

230
Local and remote build functionality with context support and offline capabilities.
231

232
```typescript { .api }
233
// Command: netlify build
234
interface BuildOptions {
235
  context?: string;        // Deploy context (default: production)
236
  dry?: boolean;          // Show instructions without running
237
  offline?: boolean;       // Disable network features
238
}
239

240
// Command: netlify serve
241
interface ServeOptions {
242
  context?: string;        // Deploy context
243
  port?: number;          // Server port
244
  dir?: string;           // Static files directory
245
  functions?: string;      // Functions folder
246
  geo?: 'cache' | 'mock' | 'update'; // Geolocation mode
247
}
248
```
249

250
[Build System](./build-system.md)
251

252
### Authentication & Teams
253

254
Authentication management and team switching functionality for multi-account workflows.
255

256
```typescript { .api }
257
// Command: netlify login
258
interface LoginOptions {
259
  new?: boolean;           // Login to new account
260
}
261
```
262

263
[Authentication & Teams](./authentication-teams.md)
264

265
### Database Management
266

267
PostgreSQL database provisioning and management for modern web applications.
268

269
```typescript { .api }
270
// Command: netlify database:init
271
interface DatabaseInitOptions {
272
  assumeNo?: boolean;          // Non-interactive setup
273
  boilerplate?: 'drizzle';     // Type of boilerplate to add
274
  noBoilerplate?: boolean;     // Don't add boilerplate code
275
  overwrite?: boolean;         // Overwrite existing files
276
}
277

278
// Command: netlify database:status
279
interface DatabaseStatusOptions {
280
  /** No additional options */
281
}
282
```
283

284
### Project Cloning
285

286
Clone Git repositories with optional framework filtering for quick project setup.
287

288
```typescript { .api }
289
// Command: netlify clone [repository] [directory]
290
interface CloneOptions {
291
  filter?: string;             // Filter template results by framework
292
}
293
```
294

295
### File Watching
296

297
Watch for project changes and deploy automatically for continuous deployment workflows.
298

299
```typescript { .api }
300
// Command: netlify watch
301
interface WatchOptions {
302
  dir?: string;                // Directory to deploy
303
  functions?: string;          // Functions folder
304
}
305
```
306

307
### Log Management
308

309
Stream and view logs from builds and serverless functions for debugging and monitoring.
310

311
```typescript { .api }
312
// Command: netlify logs:deploy (alias: logs:build)
313
interface LogsDeployOptions {
314
  /** No additional options */
315
}
316

317
// Command: netlify logs:function [functionName]
318
interface LogsFunctionOptions {
319
  level?: ('trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal')[]; // Log levels to stream
320
}
321
```
322

323
### Project Recipes
324

325
Interactive setup and configuration templates for different frameworks and use cases.
326

327
```typescript { .api }
328
// Command: netlify recipes
329
interface RecipesOptions {
330
  /** Interactive recipe selection */
331
}
332
```
333

334
### Development Execution
335

336
Execute commands in the development environment context with full access to environment variables.
337

338
```typescript { .api }
339
// Command: netlify dev-exec <command...>
340
interface DevExecOptions {
341
  context?: string;            // Deploy context for environment variables
342
}
343
```
344

345
### Resource Opening
346

347
Open project resources and admin interfaces in browser for quick access.
348

349
```typescript { .api }
350
// Command: netlify open:admin
351
interface OpenAdminOptions {
352
  /** No additional options */
353
}
354

355
// Command: netlify open:site
356
interface OpenSiteOptions {
357
  /** No additional options */
358
}
359
```
360

361
### API Access
362

363
Direct access to Netlify's REST API for advanced automation and custom integrations.
364

365
```typescript { .api }
366
// Command: netlify api
367
interface ApiOptions {
368
  data?: string;               // JSON data payload for API call
369
  list?: boolean;              // List all available API methods
370
}
371
```
372

373
### Shell Completion
374

375
Generate shell completion scripts for improved command-line productivity.
376

377
```typescript { .api }
378
// Command: netlify completion
379
interface CompletionOptions {
380
  shell?: 'bash' | 'zsh' | 'fish' | 'powershell'; // Target shell
381
}
382
```
383

384
## Global Options
385

386
All commands support these global options:
387

388
```typescript { .api }
389
interface GlobalOptions {
390
  telemetryDisable?: boolean; // Disable usage telemetry
391
  telemetryEnable?: boolean;  // Enable usage telemetry
392
  version?: boolean;          // Show version information
393
  verbose?: boolean;          // Show detailed environment information
394
  auth?: string;              // Authentication token
395
  debug?: boolean;            // Enable debug mode
396
  cwd?: string;               // Working directory (hidden but functional)
397
  httpProxy?: string;         // HTTP proxy configuration (hidden)
398
  silent?: boolean;           // Silence output (hidden)
399
  filter?: string;            // Monorepo package selection
400
}
401
```
402

403
## Deploy Contexts
404

405
The CLI supports context-aware operations for different deployment environments:
406

407
- `production` - Production environment
408
- `deploy-preview` - Deploy preview environment (pull requests)
409
- `branch-deploy` - Branch deployment environment
410
- `dev` - Development environment (local)
411
- `branch:branch-name` - Specific branch context
412

413
## Types
414

415
```typescript { .api }
416
type DeployContext = 'production' | 'deploy-preview' | 'branch-deploy' | 'dev' | `branch:${string}`;
417

418
type VariableScope = 'builds' | 'functions' | 'post-processing' | 'runtime' | 'any';
419

420
type GeoMode = 'cache' | 'mock' | 'update';
421

422
type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
423

424
interface NetlifyConfig {
425
  build?: {
426
    command?: string;
427
    publish?: string;
428
    functions?: string;
429
  };
430
  redirects?: Array<{
431
    from: string;
432
    to: string;
433
    status?: number;
434
  }>;
435
  headers?: Array<{
436
    for: string;
437
    values: Record<string, string>;
438
  }>;
439
}
440
```
441

442
## Programmatic API
443

444
The CLI also provides programmatic access to Netlify's API:
445

446
```typescript { .api }
447
/**
448
 * Netlify API client for programmatic access
449
 * Re-exported from @netlify/api package
450
 */
451
class NetlifyAPI {
452
  constructor(token?: string, options?: ApiOptions);
453
  
454
  // Site management
455
  listSites(): Promise<Site[]>;
456
  getSite(siteId: string): Promise<Site>;
457
  createSite(params: CreateSiteParams): Promise<Site>;
458
  deleteSite(siteId: string): Promise<void>;
459
  
460
  // Deploy management
461
  listDeploys(siteId: string): Promise<Deploy[]>;
462
  getDeploy(deployId: string): Promise<Deploy>;
463
  createDeploy(siteId: string, params: CreateDeployParams): Promise<Deploy>;
464
  
465
  // Function management
466
  listFunctions(siteId: string): Promise<Function[]>;
467
  // ... additional API methods
468
}
469

470
/**
471
 * API method definitions
472
 * Re-exported from @netlify/api package
473
 */
474
const methods: {
475
  listSites: ApiMethod;
476
  getSite: ApiMethod;
477
  createSite: ApiMethod;
478
  // ... additional method definitions
479
};
480
```