Skip to content

Environment Tools

Tools to manipulate environment files in Bash:

  • Standardizing
  • Application defaults

  • Reading and writing to/from files

⬅ Parent

Environment

environmentVariables

Output a list of environment variables and ignore function definitions

Usage

environmentVariables

Output a list of environment variables and ignore function definitions

both set and env output functions and this is an easy way to just output exported variables

Arguments

  • none

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Requires

declare grep cut usageDocument __help

environmentVariableNameValid

Validates zero or more environment variable names.

Usage

environmentVariableNameValid variableName ... [ --help ]

Validates zero or more environment variable names.

  • alpha
  • digit
  • underscore

First letter MUST NOT be a digit

Arguments

  • variableName ... - String. Required. Exit status 0 if all variables names are valid ones.
  • --help - Optional. Flag. Display this help.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

environmentOutput

Output all exported environment variables, hiding secure ones and ones

Usage

environmentOutput [ --underscore ] [ --skip-prefix ] [ --secure ]

Output all exported environment variables, hiding secure ones and ones prefixed with underscore. Any values which contain a newline are also skipped.

Arguments

  • --underscore - Flag. Optional. Include environment variables which begin with underscore _.
  • --skip-prefix - String. Optional. Skip environment variables which begin with this exact prefix (case-sensitive).
  • --secure - Flag. Optional. Include environment variables which are in environmentSecureVariables

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Requires

throwArgument decorate environmentSecureVariables grepSafe env removeFields

environmentCompile

Load an environment file and evaluate it using bash and

Usage

environmentCompile [ --underscore ] [ --secure ] environmentFile

Load an environment file and evaluate it using bash and output the changed environment variables after running Do not perform this operation on files which are untrusted.

Arguments

  • --underscore - Flag. Include environment variables which begin with underscore _.
  • --secure - Flag. Include environment variables which are in environmentSecureVariables
  • environmentFile - File. Required. Environment file to load, evaluate, and output in raw form (Bash-compatible).

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

environmentClean

Clean most exported variables from the current context except a

Usage

environmentClean [ keepEnvironment ]

Clean most exported variables from the current context except a few important ones: - BUILD_HOME PATH LD_LIBRARY USER HOME PS1 PS2 Calls unset on any variable in the global environment and exported. Use with caution. Any additional environment variables you wish to preserve, simply pass those on the command line

Arguments

  • keepEnvironment - EnvironmentVariable. Optional. Keep this environment variable. ZeroOrMore.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

environmentAddFile

Adds an environment variable file to a project

Usage

environmentAddFile [ --help ] environmentName ...

Adds an environment variable file to a project

Arguments

  • --help - Optional. Flag. Display this help.
  • environmentName ... - EnvironmentName. Required. One or more environment variable names to add to this project.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Variable lists

environmentSecureVariables

List environment variables related to security

Usage

environmentSecureVariables

List environment variables related to security

Arguments

  • none

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

environmentApplicationVariables

List environment variables related to application deployments

Usage

environmentApplicationVariables

List environment variables related to application deployments

Arguments

  • none

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Converting

environmentFileIsDocker

Ensure an environment file is compatible with non-quoted docker environment

Usage

environmentFileIsDocker [ filename ]

Ensure an environment file is compatible with non-quoted docker environment files Return Code: 1 - if errors occur Return Code: 0 - if file is valid

Arguments

  • filename - Docker environment file to check for common issues

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

environmentFileToBashCompatible

Takes any environment file and makes it bash-compatible

Usage

environmentFileToBashCompatible [ filename ]

Takes any environment file and makes it bash-compatible

Outputs the compatible env to stdout

Reads standard input

environment file

Writes to standard output

bash-compatible environment statements

Arguments

  • filename - Optional. File. One or more files to convert.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

environmentFileToDocker

Takes any environment file and makes it docker-compatible

Usage

environmentFileToDocker envFile

Takes any environment file and makes it docker-compatible

Outputs the compatible env to stdout

Arguments

  • envFile - Required. File. One or more files to convert.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

environmentFileBashCompatibleToDocker

Ensure an environment file is compatible with non-quoted docker environment

Usage

environmentFileBashCompatibleToDocker [ filename ]

Ensure an environment file is compatible with non-quoted docker environment files Return Code: 1 - if errors occur Return Code: 0 - if file is valid

Reads standard input

text - Optional. Environment file to convert.

Writes to standard output

text - Only if stdin is supplied and no filename arguments.

Arguments

  • filename - File. Optional. Docker environment file to check for common issues

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

environmentFileDockerToBashCompatible

Ensure an environment file is compatible with non-quoted docker environment

Usage

environmentFileDockerToBashCompatible [ filename ]

Ensure an environment file is compatible with non-quoted docker environment files May take a list of files to convert or stdin piped in

Outputs bash-compatible entries to stdout Any output to stdout is considered valid output Any output to stderr is errors in the file but is written to be compatible with a bash

Return Code: 1 - if errors occur Return Code: 0 - if file is valid

Arguments

  • filename - Docker environment file to check for common issues

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

State files

environmentLoad

Safely load an environment from stdin (no code execution)

Usage

environmentLoad [ --verbose ] [ --debug ] [ --prefix ] [ --context ] [ --ignore environmentName ] [ --secure environmentName ] [ --secure-defaults ] [ --execute arguments ... ]

Safely load an environment from stdin (no code execution) Return Code: 2 - if file does not exist; outputs an error Return Code: 0 - if files are loaded successfully

Arguments

  • --verbose - Flag. Optional. Output errors with variables.
  • --debug - Flag. Optional. Debugging mode, for developers probably.
  • --prefix - String. Optional. Prefix each environment variable defined with this string. e.g. NAME -> DSN_NAME for --prefix DSN_
  • --context - String. Optional. Name of the context for debugging or error messages. (e.g. what is this doing for whom and why)
  • --ignore environmentName - Optional. String. Environment value to ignore on load.
  • --secure environmentName - Optional. String. If found, entire load fails.
  • --secure-defaults - Flag. Optional. Add a list of environment variables considered security risks to the --ignore list.
  • --execute arguments ... - Callable. Optional. All additional arguments are passed to callable after loading environment.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

environmentFileLoad

Safely load an environment file (no code execution)

Usage

environmentFileLoad [ --required | --optional ] [ --ignore name ] environmentFile ...

Safely load an environment file (no code execution) Return Code: 2 - if file does not exist; outputs an error Return Code: 0 - if files are loaded successfully

Arguments

  • --prefix - EnvironmentVariable|Blank. Optional. All subsequent environment variables are prefixed with this prefix.
  • --require - Flag. Optional. All subsequent environment files on the command line will be required.
  • --optional - Flag. Optional. All subsequent environment files on the command line will be optional. (If they do not exist, no errors.)
  • --verbose - Flag. Optional. Output errors with variables in files.
  • environmentFile - Required. Environment file to load. For --optional files the directory must exist.
  • --ignore environmentName - Optional. String. Environment value to ignore on load.
  • --secure environmentName - Optional. String. If found in a loaded file, entire file fails.
  • --secure-defaults - Flag. Optional. Add a list of environment variables considered security risks to the --ignore list.
  • --execute arguments ... - Callable. Optional. All additional arguments are passed to callable after loading environment files.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

environmentValueWrite

Write a value to a state file as NAME="value"

Usage

name - Required. String. Name to write.
value - Optional. EmptyString. Value to write.
... - Optional. EmptyString. Additional values, when supplied, write this value as an array.

Write a value to a state file as NAME="value"

Arguments

  • none

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

environmentValueWriteArray

Write an array value as NAME=([0]="a" [1]="b" [2]="c")

Usage

environmentValueWriteArray [ --help ] [ value ... ] [ --help ]

Write an array value as NAME=([0]="a" [1]="b" [2]="c") Supports empty arrays Bash outputs on different versions:

declare -a foo='([0]="a'\''s" [1]="b" [2]="c")'
declare -a foo=([0]="a's" [1]="b" [2]="c")

Arguments

  • --help - Optional. Flag. Display this help.
  • value ... - Arguments. Optional. Array values as arguments.
  • --help - Optional. Flag. Display this help.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

environmentValueRead

Return Code: 1 - If value is not found and

Usage

environmentValueRead stateFile name [ default ] [ --help ]

Return Code: 1 - If value is not found and no default argument is supplied (2 arguments) Return Code: 0 - If value

Arguments

  • stateFile - EnvironmentFile. Required. File to read a value from.
  • name - EnvironmentVariable. Required. Variable to read.
  • default - EmptyString. Optional. Default value of the environment variable if it does not exist.
  • --help - Optional. Flag. Display this help.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

environmentValueReadArray

Read an array value from a state file

Usage

environmentValueReadArray stateFile name [ --help ]

Read an array value from a state file Outputs array elements, one per line.

Arguments

  • stateFile - Required. File. File to access, must exist.
  • name - Required. EnvironmentVariable. Name to read.
  • --help - Optional. Flag. Display this help.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

environmentValueConvertArray

Convert an array value which was loaded already

Usage

environmentValueConvertArray encodedValue [ --help ]

Convert an array value which was loaded already

Writes to standard output

Array values separated by newlines

Arguments

  • encodedValue - String. Required. Value to convert to tokens, one per line
  • --help - Optional. Flag. Display this help.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

environmentLines

List lines of environment values set in a bash state

Usage

environmentLines [ --help ]

List lines of environment values set in a bash state file

Arguments

  • --help - Optional. Flag. Display this help.

Examples

environmentLines < "$stateFile"

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

environmentNames

List names of environment values set in a bash state

Usage

environmentNames [ --help ]

List names of environment values set in a bash state file

Arguments

  • --help - Optional. Flag. Display this help.

Examples

environmentNames < "$stateFile"

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Application .env

environmentFileApplicationMake

Create environment file .env for build.

Usage

environmentFileApplicationMake [ requiredEnvironment ... ] [ -- optionalEnvironment ...] "

Create environment file .env for build.

Note that this does NOT change or modify the current environment.

Arguments

  • --help - Optional. Flag. Display this help.
  • requiredVariable ... - Optional. One or more environment variables which should be non-blank and included in the .env file.
  • -- - Optional. Divider. Divides the requiredEnvironment values from the optionalEnvironment. Should appear once and only once.
  • optionalVariable ... - Optional. One or more environment variables which are included if blank or not

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Environment

  • APPLICATION_VERSION - String. This is the version number which can be displayed
  • reserved and set to hookRun version-current if not set already
  • APPLICATION_BUILD_DATE - Date. Time when a build was initiated, set upon first invocation if not already
  • reserved and set to current date; format like SQL.
  • APPLICATION_TAG - String. This is the full version number including debugging or release identifiers
  • reserved and set to hookRun application-id
  • APPLICATION_ID - String. This is the unique hash which represents the source code state (typically a git hash)
  • reserved and set to hookRun application-tag

environmentFileApplicationVerify

Check application environment is populated correctly.

Usage

environmentFileApplicationVerify [ --help ] [ requiredEnvironment ... ] [ -- ] [ optionalEnvironment ... ]

Check application environment is populated correctly. Also verifies that environmentApplicationVariables and environmentApplicationLoad are defined.

Arguments

  • --help - Optional. Flag. Display this help.
  • requiredEnvironment ... - Optional. EnvironmentName. One or more environment variables which should be non-blank and included in the .env file.
  • -- - Optional. Divider. Divides the requiredEnvironment values from the optionalEnvironment
  • optionalEnvironment ... - EnvironmentName. Optional. One or more environment variables which are included if blank or not

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error