or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

cli-interface.md core-execution.md environment-loading.md file-formats.md index.md utilities.md

tile.json

Command Line Interface

Comprehensive CLI system providing command-line argument parsing and integration with the core env-cmd functionality. The CLI supports extensive options for file specification, environment selection, and execution control.

Capabilities

CLI Function

Main CLI entry point that processes command-line arguments and executes commands.

/**
 * Executes env-cmd using command line arguments
 * @param args - Command line arguments to parse (without node and script name)
 * @returns Promise resolving to environment variables used
 */
function CLI(args: string[]): Promise<Environment>;

Usage Examples:

import { CLI } from "env-cmd";

// Parse and execute CLI arguments
const env = await CLI(["-f", ".env.production", "--", "node", "server.js"]);

// Parse arguments from process.argv
const env = await CLI(process.argv.slice(2));

Argument Parsing

Function for parsing command-line arguments into structured options.

/**
 * Parses the arguments passed into the cli
 * @param args - Array of command line arguments
 * @returns Parsed configuration for EnvCmd execution
 */
function parseArgs(args: string[]): EnvCmdOptions;

CLI Options:

interface CommanderOptions {
  /** List of environments for RC files */
  environments?: true | string[];
  /** Enable environment variable expansion */
  expandEnvs?: boolean;
  /** Enable recursive variable expansion */
  recursive?: boolean;
  /** Use fallback file locations */
  fallback?: boolean;
  /** Specify env file path */
  file?: true | string;
  /** Don't override existing environment variables */
  override?: boolean;
  /** Silent mode - suppress errors */
  silent?: boolean;
  /** Use shell for command execution */
  useShell?: boolean;
  /** Enable verbose logging */
  verbose?: boolean;
}

Command Line Options

File Selection Options

-f, --file <path> Specify custom environment file path:

env-cmd -f .env.production -- node server.js
env-cmd --file ./config/.env -- npm start

--fallback Enable fallback to default file locations if specified file not found:

env-cmd -f .env.missing --fallback -- node server.js

Environment Selection Options

-e, --environments <list> Specify comma-separated list of environments for RC files:

env-cmd -e development,staging -- node server.js
env-cmd --environments prod,staging -- npm test

Variable Processing Options

--expand-envs Enable expansion of environment variables in command and arguments:

env-cmd --expand-envs -- echo "API URL: $API_URL"
env-cmd --expand-envs -- node -e "console.log('$NODE_ENV')"

-r, --recursive Enable recursive expansion of environment variables:

env-cmd --recursive -- node server.js
env-cmd -r --expand-envs -- echo "$FULL_URL"

--no-override Prevent overriding existing process environment variables:

env-cmd --no-override -- node server.js

Execution Control Options

--use-shell Execute command using system shell:

env-cmd --use-shell -- "echo $PATH | grep node"
env-cmd --use-shell -- "npm run build && npm run test"

--silent Suppress error output for missing files:

env-cmd --silent -f .env.optional -- node server.js

-v, --verbose Enable verbose logging output:

env-cmd --verbose -f .env -- node server.js
env-cmd -v -e development -- npm start

Argument Processing

Command Separation

The CLI uses -- to separate env-cmd options from the command to execute:

env-cmd [options] -- <command> [command-args...]

Examples:

# Correct: options before --, command after
env-cmd -f .env.prod --verbose -- node server.js --port 3000

# Incorrect: missing separator
env-cmd -f .env.prod node server.js  # 'node' treated as env file

Option Parsing Process

Commander.js Integration: Uses @commander-js/extra-typings for type-safe parsing
Command Extraction: Identifies the command to execute from arguments
Argument Separation: Splits env-cmd options from command arguments
Option Processing: Converts parsed options to EnvCmdOptions format
Validation: Ensures required command is present

Boolean Option Handling

Some options have special boolean handling:

// --no-override sets noOverride: true
if (parsedCmdOptions.override === false) {
  noOverride = true;
}

// --use-shell enables shell execution
if (parsedCmdOptions.useShell === true) {
  useShell = true;
}

Binary Entry Point

The package provides an executable binary:

// bin/env-cmd.js
#!/usr/bin/env node
import { CLI } from '../dist/index.js'
CLI(process.argv.slice(2))

Installation and Usage:

# Global installation
npm install -g env-cmd
env-cmd -f .env.prod -- node server.js

# Local installation  
npm install env-cmd
npx env-cmd -f .env.prod -- node server.js
./node_modules/.bin/env-cmd -f .env.prod -- node server.js

Package.json Integration

Common patterns for integrating env-cmd with npm scripts:

{
  "scripts": {
    "start": "env-cmd -f .env -- node server.js",
    "start:prod": "env-cmd -f .env.production -- node server.js",
    "test": "env-cmd -e test -- jest",
    "dev": "env-cmd --expand-envs -- nodemon server.js"
  }
}

Error Handling

The CLI handles various error scenarios:

Missing Command:

env-cmd -f .env  # No command specified
# Error: env-cmd cannot be used as a standalone command

Invalid Arguments:

env-cmd --invalid-option -- node server.js
# Error from Commander.js argument parser

Command Execution Errors:

try {
  return await EnvCmd(parsedArgs);
} catch (e) {
  console.error(e);
  return process.exit(1);
}

Version Information

The CLI includes version information from package.json:

import packageJson from '../package.json' with { type: 'json' };

// Available through --version flag
program.version(packageJson.version);