envsubst

Replace environment variables in stdin and output to stdout

$ echo '[$HOME]' | envsubst

$ envsubst < [path/to/input_file]

$ envsubst < [path/to/input_file] > [path/to/output_file]

$ envsubst '[$USER $SHELL $HOME]' < [path/to/input_file]

envsubst [OPTION]... [SHELL-FORMAT]

-v, --version
    Prints version information about envsubst and exits.

-h, --help
    Displays a help message with usage instructions and exits.

SHELL-FORMAT
    An optional argument specifying a space-separated list of shell variable names (e.g., HOME USER). If provided, envsubst will only substitute variables listed in this format string. If omitted, it will substitute all valid shell variables found in the input that are set in the environment. This offers fine-grained control over which variables are processed.

The envsubst command is a powerful utility from the gettext package designed to substitute environment variables found within text files. It reads from standard input or specified files, identifies patterns matching shell variable expansion syntax (like $VAR or ${VAR}), and replaces them with their corresponding values from the current environment.

It's widely used in scripting, especially in dynamic environments such as Docker containers, CI/CD pipelines, or configuration management, where application settings need to be customized without modifying source files. envsubst handles various forms of variable expansion, including those with default values (e.g., ${VAR:-default}), empty values (${VAR:+value_if_set}), or error messages (${VAR:?error_message}). This makes it an ideal tool for basic templating and configuration generation based on runtime environment variables.

Care should be taken when using envsubst with untrusted input, as patterns resembling shell variables could unintentionally expose sensitive environment variables. It's recommended to either control the input source or explicitly limit the substituted variables using the SHELL-FORMAT argument.

Note that envsubst performs only variable substitution; it does not execute shell commands or perform arithmetic expansions like a full shell interpreter. Its functionality is limited to simple environment variable replacement based on shell-like syntax.

envsubst typically operates by reading from standard input and writing to standard output. This makes it highly versatile for use in pipes.

Example 1: Substituting a single variable
echo '$USER is logged in' | envsubst

Example 2: Substituting multiple variables, limiting scope
echo 'User: $USER
Home: $HOME
Path: $PATH' | envsubst '$USER $HOME'

In the second example, only $USER and $HOME would be substituted, while $PATH would remain untouched, demonstrating how the SHELL-FORMAT argument controls which variables are processed.

envsubst recognizes various forms of shell parameter expansion:
$VAR and ${VAR}: Basic variable substitution.
${VAR:-word}: If VAR is unset or null, the result of the expansion is word. Otherwise, the value of VAR is substituted.
${VAR:=word}: If VAR is unset or null, word is assigned to VAR, and its value is substituted.
${VAR:?message}: If VAR is unset or null, message is printed to standard error, and the command exits.
${VAR:+word}: If VAR is unset or null, nothing is substituted. Otherwise, word is substituted.

envsubst is part of the GNU gettext utilities, a project primarily focused on internationalization and localization of software. While its original purpose was related to processing message catalogs, its simple and effective variable substitution capability made it a standalone utility widely adopted for dynamic configuration generation, particularly in modern DevOps practices. Its development is integrated with the broader gettext project, which has been under continuous development for decades.

bash(1), sh(1), gettext(1), printf(1), sed(1), awk(1)