0
# Environment Variables
1

2
Environment variable management system with context support for different deployment environments, scoped variables, and secure secret handling.
3

4
## Capabilities
5

6
### Set Environment Variables
7

8
Set environment variables with context and scope support for different deployment environments.
9

10
```typescript { .api }
11
/**
12
 * Set environment variable value
13
 * Command: netlify env:set <key> [value] [options]
14
 */
15
interface EnvSetOptions {
16
  /** Deploy contexts to set variable for (can specify multiple) */
17
  context?: ('production' | 'deploy-preview' | 'branch-deploy' | 'dev' | string)[];
18
  /** Output result as JSON */
19
  json?: boolean;
20
  /** Variable scopes (can specify multiple) */
21
  scope?: ('builds' | 'functions' | 'post-processing' | 'runtime' | 'any')[];
22
  /** Mark variable as secret (encrypted storage) */
23
  secret?: boolean;
24
}
25
```
26

27
**Usage Examples:**
28

29
```bash
30
# Set variable for all contexts
31
netlify env:set API_KEY "your-api-key"
32

33
# Set variable for specific context
34
netlify env:set DATABASE_URL "prod-db-url" --context production
35

36
# Set variable for multiple contexts
37
netlify env:set DEBUG_MODE "true" --context dev --context deploy-preview
38

39
# Set variable with specific scope
40
netlify env:set BUILD_COMMAND "npm run build:prod" --scope builds
41

42
# Set secret variable
43
netlify env:set SECRET_TOKEN "sensitive-value" --secret
44

45
# Set variable for functions only
46
netlify env:set FUNCTION_API_KEY "func-key" --scope functions
47

48
# Combine multiple options
49
netlify env:set STRIPE_KEY "sk_live_..." --context production --scope functions --secret
50

51
# Get JSON output
52
netlify env:set NEW_VAR "value" --json
53
```
54

55
### Get Environment Variables
56

57
Retrieve environment variable values with context and scope filtering.
58

59
```typescript { .api }
60
/**
61
 * Get resolved value of environment variable
62
 * Command: netlify env:get <name> [options]
63
 */
64
interface EnvGetOptions {
65
  /** Deploy context (default: dev) */
66
  context?: 'production' | 'deploy-preview' | 'branch-deploy' | 'dev' | string;
67
  /** Output as JSON */
68
  json?: boolean;
69
  /** Variable scope filter */
70
  scope?: 'builds' | 'functions' | 'post-processing' | 'runtime' | 'any';
71
}
72
```
73

74
**Usage Examples:**
75

76
```bash
77
# Get variable for dev context (default)
78
netlify env:get API_KEY
79

80
# Get variable for production context
81
netlify env:get DATABASE_URL --context production
82

83
# Get variable with scope filter
84
netlify env:get BUILD_COMMAND --scope builds
85

86
# Get variable as JSON
87
netlify env:get API_KEY --json --context production
88
```
89

90
### List Environment Variables
91

92
List all environment variables with filtering and formatting options.
93

94
```typescript { .api }
95
/**
96
 * List resolved environment variables
97
 * Command: netlify env:list [options]
98
 */
99
interface EnvListOptions {
100
  /** Deploy context (default: dev) */
101
  context?: 'production' | 'deploy-preview' | 'branch-deploy' | 'dev' | string;
102
  /** Output as JSON */
103
  json?: boolean;
104
  /** Output as plain text (key=value format) */
105
  plain?: boolean;
106
  /** Variable scope filter */
107
  scope?: 'builds' | 'functions' | 'post-processing' | 'runtime' | 'any';
108
}
109
```
110

111
**Usage Examples:**
112

113
```bash
114
# List all variables for dev context
115
netlify env:list
116

117
# List variables for production
118
netlify env:list --context production
119

120
# List variables as JSON
121
netlify env:list --json
122

123
# List variables as plain text
124
netlify env:list --plain
125

126
# List variables for specific scope
127
netlify env:list --scope functions
128

129
# List production function variables as JSON
130
netlify env:list --context production --scope functions --json
131
```
132

133
### Remove Environment Variables
134

135
Remove environment variables from specified contexts.
136

137
```typescript { .api }
138
/**
139
 * Unset/remove environment variable
140
 * Command: netlify env:unset <key> [options]
141
 * Aliases: netlify env:delete, netlify env:remove
142
 */
143
interface EnvUnsetOptions {
144
  /** Deploy contexts to remove variable from (can specify multiple) */
145
  context?: ('production' | 'deploy-preview' | 'branch-deploy' | 'dev' | string)[];
146
  /** Output result as JSON */
147
  json?: boolean;
148
}
149
```
150

151
**Usage Examples:**
152

153
```bash
154
# Remove variable from all contexts
155
netlify env:unset OLD_API_KEY
156

157
# Remove variable from specific context
158
netlify env:unset DEBUG_MODE --context dev
159

160
# Remove variable from multiple contexts
161
netlify env:unset TEMP_VAR --context dev --context deploy-preview
162

163
# Remove with JSON output
164
netlify env:unset OLD_VAR --json
165

166
# Alternative command names
167
netlify env:delete OLD_VAR
168
netlify env:remove OLD_VAR
169
```
170

171
### Import Environment Variables
172

173
Import environment variables from .env files with options for replacing existing variables.
174

175
```typescript { .api }
176
/**
177
 * Import environment variables from .env file
178
 * Command: netlify env:import <fileName> [options]
179
 */
180
interface EnvImportOptions {
181
  /** Replace all existing variables with imported ones */
182
  replaceExisting?: boolean;
183
  /** Output result as JSON */
184
  json?: boolean;
185
}
186
```
187

188
**Usage Examples:**
189

190
```bash
191
# Import from .env file
192
netlify env:import .env
193

194
# Import and replace existing variables
195
netlify env:import .env.production --replace-existing
196

197
# Import with JSON output
198
netlify env:import .env --json
199

200
# Import from custom file
201
netlify env:import config/production.env
202
```
203

204
### Clone Environment Variables
205

206
Clone environment variables between different projects for consistency.
207

208
```typescript { .api }
209
/**
210
 * Clone environment variables between projects
211
 * Command: netlify env:clone [options]
212
 * Alias: netlify env:migrate
213
 */
214
interface EnvCloneOptions {
215
  /** Source project ID */
216
  from?: string;
217
  /** Target project ID (required) */
218
  to: string;
219
}
220
```
221

222
**Usage Examples:**
223

224
```bash
225
# Clone from current project to another
226
netlify env:clone --to target-project-id
227

228
# Clone between specific projects
229
netlify env:clone --from source-project-id --to target-project-id
230

231
# Alternative command name
232
netlify env:migrate --from staging-site --to production-site
233
```
234

235
### Environment Variable Contexts
236

237
Different deployment contexts provide different environment variable sets:
238

239
```typescript { .api }
240
/**
241
 * Deployment context configuration
242
 */
243
type DeployContext = 
244
  | 'production'     // Production deployments
245
  | 'deploy-preview' // Pull request previews
246
  | 'branch-deploy'  // Branch deployments  
247
  | 'dev'           // Local development
248
  | `branch:${string}`; // Specific branch context
249

250
/**
251
 * Context-specific variable resolution
252
 */
253
interface ContextVariables {
254
  /** Base variables (available in all contexts) */
255
  base: Record<string, string>;
256
  /** Context-specific overrides */
257
  context: {
258
    [K in DeployContext]?: Record<string, string>;
259
  };
260
  /** Final resolved variables for a context */
261
  resolved: Record<string, string>;
262
}
263
```
264

265
### Variable Scopes
266

267
Environment variables can be scoped to different parts of the build and runtime process:
268

269
```typescript { .api }
270
/**
271
 * Variable scope definitions
272
 */
273
type VariableScope = 
274
  | 'builds'          // Available during build process
275
  | 'functions'       // Available to serverless functions
276
  | 'post-processing' // Available during post-processing
277
  | 'runtime'         // Available at runtime (client-side)
278
  | 'any';           // Available everywhere
279

280
/**
281
 * Scope-specific variable access
282
 */
283
interface ScopedVariables {
284
  builds: {
285
    /** Build-time variables */
286
    BUILD_COMMAND: string;
287
    NODE_VERSION: string;
288
    PYTHON_VERSION: string;
289
    /** Custom build variables */
290
    [key: string]: string;
291
  };
292
  
293
  functions: {
294
    /** Function runtime variables */
295
    DATABASE_URL: string;
296
    API_KEYS: string;
297
    /** Function-specific config */
298
    [key: string]: string;
299
  };
300
  
301
  runtime: {
302
    /** Client-accessible variables (prefixed with GATSBY_, NEXT_PUBLIC_, etc.) */
303
    GATSBY_API_URL: string;
304
    NEXT_PUBLIC_ANALYTICS_ID: string;
305
    REACT_APP_ENV: string;
306
    [key: string]: string;
307
  };
308
}
309
```
310

311
### Secret Management
312

313
Secure handling of sensitive environment variables:
314

315
```typescript { .api }
316
/**
317
 * Secret variable configuration
318
 */
319
interface SecretVariable {
320
  /** Variable key */
321
  key: string;
322
  /** Encrypted value (not directly accessible) */
323
  encryptedValue: string;
324
  /** Whether variable is marked as secret */
325
  isSecret: boolean;
326
  /** Contexts where secret is available */
327
  contexts: DeployContext[];
328
  /** Scopes where secret is available */
329
  scopes: VariableScope[];
330
  /** Creation timestamp */
331
  createdAt: Date;
332
  /** Last updated timestamp */
333
  updatedAt: Date;
334
}
335

336
/**
337
 * Secret management operations
338
 */
339
interface SecretManagement {
340
  /** Create secret variable */
341
  createSecret: (key: string, value: string, options: EnvSetOptions) => Promise<void>;
342
  /** Update secret variable */
343
  updateSecret: (key: string, newValue: string) => Promise<void>;
344
  /** Rotate secret (generate new value) */
345
  rotateSecret: (key: string) => Promise<string>;
346
  /** Delete secret variable */
347
  deleteSecret: (key: string) => Promise<void>;
348
}
349
```
350

351
### Built-in Environment Variables
352

353
Netlify automatically provides several built-in environment variables:
354

355
```typescript { .api }
356
/**
357
 * Built-in Netlify environment variables
358
 */
359
interface NetlifyBuiltInVars {
360
  /** General site information */
361
  URL: string;                    // Primary site URL
362
  DEPLOY_URL: string;            // Specific deploy URL
363
  DEPLOY_PRIME_URL: string;      // Primary deploy URL
364
  SITE_ID: string;               // Netlify site ID
365
  SITE_NAME: string;             // Site name
366
  
367
  /** Deploy context information */
368
  CONTEXT: DeployContext;        // Current deploy context
369
  BRANCH: string;                // Git branch being deployed
370
  HEAD: string;                  // Git commit SHA
371
  COMMIT_REF: string;            // Git commit reference
372
  
373
  /** Repository information */
374
  REPOSITORY_URL: string;        // Git repository URL
375
  PULL_REQUEST: string;          // Pull request number (if applicable)
376
  REVIEW_ID: string;             // Deploy preview ID
377
  
378
  /** Build information */
379
  BUILD_ID: string;              // Netlify build ID
380
  DEPLOY_ID: string;             // Netlify deploy ID
381
  NETLIFY: 'true';               // Indicates Netlify environment
382
  
383
  /** Development-specific variables */
384
  NETLIFY_DEV?: 'true';          // Present during local development
385
  NETLIFY_LOCAL?: 'true';        // Present during local development
386
}
387
```
388

389
### Environment File Support
390

391
Local development environment file support and precedence:
392

393
```typescript { .api }
394
/**
395
 * Environment file loading order (highest to lowest precedence)
396
 */
397
interface EnvFileSupport {
398
  files: [
399
    '.env.local',       // Local overrides (git-ignored)
400
    '.env.development', // Development-specific variables
401
    '.env',            // Default environment variables
402
  ];
403
  
404
  /** File format support */
405
  formats: {
406
    /** Standard .env format */
407
    dotenv: {
408
      example: 'KEY=value';
409
      multiline: 'KEY="line1\nline2"';
410
      comments: '# This is a comment';
411
      interpolation: 'PATH=$HOME/app';
412
    };
413
    
414
    /** JSON format support (.env.json) */
415
    json: {
416
      example: '{"KEY": "value", "NESTED": {"SUB": "value"}}';
417
    };
418
  };
419
}
420
```
421

422
### Variable Validation and Types
423

424
Environment variable validation and type checking:
425

426
```typescript { .api }
427
/**
428
 * Environment variable validation
429
 */
430
interface EnvValidation {
431
  /** Required variables */
432
  required: string[];
433
  /** Optional variables with defaults */
434
  optional: Record<string, string>;
435
  /** Variable type definitions */
436
  types: {
437
    [key: string]: 'string' | 'number' | 'boolean' | 'url' | 'email' | 'json';
438
  };
439
  /** Custom validation patterns */
440
  patterns: {
441
    [key: string]: RegExp;
442
  };
443
  /** Validation errors */
444
  errors: Array<{
445
    key: string;
446
    message: string;
447
    type: 'missing' | 'invalid_type' | 'invalid_format';
448
  }>;
449
}
450
```