or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-dotenv-cli

A global command-line executable to run applications with environment variables loaded from .env files

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/dotenv-cli@10.0.x

To install, run

npx @tessl/cli install tessl/npm-dotenv-cli@10.0.0

index.mddocs/

dotenv-cli

dotenv-cli is a command-line interface tool that enables developers to run applications with environment variables loaded from .env files. It provides comprehensive dotenv functionality including support for multiple .env files, variable expansion, cascading environment configurations, command-line variable setting, and cross-platform compatibility.

Package Information

  • Package Name: dotenv-cli
  • Package Type: npm
  • Language: JavaScript (Node.js)
  • Installation: npm install -g dotenv-cli or yarn global add dotenv-cli or pnpm add -g dotenv-cli

Core Usage

The primary usage pattern is:

dotenv [options] [-- command with arguments]

Basic command execution:

dotenv -- node app.js
dotenv -- npm start

Shorthand (when no command flags needed):

dotenv node app.js

Basic Usage

# Run application with .env file in current directory
dotenv -- node server.js

# Use custom environment file
dotenv -e .env.production -- node server.js

# Use multiple environment files (processed in order)
dotenv -e .env -e .env.local -- node server.js

# Set variables from command line
dotenv -v PORT=3000 -v NODE_ENV=development -- node server.js

# Check value of environment variable
dotenv -p NODE_ENV

# Debug mode - see what files and variables would be loaded
dotenv --debug

Capabilities

Environment File Loading

Load environment variables from .env files before executing commands.

# Load default .env file
dotenv -- <command>

# Load custom environment file
dotenv -e <path> -- <command>

# Load multiple environment files (processed in order)
dotenv -e <path1> -e <path2> -- <command>

Options:

  • -e <path>: Parse file at specified path as .env file (repeatable)
  • Default: .env if no -e flag specified

Usage Examples:

# Use production environment file
dotenv -e .env.production -- node app.js

# Load base config then environment-specific overrides
dotenv -e .env -e .env.local -e .env.production -- node app.js

# Load environment file from parent directory
dotenv -e ../.env -- node app.js

Cascading Environment Files

Support for loading multiple environment files in a cascading pattern, similar to Create React App and other modern development tools.

# Load .env and .env.local files
dotenv -c -- <command>

# Load environment-specific cascade: .env.{environment}.local, .env.local, .env.{environment}, .env
dotenv -c <environment> -- <command>

Options:

  • -c: Load .env and .env.local files
  • -c <environment>: Load .env.{environment}.local, .env.local, .env.{environment}, .env files
  • Cannot be used with -o/--override flag

Usage Examples:

# Load .env and .env.local
dotenv -c -- node app.js

# Load development environment cascade
dotenv -c development -- node app.js
# Loads: .env.development.local, .env.local, .env.development, .env

# Combine with custom env file path
dotenv -e config/.env -c development -- node app.js

Command-line Variable Setting

Set environment variables directly from command line, providing cross-platform alternative to shell variable setting.

# Set single variable
dotenv -v <name>=<value> -- <command>

# Set multiple variables
dotenv -v <name1>=<value1> -v <name2>=<value2> -- <command>

Options:

  • -v <name>=<value>: Set environment variable (repeatable)
  • Variables set via -v have higher priority than env file variables
  • Cross-platform alternative to VARIABLE=value command syntax

Usage Examples:

# Set PORT variable
dotenv -v PORT=3000 -- node server.js

# Set multiple variables
dotenv -v NODE_ENV=production -v PORT=8080 -v DEBUG=true -- node app.js

# Combine with env files (command-line variables take precedence)
dotenv -e .env -v PORT=3000 -- node server.js

Variable Inspection

Print environment variable values to console for debugging and verification.

# Print value of specific variable
dotenv -p <variable_name>

Options:

  • -p <variable>: Print value of specified environment variable
  • When used, command execution is skipped
  • Prints empty string if variable is undefined

Usage Examples:

# Check NODE_ENV value
dotenv -p NODE_ENV

# Check variable after loading env file
dotenv -e .env.production -p DATABASE_URL

# Check variable with cascading
dotenv -c production -p API_KEY

Variable Expansion

Support for variable expansion using ${VAR} syntax within .env files.

# Default: Variable expansion enabled
dotenv -- <command>

# Disable variable expansion
dotenv --no-expand -- <command>

Options:

  • Variable expansion enabled by default using dotenv-expand
  • --no-expand: Disable variable expansion for .env files containing literal ${} values

Usage Examples:

# .env file with expansion:
# BASE_URL=https://api.example.com
# USERS_URL=${BASE_URL}/users
# Default behavior - expansion enabled
dotenv -- node app.js

# Disable expansion when .env contains literal ${} values
dotenv --no-expand -- node app.js

System Variable Override

Override existing environment variables with values from .env files.

# Override system variables with env file values
dotenv -o -- <command>
dotenv --override -- <command>

Options:

  • -o, --override: Override existing environment variables with .env file values
  • Cannot be used with cascading (-c) flag
  • By default, existing environment variables take precedence

Usage Examples:

# Override system PATH with value from .env
dotenv -e .env --override -- node app.js

# Cannot combine with cascading
dotenv -c -o -- node app.js  # Error: conflicts with overrides

Debug and Help

Debug environment file processing and display help information.

# Show help information
dotenv --help

# Debug mode - show files and variables without executing command
dotenv --debug [other options]

# Control output verbosity
dotenv --quiet -- <command>
dotenv -q -- <command>

Options:

  • --help: Display help information and exit
  • --debug: Output files and variables that would be processed, then exit without running command
  • --quiet, -q: Suppress debug output (default: true, can be disabled with --quiet=false)

Usage Examples:

# Show all available options
dotenv --help

# Debug what files would be loaded
dotenv -e .env.production -c production --debug

# Disable quiet mode to see debug output
dotenv --quiet=false -e .env -- node app.js

Command Execution

Execute target commands with loaded environment variables.

# Best practice: use -- separator
dotenv [options] -- <command> [command_args]

# Shorthand: direct command (when no command flags needed)
dotenv [options] <command> [command_args]

Command Handling:

  • Best practice: Use -- separator before command
  • Everything after -- passed directly to target command
  • Without --, tool may strip flags intended for target command
  • Cross-platform process spawning with signal forwarding
  • Exit codes forwarded from target command

Usage Examples:

# Maven command with flags
dotenv -- mvn exec:java -Dexec.args="-g -f"

# NPM scripts
dotenv -e .env.test -- npm test

# Node.js applications
dotenv -v NODE_ENV=development -- node --inspect server.js

# Shell commands
dotenv -- bash -c 'echo "Port: $PORT"'

Error Handling

dotenv-cli provides clear error messages for common issues:

  • Invalid variable format: Variables must be in name=value format
  • Conflicting flags: Cannot use cascading (-c) with override (-o)
  • Missing command: Command required unless using -p flag
  • File not found: Silently ignores missing .env files (controlled by --quiet flag)

Cross-Platform Compatibility

dotenv-cli provides consistent behavior across operating systems:

  • Uses cross-spawn for reliable process spawning on Windows/Unix
  • Command-line variable setting (-v) works on all platforms
  • Signal handling (SIGINT, SIGTERM, etc.) forwarded to child processes
  • Path resolution works with both forward and backward slashes

Integration Patterns

Common integration patterns for development workflows:

# Package.json scripts
{
  "scripts": {
    "dev": "dotenv -e .env.development -- node server.js",
    "test": "dotenv -e .env.test -- jest",
    "prod": "dotenv -e .env.production -- node server.js"
  }
}

# Docker containers
RUN npm install -g dotenv-cli
CMD ["dotenv", "-e", ".env.production", "--", "node", "app.js"]

# CI/CD pipelines
dotenv -v NODE_ENV=production -v BUILD_ID=$BUILD_ID -- npm run build