or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli-interface.mdcore-execution.mdenvironment-loading.mdfile-formats.mdindex.mdutilities.md
tile.json

index.mddocs/

env-cmd

env-cmd is a simple yet powerful Node.js tool for executing commands using environment variables loaded from various file formats. It supports both command-line usage and programmatic API access, with comprehensive file format support including .env, .env.json, .env.js, .env.ts, and multi-environment .env-cmdrc files.

Package Information

  • Package Name: env-cmd
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install env-cmd or npm install -g env-cmd
  • Node.js Version: >= 20.10.0

Core Imports

import { EnvCmd, CLI, GetEnvVars, type Environment, type EnvCmdOptions } from "env-cmd";

For CommonJS:

const { EnvCmd, CLI, GetEnvVars } = require("env-cmd");

Note: Additional utility functions like expandEnvs, resolveEnvFilePath, etc. are available via direct submodule imports (e.g., import { expandEnvs } from "env-cmd/dist/expand-envs.js").

Basic Usage

CLI Usage

# Use default .env file
env-cmd -- node server.js

# Use custom env file
env-cmd -f .env.production -- node server.js

# Use RC file with environments
env-cmd -e staging,production -- node server.js

# Enable environment variable expansion
env-cmd --expand-envs -- echo "API URL: $API_URL"

Programmatic Usage

import { EnvCmd, GetEnvVars } from "env-cmd";

// Execute command with environment variables
const env = await EnvCmd({
  command: "node",
  commandArgs: ["server.js"],
  envFile: { filePath: ".env.production" },
  options: {
    verbose: true,
    expandEnvs: true
  }
});

// Just load environment variables
const envVars = await GetEnvVars({
  envFile: { filePath: ".env" },
  verbose: true
});

Architecture

env-cmd is built around several key components:

  • Core Execution: EnvCmd function spawns processes with loaded environment variables
  • Environment Loading: Flexible file loading system supporting multiple formats and fallback strategies
  • CLI Interface: Command-line argument parsing with extensive options
  • File Parsing: Support for .env, JSON, JavaScript, TypeScript, and RC configuration formats
  • Signal Handling: Proper termination signal propagation between parent and child processes
  • Variable Expansion: Environment variable expansion with $var and ${var} syntax

Capabilities

Core Environment Command Execution

Main functionality for executing commands with environment variables loaded from files. Supports process spawning, signal handling, and variable expansion.

function EnvCmd(options: EnvCmdOptions): Promise<Environment>;

interface EnvCmdOptions {
  command: string;
  commandArgs: string[];
  envFile?: EnvFileOptions;
  rc?: RCFileOptions;
  options?: {
    expandEnvs?: boolean;
    recursive?: boolean;
    noOverride?: boolean;
    silent?: boolean;
    useShell?: boolean;
    verbose?: boolean;
  };
}

Core Execution

Environment Variable Loading

System for loading environment variables from various file formats with fallback support and error handling.

function getEnvVars(options?: GetEnvVarOptions): Promise<Environment>;
function getEnvFile(options: { filePath?: string, fallback?: boolean, verbose?: boolean }): Promise<Environment>;
function getRCFile(options: { environments: string[], filePath?: string, verbose?: boolean }): Promise<Environment>;

interface GetEnvVarOptions {
  envFile?: EnvFileOptions;
  rc?: RCFileOptions;
  verbose?: boolean;
}

Environment Loading

Command Line Interface

CLI system with comprehensive argument parsing and command execution integration.

function CLI(args: string[]): Promise<Environment>;
function parseArgs(args: string[]): EnvCmdOptions;

CLI Interface

File Format Support

Support for multiple environment file formats including .env, JSON, JavaScript, TypeScript, and RC files.

function getEnvFileVars(envFilePath: string): Promise<Environment>;
function getRCFileVars(options: { environments: string[], filePath: string }): Promise<Environment>;

File Formats

Utility Functions

Helper functions for path resolution, argument parsing, and environment variable expansion.

function expandEnvs(str: string, envs: Environment): string;
function resolveEnvFilePath(userPath: string): string;
function parseArgList(list: string): string[];

Utilities

Types

type Environment = Partial<Record<string, string>>;

type RCEnvironment = Partial<Record<string, Environment>>;

interface EnvFileOptions {
  filePath?: string;
  fallback?: boolean;
}

interface RCFileOptions {
  environments: string[];
  filePath?: string;
}

interface GetEnvVarOptions {
  envFile?: EnvFileOptions;
  rc?: RCFileOptions;
  verbose?: boolean;
}

interface EnvCmdOptions extends GetEnvVarOptions {
  command: string;
  commandArgs: string[];
  options?: {
    expandEnvs?: boolean;
    recursive?: boolean;
    noOverride?: boolean;
    silent?: boolean;
    useShell?: boolean;
    verbose?: boolean;
  };
}

type CommanderOptions = Command<[], {
  environments?: true | string[];
  expandEnvs?: boolean;
  recursive?: boolean;
  fallback?: boolean;
  file?: true | string;
  override?: boolean;
  silent?: boolean;
  useShell?: boolean;
  verbose?: boolean;
}>;

Supported File Formats

  • .env: Standard dotenv format with key=value pairs
  • .env.json: JSON objects with string key-value pairs
  • .env.js/.env.mjs: JavaScript modules exporting environment objects
  • .env.ts/.env.mts/.env.cts: TypeScript modules (requires tsx loader)
  • .env-cmdrc: Multi-environment configuration files
  • .env-cmdrc.json: JSON format multi-environment files
  • .env-cmdrc.js: JavaScript multi-environment files

Default File Locations

  • Environment files: ./.env, ./.env.js, ./.env.json
  • RC files: ./.env-cmdrc, ./.env-cmdrc.js, ./.env-cmdrc.json