Envsub

https://www.npmjs.com/package/envsub
Admin
Envsub is a Node.js environment variable substitution tool that performs file-level template...
Tokens:11,027
Snippets:151
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install envsub

Source: https://www.npmjs.com/package/envsub?activeTab=readme

Installation commands for the package.

```bash
npm install --save envsub # yes this is correct, see require statement below
```

```bash
npm i envsub
```

--------------------------------

### CLI Usage and Help

Source: https://www.npmjs.com/package/envsub?activeTab=versions

Access the help menu and view usage examples for the envsubh command-line interface.

```bash
envsubh --help
```

```bash
  Usage: envsubh [options] <templateFile> [outputFile]

  Options:

    -h, --help     output usage information
    -V, --version  output the version number
    -d, --diff     show diff between template file and output file

  Examples:

    Typical usage
    -------------
    $ envsubh templateFile outputFile
    $ envsubh --diff templateFile outputFile

    Overwrite your template file
    ----------------------------
    After copying a template file into a docker image, it is useful to overwrite the copied file with its substituted equivalent.
    $ envsubh templateFile
    $ envsubh -d templateFile
```

--------------------------------

### .env File Syntax Example

Source: https://www.npmjs.com/package/envsub?activeTab=dependencies

Example of supported syntax within a .env file for loading environment variables.

```dotenv
# example comment
MYVAR1               # same as --env MYVAR1
export MYVAR2        # same as --env MYVAR2
MYVAR3=hello         # same as --env MYVAR3=hello
export MYVAR4=hello  # same as --env MYVAR4=hello

```

--------------------------------

### CLI Usage Examples

Source: https://www.npmjs.com/package/envsub?activeTab=dependencies

Common CLI commands for rendering templates and managing output files.

```bash
envsubh templateFile outputFile
```

```bash
envsubh --diff templateFile outputFile
```

```bash
envsubh templateFile
```

```bash
envsubh -d templateFile
```

--------------------------------

### CLI Usage Examples

Source: https://www.npmjs.com/package/envsub?activeTab=readme

Common command-line interface patterns for rendering templates and viewing differences.

```bash
envsubh templateFile outputFile
```

```bash
envsubh templateFile
```

```bash
envsubh --diff templateFile outputFile
```

```bash
envsubh --help
```

```bash
  Usage: envsubh [options] <templateFile> [outputFile]

  Options:

    -h, --help     output usage information
    -V, --version  output the version number
    -d, --diff     show diff between template file and output file

  Examples:

    Typical usage
    -------------
    $ envsubh templateFile outputFile
    $ envsubh --diff templateFile outputFile

    Overwrite your template file
    ----------------------------
    After copying a template file into a docker image, it is useful to overwrite the copied file with its substituted equivalent.
    $ envsubh templateFile
    $ envsubh -d templateFile
```

--------------------------------

### Define .env file syntax

Source: https://www.npmjs.com/package/envsub?activeTab=readme

Example of supported syntax for .env files used with the --env-file flag.

```text
# example comment
MYVAR1               # same as --env MYVAR1
export MYVAR2        # same as --env MYVAR2
MYVAR3=hello         # same as --env MYVAR3=hello
export MYVAR4=hello  # same as --env MYVAR4=hello
```

--------------------------------

### envsub Advanced CLI Usage Example

Source: https://www.npmjs.com/package/envsub?activeTab=readme

An example showcasing various flags for diffing, specifying environment variables, using .env files, protecting variables, and setting substitution syntax.

```bash
envsub --diff --env MYVAR1 --env MYVAR2=foo --env-file envFile.env --protect --syntax dollar-both --system templateFile outputFile
```

--------------------------------

### Install envsub Package

Source: https://www.npmjs.com/package/envsub?activeTab=dependencies

Installation command for the envsub package.

```bash
npm install --save envsub
```

```bash
npm i envsub
```

--------------------------------

### Install envsub Globally

Source: https://www.npmjs.com/package/envsub?activeTab=readme

Command to install the envsub package globally, which also installs the envsubh executable.

```bash
npm install -g envsub # yes, this also globally installs envsubh
```

--------------------------------

### Install envsub globally

Source: https://www.npmjs.com/package/envsub?activeTab=readme

Install the envsub CLI tool globally using npm.

```bash
npm install -g envsub
```

--------------------------------

### Build Docker Image with Run-Time Templating

Source: https://www.npmjs.com/package/envsub?activeTab=readme

Example Dockerfile commands for building an image and then running containers with run-time environment variable substitution.

```bash
docker build -t danday74/envsub-run-example .
```

```bash
docker run --name envrun1 -d -e MY_NAME=Daniel -p "8081:8080" danday74/envsub-run-example
```

```bash
docker run --name envrun2 -d -e MY_NAME=Jimbob -p "8082:8080" danday74/envsub-run-example
```

--------------------------------

### Execute envsub CLI commands

Source: https://www.npmjs.com/package/envsub?activeTab=dependents

Examples of standard CLI usage for file substitution and diffing.

```bash
$ envsub templateFile outputFile
$ envsub --diff --env MYVAR1 --env MYVAR2=foo --env-file envFile.env --protect --syntax dollar-both --system templateFile outputFile
```

--------------------------------

### Install envsub package

Source: https://www.npmjs.com/package/envsub?activeTab=code

Install the envsub package using npm. This is required for local promise-based usage.

```bash
npm i envsub
```

--------------------------------

### Install envsub Locally

Source: https://www.npmjs.com/package/envsub?activeTab=readme

Command to install the envsub package as a project dependency using npm.

```bash
npm install --save envsub
```

--------------------------------

### envsub Overwrite Template File Example

Source: https://www.npmjs.com/package/envsub?activeTab=readme

This example shows how to overwrite the template file with its substituted content, useful in Docker image builds.

```bash
envsub templateFile
```

--------------------------------

### Run Docker Container with Run-time Templating (Instance 1)

Source: https://www.npmjs.com/package/envsub?activeTab=versions

Example command to run a Docker container with run-time templating, setting an environment variable and exposing a port.

```bash
docker run --name envrun1 -d -e MY_NAME=Daniel -p "8081:8080" danday74/envsub-run-example
```

--------------------------------

### Run Docker Container with Build-time Templating

Source: https://www.npmjs.com/package/envsub?activeTab=versions

Example command to run a Docker container built with build-time templating, exposing a port.

```bash
docker run --name envbuild -d -p "8080:8080" danday74/envsub-build-example
```

--------------------------------

### Build Docker Image with Build-Time Templating

Source: https://www.npmjs.com/package/envsub?activeTab=readme

Example Dockerfile commands for building an image with build-time environment variable substitution using envsub.

```bash
docker build --build-arg MY_NAME=Daniel -t danday74/envsub-build-example .
```

```bash
docker run --name envbuild -d -p "8080:8080" danday74/envsub-build-example
```

--------------------------------

### Build Docker Image with Run-time Templating

Source: https://www.npmjs.com/package/envsub?activeTab=versions

Example Dockerfile command for building an image intended for run-time environment variable substitution.

```bash
docker build -t danday74/envsub-run-example .
```

--------------------------------

### CLI Usage Examples

Source: https://www.npmjs.com/package/envsub

Common patterns for using the envsub CLI, including basic substitution, diffing, and overwriting files.

```bash
$ envsub templateFile outputFile
$ envsub --diff --env MYVAR1 --env MYVAR2=foo --env-file envFile.env --protect --syntax dollar-both --system templateFile outputFile
$ envsub templateFile
$ envsub -d -e MYVAR1 -e MYVAR2=foo -f envFile.env -p -s dollar-both -S templateFile
```

--------------------------------

### Build Docker Image with Build-time Templating

Source: https://www.npmjs.com/package/envsub?activeTab=versions

Example Dockerfile command for building an image with build-time environment variable substitution using envsub.

```bash
docker build --build-arg MY_NAME=Daniel -t danday74/envsub-build-example .
```

--------------------------------

### Run Docker Container with Run-time Templating (Instance 2)

Source: https://www.npmjs.com/package/envsub?activeTab=versions

Example command to run a second instance of a Docker container with run-time templating, using a different environment variable value.

```bash
docker run --name envrun2 -d -e MY_NAME=Jimbob -p "8082:8080" danday74/envsub-run-example
```

--------------------------------

### envsubh CLI Usage

Source: https://www.npmjs.com/package/envsub?activeTab=dependencies

This section covers the command-line interface for envsubh, including basic usage, options, and examples.

```APIDOC
## envsubh CLI Usage

### Description
Performs file-level handlebars template rendering using environment variables as data. Supports conditional statements and other Handlebars features.

### Method
N/A (CLI Tool)

### Endpoint
N/A (CLI Tool)

### Parameters
#### Path Parameters
- **templateFile** (string) - Required - The path to the template file.
- **outputFile** (string) - Optional - The path to the output file. If not provided, the template file is overwritten.

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```bash
$ envsubh templateFile outputFile
$ envsubh --diff templateFile outputFile
$ envsubh templateFile
$ envsubh -d templateFile
```

### Response
N/A (CLI Tool outputs to file or console)

### Options
- **-h, --help** - output usage information
- **-V, --version** - output the version number
- **-d, --diff** - show diff between template file and output file
```

--------------------------------

### Local Promise-based envsub Usage

Source: https://www.npmjs.com/package/envsub?activeTab=readme

Example of using the envsub Node.js module with promise-based API, mirroring CLI flags for configuration.

```javascript
const envsub = require('envsub');

let templateFile = `${__dirname}/templateFile`;
let outputFile = `${__dirname}/outputFile`;
let options = {
  all: false, // see --all flag
  diff: false, // see --diff flag
  envs: [
    {name: 'MYVAR1'}, // see --env flag
    {name: 'MYVAR2', value: 'station'} // see --env flag
  ],
  envFiles: [
    `${__dirname}/envFile.env` // see --env-file flag
  ],
  protect: false, // see --protect flag
  syntax: 'default', // see --syntax flag
  system: true // see --system flag
};

// create (or overwrite) the output file
envsub({templateFile, outputFile, options}).then((envobj) => {
  // output file created
  console.log(envobj.templateFile);
  console.log(envobj.templateContents);
  console.log(envobj.outputFile);
  console.log(envobj.outputContents);
}).catch((err) => {
  console.error(err.message);
});
```

--------------------------------

### envsubh CLI Usage

Source: https://www.npmjs.com/package/envsub?activeTab=dependents

This section details the command-line interface for envsubh, including its options and examples for basic usage, diffing, and overwriting template files.

```APIDOC
## envsubh CLI Usage

### Description
Performs file-level handlebars template rendering using environment variables as data. Supports conditional statements and other Handlebars features.

### Method
CLI Command

### Endpoint
`envsubh [options] <templateFile> [outputFile]`

### Parameters
#### Query Parameters
- **templateFile** (string) - Required - The path to the template file.
- **outputFile** (string) - Optional - The path to the output file. If not provided, the template file will be overwritten.

#### Options
- **-h, --help** - output usage information
- **-V, --version** - output the version number
- **-d, --diff** - show diff between template file and output file

### Request Example
```bash
$ envsubh templateFile outputFile
$ envsubh --diff templateFile outputFile
$ envsubh templateFile
$ envsubh -d templateFile
```

### Response
#### Success Response (200)
- **output** (string) - The rendered content written to the output file or stdout.

#### Response Example
(CLI output depends on the template and environment variables)

```

--------------------------------

### envsubh CLI Usage

Source: https://www.npmjs.com/package/envsub

This section covers the basic command-line interface for envsubh, including its options and examples for typical use cases and overwriting files.

```APIDOC
## envsubh CLI Usage

### Description
Performs file-level handlebars template rendering using environment variables as data. Supports conditional statements and other Handlebars features.

### Method
CLI Command

### Endpoint
`envsubh [options] <templateFile> [outputFile]`

### Parameters
#### Path Parameters
- **templateFile** (string) - Required - The path to the template file.
- **outputFile** (string) - Optional - The path to the output file. If not provided, the template file will be overwritten.

#### Query Parameters
- **-h, --help** (boolean) - Output usage information.
- **-V, --version** (boolean) - Output the version number.
- **-d, --diff** (boolean) - Show diff between template file and output file.

### Request Example
```bash
$ envsubh templateFile outputFile
$ envsubh --diff templateFile outputFile
$ envsubh templateFile
$ envsubh -d templateFile
```

### Response
#### Success Response (200)
- **outputFile** (string) - Path to the generated output file.
- **outputContents** (string) - Content of the generated output file.

#### Response Example
(CLI output will vary based on input and options. For programmatic response, see API usage.)
```

--------------------------------

### envsubh Local Promise-based Usage

Source: https://www.npmjs.com/package/envsub?activeTab=code

Provides an example of using envsubh programmatically within a Node.js application using promises.

```APIDOC
## envsubh Local Promise-based Usage

### Description
Local promise-based options are a perfect reflection of global CLI flags. This allows for programmatic use of envsubh within Node.js applications.

### Method
Node.js require and function call

### Endpoint
`require('envsub/envsubh')`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
`envsubh({templateFile, outputFile, options})`
- **templateFile** (string) - Required - Path to the template file.
- **outputFile** (string) - Required - Path to the output file.
- **options** (object) - Optional - Configuration options.
  - **diff** (boolean) - Corresponds to the `--diff` flag. Defaults to `false`.

### Request Example
```javascript
const envsubh = require('envsub/envsubh');

let templateFile = `${__dirname}/templateFile`;
let outputFile = `${__dirname}/outputFile`;
let options = {
  diff: false // see --diff flag
};

// create (or overwrite) the output file
envsubh({templateFile, outputFile, options}).then((envobj) => {
  // output file created
  console.log(envobj.templateFile);
  console.log(envobj.templateContents);
  console.log(envobj.outputFile);
  console.log(envobj.outputContents);
}).catch((err) => {
  console.error(err.message);
});
```

### Response
Returns a Promise that resolves with an object containing details about the processed files.

#### Success Response (200)
- **templateFile** (string) - The path to the template file.
- **templateContents** (string) - The original content of the template file.
- **outputFile** (string) - The path to the output file.
- **outputContents** (string) - The rendered content of the output file.

#### Response Example
```json
{
  "templateFile": "/path/to/templateFile",
  "templateContents": "Hello {{name}}!",
  "outputFile": "/path/to/outputFile",
  "outputContents": "Hello World!"
}
```
```

--------------------------------

### Display CLI Help

Source: https://www.npmjs.com/package/envsub?activeTab=dependencies

Displays the help menu for the envsubh command-line interface.

```bash
envsubh --help
```

--------------------------------

### Display envsub Help Information

Source: https://www.npmjs.com/package/envsub?activeTab=readme

Use this command to display the help message and available options for the envsub CLI.

```bash
envsub --help
```

--------------------------------

### envsubh CLI Usage

Source: https://www.npmjs.com/package/envsub?activeTab=code

Demonstrates the command-line interface for envsubh, including basic usage, diffing, and overwriting template files.

```APIDOC
## envsubh CLI Usage

### Description
Performs file-level handlebars template rendering using environment variables as data. Supports conditional statements and other Handlebars features.

### Method
CLI Command

### Endpoint
`envsubh [options] <templateFile> [outputFile]`

### Parameters
#### Path Parameters
- **templateFile** (string) - Required - The path to the template file.
- **outputFile** (string) - Optional - The path to the output file. If not provided, the template file will be overwritten.

#### Query Parameters
None

#### Options
- **-h, --help** (boolean) - Output usage information.
- **-V, --version** (boolean) - Output the version number.
- **-d, --diff** (boolean) - Show diff between the template file and the output file.

### Request Example
```bash
$ envsubh templateFile outputFile
$ envsubh --diff templateFile outputFile
$ envsubh templateFile
$ envsubh -d templateFile
```

### Response
Outputs the rendered file content to the specified outputFile or overwrites the templateFile.

#### Success Response (200)
File content is written to the output.

#### Response Example
(No specific response example provided for CLI, output is file content)
```

--------------------------------

### envsub Typical CLI Usage

Source: https://www.npmjs.com/package/envsub?activeTab=readme

Demonstrates the basic command-line usage for substituting variables in a template file and writing to an output file.

```bash
envsub templateFile outputFile
```

--------------------------------

### envsub with Diff Flag

Source: https://www.npmjs.com/package/envsub?activeTab=dependencies

Log the difference between the template file and the output file. Useful for debugging substitutions.

```bash
envsub --diff templateFile outputFile
```

--------------------------------

### envsub CLI with Custom Syntax

Source: https://www.npmjs.com/package/envsub?activeTab=dependencies

Specify the template substitution syntax using the --syntax flag. Supported syntaxes include dollar-basic, dollar-curly, dollar-both, and handlebars.

```bash
envsub --syntax handlebars templateFile outputFile
```

--------------------------------

### envsub Overwrite Template File with Advanced Flags

Source: https://www.npmjs.com/package/envsub?activeTab=readme

Demonstrates overwriting a template file using advanced CLI options like diff, environment variables, .env files, protection, and syntax.

```bash
envsub -d -e MYVAR1 -e MYVAR2=foo -f envFile.env -p -s dollar-both -S templateFile
```

--------------------------------

### Local Promise-based Usage of envsubh

Source: https://www.npmjs.com/package/envsub

Demonstrates how to use envsubh programmatically with Promises. This mirrors the CLI flags and is useful for scripting within Node.js applications.

```javascript
const envsubh = require('envsub/envsubh');

let templateFile = `${__dirname}/templateFile`;
let outputFile = `${__dirname}/outputFile`;
let options = {
  diff: false // see --diff flag
};

// create (or overwrite) the output file
envsubh({templateFile, outputFile, options}).then((envobj) => {
  // output file created
  console.log(envobj.templateFile);
  console.log(envobj.templateContents);
  console.log(envobj.outputFile);
  console.log(envobj.outputContents);
}).catch((err) => {
  console.error(err.message);
});

```

--------------------------------

### Use dollar-curly default values

Source: https://www.npmjs.com/package/envsub?activeTab=readme

Demonstration of default value substitution syntax for dollar-curly placeholders.

```text
# Before substitution
Variable with default value: ${VARIABLE_NAME:-default}.
# After substitution
Variable with default value: default.

# Before substitution
Variable with default value + whitespaces: ${VARIABLE_NAME:-        default value }.
# After substitution
Variable with default value + whitespaces:         default value .
```

--------------------------------

### envsubh Programmatic Usage (Node.js)

Source: https://www.npmjs.com/package/envsub

Demonstrates how to use envsubh as a Node.js module for promise-based environment variable substitution.

```APIDOC
## envsubh Programmatic Usage

### Description
Provides a promise-based API for performing environment variable substitution within template files, mirroring the CLI options.

### Method
`require('envsub/envsubh')`

### Endpoint
`envsubh({ templateFile, outputFile, options })`

### Parameters
#### Request Body
- **templateFile** (string) - Required - Path to the template file.
- **outputFile** (string) - Optional - Path to the output file. If omitted, the template file is overwritten.
- **options** (object) - Optional - Configuration options.
  - **diff** (boolean) - Optional - If true, shows the diff between the template and output files. Defaults to false.

### Request Example
```javascript
const envsubh = require('envsub/envsubh');

let templateFile = `${__dirname}/templateFile`;
let outputFile = `${__dirname}/outputFile`;
let options = {
  diff: false
};

envsubh({ templateFile, outputFile, options }).then((envobj) => {
  console.log(envobj.templateFile);
  console.log(envobj.templateContents);
  console.log(envobj.outputFile);
  console.log(envobj.outputContents);
}).catch((err) => {
  console.error(err.message);
});
```

### Response
#### Success Response (200)
- **templateFile** (string) - The path to the input template file.
- **templateContents** (string) - The original content of the template file.
- **outputFile** (string) - The path to the generated output file.
- **outputContents** (string) - The content of the generated output file after substitution.

#### Response Example
```json
{
  "templateFile": "/path/to/templateFile",
  "templateContents": "Hello {{name}}!",
  "outputFile": "/path/to/outputFile",
  "outputContents": "Hello World!"
}
```
```

--------------------------------

### envsubh CLI Usage

Source: https://www.npmjs.com/package/envsub?activeTab=versions

Perform file-level handlebars template rendering using environment variables via the command line.

```APIDOC
## CLI Usage

### Description
Perform file-level handlebars template rendering using environment variables as data. If only the templateFile is provided, the file is overwritten.

### Usage
`envsubh [options] <templateFile> [outputFile]`

### Options
- **-h, --help** - Output usage information
- **-V, --version** - Output the version number
- **-d, --diff** - Show diff between template file and output file
```

--------------------------------

### CLI Usage: envsub

Source: https://www.npmjs.com/package/envsub?activeTab=dependents

Perform environment variable substitution on a template file using the command line interface.

```APIDOC
## CLI Usage

### Description
Substitute environment variables into a template file and save the result to an output file or overwrite the template.

### Usage
`envsub [options] <templateFile> [outputFile]`

### Options
- **-a, --all** - Substitute all system environment variables and all variable placeholders with default values.
- **-d, --diff** - Show diff between template file and output file.
- **-e, --env <name>[=value]** - Environment variable to substitute. Can be repeated.
- **-f, --env-file <envFile>** - Load environment variables from an .env file. Can be repeated.
- **-p, --protect** - Protect non-existent environment variable placeholders from being substituted with an empty string.
- **-s, --syntax <syntax>** - Template substitution syntax (dollar-basic, dollar-curly, dollar-both, handlebars, default).
- **-S, --system** - Prefer system environment variables.
```

--------------------------------

### envsub CLI with .env File

Source: https://www.npmjs.com/package/envsub?activeTab=dependencies

Load environment variables from a .env file using the --env-file flag. This flag also restricts substitutions to variables defined in the file.

```bash
envsub --env-file envFile.env templateFile outputFile
```

--------------------------------

### envsub CLI with --all Flag

Source: https://www.npmjs.com/package/envsub?activeTab=dependencies

Use the --all flag to substitute all environment variables, overriding any restrictions imposed by --env or --env-file flags.

```bash
envsub --env MYVAR=herro --env-file envFile.env --all templateFile outputFile
```

--------------------------------

### Environment Variable Naming Conventions

Source: https://www.npmjs.com/package/envsub

Details the naming conventions enforced by envsub for environment variables.

```APIDOC
## Environment Variable Naming Conventions

### Description
Enforces the Open Group Environment Variable Definition, allowing uppercase letters, digits, and underscores, but not starting with a digit. Also permits lowercase letters.

### Regex for Matching
`[a-zA-Z_]+[a-zA-Z0-9_]*`
```

--------------------------------

### Node.js Promise-based Usage

Source: https://www.npmjs.com/package/envsub?activeTab=readme

Programmatic usage of envsubh using the promise-based API.

```javascript
const envsubh = require('envsub/envsubh');

let templateFile = `${__dirname}/templateFile`;
let outputFile = `${__dirname}/outputFile`;
let options = {
  diff: false // see --diff flag
};

// create (or overwrite) the output file
envsubh({templateFile, outputFile, options}).then((envobj) => {
  // output file created
  console.log(envobj.templateFile);
  console.log(envobj.templateContents);
  console.log(envobj.outputFile);
  console.log(envobj.outputContents);
}).catch((err) => {
  console.error(err.message);
});
```

--------------------------------

### Node.js API: envsub()

Source: https://www.npmjs.com/package/envsub?activeTab=dependents

Programmatic usage of envsub within a Node.js application using promises.

```APIDOC
## Node.js API

### Description
Use the envsub function to perform template substitution programmatically.

### Request Body
- **templateFile** (string) - Required - Path to the template file.
- **outputFile** (string) - Optional - Path to the output file.
- **options** (object) - Optional - Configuration object mirroring CLI flags (all, diff, envs, envFiles, protect, syntax, system).

### Response
- **envobj** (object) - Contains templateFile, templateContents, outputFile, and outputContents.
```

--------------------------------

### envsub CLI with --protect Flag

Source: https://www.npmjs.com/package/envsub?activeTab=dependencies

Prevent non-existent environment variable placeholders from being substituted with an empty string using the --protect flag. Protection is automatic when using --all, --env, or --env-file.

```bash
envsub --protect templateFile outputFile
```

--------------------------------

### envsub CLI with --system Flag

Source: https://www.npmjs.com/package/envsub?activeTab=dependencies

Prioritize system environment variables over CLI-specified values using the --system flag. If a variable is set in the system environment, its value will be used even if overridden by --env.

```bash
envsub --env MYVAR1 --env MYVAR2=station --system templateFile outputFile
```

--------------------------------

### Environment Variable Regex

Source: https://www.npmjs.com/package/envsub?activeTab=readme

The regular expression used for matching environment variable names.

```regex
[a-zA-Z_]+[a-zA-Z0-9_]*
```

--------------------------------

### Overwrite template file via CLI

Source: https://www.npmjs.com/package/envsub?activeTab=dependents

Commands to overwrite a template file with its substituted version, often used in Docker workflows.

```bash
$ envsub templateFile
$ envsub -d -e MYVAR1 -e MYVAR2=foo -f envFile.env -p -s dollar-both -S templateFile
```

--------------------------------

### envsubh Local Promise-based Usage

Source: https://www.npmjs.com/package/envsub?activeTab=dependencies

This section details how to use envsubh programmatically within a Node.js application using promises.

```APIDOC
## envsubh Local Promise-based Usage

### Description
Use envsubh programmatically in your Node.js application. Local promise-based options mirror the global CLI flags.

### Method
N/A (Programmatic Usage)

### Endpoint
N/A (Programmatic Usage)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
- **templateFile** (string) - Required - The path to the template file.
- **outputFile** (string) - Required - The path to the output file.
- **options** (object) - Optional - Configuration options.
  - **diff** (boolean) - Optional - Corresponds to the `--diff` flag. Defaults to `false`.

### Request Example
```javascript
const envsubh = require('envsub/envsubh');

let templateFile = `${__dirname}/templateFile`;
let outputFile = `${__dirname}/outputFile`;
let options = {
  diff: false // see --diff flag
};

// create (or overwrite) the output file
envsubh({templateFile, outputFile, options}).then((envobj) => {
  // output file created
  console.log(envobj.templateFile);
  console.log(envobj.templateContents);
  console.log(envobj.outputFile);
  console.log(envobj.outputContents);
}).catch((err) => {
  console.error(err.message);
});
```

### Response
#### Success Response (Promise resolves with an object)
- **templateFile** (string) - The path to the template file.
- **templateContents** (string) - The content of the template file.
- **outputFile** (string) - The path to the output file.
- **outputContents** (string) - The content of the output file.

#### Response Example
```json
{
  "templateFile": "/path/to/templateFile",
  "templateContents": "Hello {{name}}!",
  "outputFile": "/path/to/outputFile",
  "outputContents": "Hello World!"
}
```

### Error Handling
- The promise will reject if an error occurs during the substitution process.
```

--------------------------------

### envsub Variable Placeholder Default Values

Source: https://www.npmjs.com/package/envsub?activeTab=dependencies

For 'dollar-curly' syntax, define default values for environment variables using ${VARIABLE_NAME:-default}. These defaults are substituted even if the variable is not set.

```text
# Before substitution
Variable with default value: ${VARIABLE_NAME:-default}.
# After substitution
Variable with default value: default.

# Before substitution
Variable with default value + whitespaces: ${VARIABLE_NAME:-        default value }.
# After substitution
Variable with default value + whitespaces:         default value .

```

--------------------------------

### envsubh Programmatic Usage

Source: https://www.npmjs.com/package/envsub?activeTab=dependents

This section explains how to use envsubh programmatically within a Node.js application using its promise-based API.

```APIDOC
## envsubh Programmatic Usage

### Description
Provides a promise-based API for performing environment variable substitution in template files, mirroring the CLI flags.

### Method
JavaScript Function Call

### Endpoint
`require('envsub/envsubh')({ templateFile, outputFile, options })
`

### Parameters
#### Request Body
- **templateFile** (string) - Required - The path to the template file.
- **outputFile** (string) - Required - The path to the output file.
- **options** (object) - Optional - Configuration options.
  - **diff** (boolean) - Optional - If true, logs the difference between the template and output files. Defaults to false.

### Request Example
```javascript
const envsubh = require('envsub/envsubh');

let templateFile = `${__dirname}/templateFile`;
let outputFile = `${__dirname}/outputFile`;
let options = {
  diff: false
};

envsubh({ templateFile, outputFile, options }).then((envobj) => {
  console.log(envobj.templateFile);
  console.log(envobj.templateContents);
  console.log(envobj.outputFile);
  console.log(envobj.outputContents);
}).catch((err) => {
  console.error(err.message);
});
```

### Response
#### Success Response (200)
- **envobj** (object) - An object containing details about the operation.
  - **templateFile** (string) - The path to the template file.
  - **templateContents** (string) - The original content of the template file.
  - **outputFile** (string) - The path to the output file.
  - **outputContents** (string) - The rendered content of the output file.

#### Response Example
```json
{
  "templateFile": "/path/to/templateFile",
  "templateContents": "Hello {{name}}!",
  "outputFile": "/path/to/outputFile",
  "outputContents": "Hello World!"
}
```
```

--------------------------------

### envsub CLI with Specific Variables

Source: https://www.npmjs.com/package/envsub?activeTab=dependencies

Restrict substitutions to specific environment variables using the --env flag. Optionally, provide an overriding value for a variable.

```bash
envsub --env MYVAR1 --env MYVAR2=station templateFile outputFile
```

--------------------------------

### envsubh Node.js API

Source: https://www.npmjs.com/package/envsub?activeTab=versions

Programmatic usage of envsubh using a promise-based interface.

```APIDOC
## Node.js API

### Description
Use the envsubh module programmatically to render templates based on environment variables.

### Request Body
- **templateFile** (string) - Required - Path to the template file
- **outputFile** (string) - Optional - Path to the output file
- **options** (object) - Optional - Configuration options (e.g., { diff: boolean })

### Request Example
```javascript
const envsubh = require('envsub/envsubh');

envsubh({
  templateFile: 'template.hbs',
  outputFile: 'output.txt',
  options: { diff: false }
}).then((envobj) => {
  console.log(envobj.outputContents);
});
```

### Response
#### Success Response (Promise Resolution)
- **templateFile** (string) - Path to the template file
- **templateContents** (string) - Original template content
- **outputFile** (string) - Path to the output file
- **outputContents** (string) - Rendered content
```
Tokens:
Raw