Environment Variables

/**
 * Set environment variable value
 * Command: netlify env:set <key> [value] [options]
 */
interface EnvSetOptions {
  /** Deploy contexts to set variable for (can specify multiple) */
  context?: ('production' | 'deploy-preview' | 'branch-deploy' | 'dev' | string)[];
  /** Output result as JSON */
  json?: boolean;
  /** Variable scopes (can specify multiple) */
  scope?: ('builds' | 'functions' | 'post-processing' | 'runtime' | 'any')[];
  /** Mark variable as secret (encrypted storage) */
  secret?: boolean;
}

# Set variable for all contexts
netlify env:set API_KEY "your-api-key"

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

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

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

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

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

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

# Get JSON output
netlify env:set NEW_VAR "value" --json

/**
 * Get resolved value of environment variable
 * Command: netlify env:get <name> [options]
 */
interface EnvGetOptions {
  /** Deploy context (default: dev) */
  context?: 'production' | 'deploy-preview' | 'branch-deploy' | 'dev' | string;
  /** Output as JSON */
  json?: boolean;
  /** Variable scope filter */
  scope?: 'builds' | 'functions' | 'post-processing' | 'runtime' | 'any';
}

# Get variable for dev context (default)
netlify env:get API_KEY

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

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

# Get variable as JSON
netlify env:get API_KEY --json --context production

/**
 * List resolved environment variables
 * Command: netlify env:list [options]
 */
interface EnvListOptions {
  /** Deploy context (default: dev) */
  context?: 'production' | 'deploy-preview' | 'branch-deploy' | 'dev' | string;
  /** Output as JSON */
  json?: boolean;
  /** Output as plain text (key=value format) */
  plain?: boolean;
  /** Variable scope filter */
  scope?: 'builds' | 'functions' | 'post-processing' | 'runtime' | 'any';
}

# List all variables for dev context
netlify env:list

# List variables for production
netlify env:list --context production

# List variables as JSON
netlify env:list --json

# List variables as plain text
netlify env:list --plain

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

# List production function variables as JSON
netlify env:list --context production --scope functions --json

/**
 * Unset/remove environment variable
 * Command: netlify env:unset <key> [options]
 * Aliases: netlify env:delete, netlify env:remove
 */
interface EnvUnsetOptions {
  /** Deploy contexts to remove variable from (can specify multiple) */
  context?: ('production' | 'deploy-preview' | 'branch-deploy' | 'dev' | string)[];
  /** Output result as JSON */
  json?: boolean;
}

# Remove variable from all contexts
netlify env:unset OLD_API_KEY

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

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

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

# Alternative command names
netlify env:delete OLD_VAR
netlify env:remove OLD_VAR

/**
 * Import environment variables from .env file
 * Command: netlify env:import <fileName> [options]
 */
interface EnvImportOptions {
  /** Replace all existing variables with imported ones */
  replaceExisting?: boolean;
  /** Output result as JSON */
  json?: boolean;
}

# Import from .env file
netlify env:import .env

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

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

# Import from custom file
netlify env:import config/production.env

/**
 * Clone environment variables between projects
 * Command: netlify env:clone [options]
 * Alias: netlify env:migrate
 */
interface EnvCloneOptions {
  /** Source project ID */
  from?: string;
  /** Target project ID (required) */
  to: string;
}

# Clone from current project to another
netlify env:clone --to target-project-id

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

# Alternative command name
netlify env:migrate --from staging-site --to production-site

/**
 * Deployment context configuration
 */
type DeployContext = 
  | 'production'     // Production deployments
  | 'deploy-preview' // Pull request previews
  | 'branch-deploy'  // Branch deployments  
  | 'dev'           // Local development
  | `branch:${string}`; // Specific branch context

/**
 * Context-specific variable resolution
 */
interface ContextVariables {
  /** Base variables (available in all contexts) */
  base: Record<string, string>;
  /** Context-specific overrides */
  context: {
    [K in DeployContext]?: Record<string, string>;
  };
  /** Final resolved variables for a context */
  resolved: Record<string, string>;
}

/**
 * Variable scope definitions
 */
type VariableScope = 
  | 'builds'          // Available during build process
  | 'functions'       // Available to serverless functions
  | 'post-processing' // Available during post-processing
  | 'runtime'         // Available at runtime (client-side)
  | 'any';           // Available everywhere

/**
 * Scope-specific variable access
 */
interface ScopedVariables {
  builds: {
    /** Build-time variables */
    BUILD_COMMAND: string;
    NODE_VERSION: string;
    PYTHON_VERSION: string;
    /** Custom build variables */
    [key: string]: string;
  };
  
  functions: {
    /** Function runtime variables */
    DATABASE_URL: string;
    API_KEYS: string;
    /** Function-specific config */
    [key: string]: string;
  };
  
  runtime: {
    /** Client-accessible variables (prefixed with GATSBY_, NEXT_PUBLIC_, etc.) */
    GATSBY_API_URL: string;
    NEXT_PUBLIC_ANALYTICS_ID: string;
    REACT_APP_ENV: string;
    [key: string]: string;
  };
}

/**
 * Secret variable configuration
 */
interface SecretVariable {
  /** Variable key */
  key: string;
  /** Encrypted value (not directly accessible) */
  encryptedValue: string;
  /** Whether variable is marked as secret */
  isSecret: boolean;
  /** Contexts where secret is available */
  contexts: DeployContext[];
  /** Scopes where secret is available */
  scopes: VariableScope[];
  /** Creation timestamp */
  createdAt: Date;
  /** Last updated timestamp */
  updatedAt: Date;
}

/**
 * Secret management operations
 */
interface SecretManagement {
  /** Create secret variable */
  createSecret: (key: string, value: string, options: EnvSetOptions) => Promise<void>;
  /** Update secret variable */
  updateSecret: (key: string, newValue: string) => Promise<void>;
  /** Rotate secret (generate new value) */
  rotateSecret: (key: string) => Promise<string>;
  /** Delete secret variable */
  deleteSecret: (key: string) => Promise<void>;
}

/**
 * Built-in Netlify environment variables
 */
interface NetlifyBuiltInVars {
  /** General site information */
  URL: string;                    // Primary site URL
  DEPLOY_URL: string;            // Specific deploy URL
  DEPLOY_PRIME_URL: string;      // Primary deploy URL
  SITE_ID: string;               // Netlify site ID
  SITE_NAME: string;             // Site name
  
  /** Deploy context information */
  CONTEXT: DeployContext;        // Current deploy context
  BRANCH: string;                // Git branch being deployed
  HEAD: string;                  // Git commit SHA
  COMMIT_REF: string;            // Git commit reference
  
  /** Repository information */
  REPOSITORY_URL: string;        // Git repository URL
  PULL_REQUEST: string;          // Pull request number (if applicable)
  REVIEW_ID: string;             // Deploy preview ID
  
  /** Build information */
  BUILD_ID: string;              // Netlify build ID
  DEPLOY_ID: string;             // Netlify deploy ID
  NETLIFY: 'true';               // Indicates Netlify environment
  
  /** Development-specific variables */
  NETLIFY_DEV?: 'true';          // Present during local development
  NETLIFY_LOCAL?: 'true';        // Present during local development
}

/**
 * Environment file loading order (highest to lowest precedence)
 */
interface EnvFileSupport {
  files: [
    '.env.local',       // Local overrides (git-ignored)
    '.env.development', // Development-specific variables
    '.env',            // Default environment variables
  ];
  
  /** File format support */
  formats: {
    /** Standard .env format */
    dotenv: {
      example: 'KEY=value';
      multiline: 'KEY="line1\nline2"';
      comments: '# This is a comment';
      interpolation: 'PATH=$HOME/app';
    };
    
    /** JSON format support (.env.json) */
    json: {
      example: '{"KEY": "value", "NESTED": {"SUB": "value"}}';
    };
  };
}

/**
 * Environment variable validation
 */
interface EnvValidation {
  /** Required variables */
  required: string[];
  /** Optional variables with defaults */
  optional: Record<string, string>;
  /** Variable type definitions */
  types: {
    [key: string]: 'string' | 'number' | 'boolean' | 'url' | 'email' | 'json';
  };
  /** Custom validation patterns */
  patterns: {
    [key: string]: RegExp;
  };
  /** Validation errors */
  errors: Array<{
    key: string;
    message: string;
    type: 'missing' | 'invalid_type' | 'invalid_format';
  }>;
}