tessl/npm-env-cmd

Executes a command using the environment variables in an env file

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

env-cmd

Name: tessl/npm-env-cmd
Author: tessl

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;
}>;