Env Variable Operators

Search…

These operators are used to handle environment variables usage in expressions and documents. While environment variables can, of course, be passed in via your CLI with string interpolation, this often comes with complex quote escaping and can be tricky to write and read.
There are three operators:
env which takes a single environment variable name and parse the variable as a yaml node (be it a map, array, string, number of boolean)
strenv which also takes a single environment variable name, and always parses the variable as a string.
envsubst which you pipe strings into and it interpolates environment variables in strings using envsubst.
EnvSubst Options
You can optionally pass envsubst any of the following options:
nu: NoUnset, this will fail if there are any referenced variables that are not set
ne: NoEmpty, this will fail if there are any referenced variables that are empty
ff: FailFast, this will abort on the first failure (rather than collect all the errors)
E.g: envsubst(ne, ff) will fail on the first empty variable.
See Imposing Restrictions in the envsubst documentation for more information, and below for examples.
Tip
To replace environment variables across all values in a document, envsubst can be used with the recursive descent operator as follows:
1
yq '(.. | select(tag == "!!str")) |= envsubst' file.yaml
Copied!
Note that versions prior to 4.18 require the 'eval/e' command to be specified.
yq e <exp> <file>
Read string environment variable
Running
1
myenv="cat meow" yq --null-input '.a = env(myenv)'
Copied!
will output
1
a: cat meow
Copied!
Read boolean environment variable
Running
1
myenv="true" yq --null-input '.a = env(myenv)'
Copied!
will output
1
a: true
Copied!
Read numeric environment variable
Running
1
myenv="12" yq --null-input '.a = env(myenv)'
Copied!
will output
1
a: 12
Copied!
Read yaml environment variable
Running
1
myenv="{b: fish}" yq --null-input '.a = env(myenv)'
Copied!
will output
1
a: {b: fish}
Copied!
Read boolean environment variable as a string
Running
1
myenv="true" yq --null-input '.a = strenv(myenv)'
Copied!
will output
1
a: "true"
Copied!
Read numeric environment variable as a string
Running
1
myenv="12" yq --null-input '.a = strenv(myenv)'
Copied!
will output
1
a: "12"
Copied!
Dynamically update a path from an environment variable
The env variable can be any valid yq expression.
Given a sample.yml file of:
1
a:
2
  b:
3
    - name: dog
4
    - name: cat
Copied!
then
1
pathEnv=".a.b[0].name"  valueEnv="moo" yq 'eval(strenv(pathEnv)) = strenv(valueEnv)' sample.yml
Copied!
will output
1
a:
2
  b:
3
    - name: moo
4
    - name: cat
Copied!
Dynamic key lookup with environment variable
Given a sample.yml file of:
1
cat: meow
2
dog: woof
Copied!
then
1
myenv="cat" yq '.[env(myenv)]' sample.yml
Copied!
will output
1
meow
Copied!
Replace strings with envsubst
Running
1
myenv="cat" yq --null-input '"the ${myenv} meows" | envsubst'
Copied!
will output
1
the cat meows
Copied!
Replace strings with envsubst, missing variables
Running
1
yq --null-input '"the ${myenvnonexisting} meows" | envsubst'
Copied!
will output
1
the  meows
Copied!
Replace strings with envsubst(nu), missing variables
(nu) not unset, will fail if there are unset (missing) variables
Running
1
yq --null-input '"the ${myenvnonexisting} meows" | envsubst(nu)'
Copied!
will output
1
Error: variable ${myenvnonexisting} not set
Copied!
Replace strings with envsubst(ne), missing variables
(ne) not empty, only validates set variables
Running
1
yq --null-input '"the ${myenvnonexisting} meows" | envsubst(ne)'
Copied!
will output
1
the  meows
Copied!
Replace strings with envsubst(ne), empty variable
(ne) not empty, will fail if a references variable is empty
Running
1
myenv="" yq --null-input '"the ${myenv} meows" | envsubst(ne)'
Copied!
will output
1
Error: variable ${myenv} set but empty
Copied!
Replace strings with envsubst, missing variables with defaults
Running
1
yq --null-input '"the ${myenvnonexisting-dog} meows" | envsubst'
Copied!
will output
1
the dog meows
Copied!
Replace strings with envsubst(nu), missing variables with defaults
Having a default specified skips over the missing variable.
Running
1
yq --null-input '"the ${myenvnonexisting-dog} meows" | envsubst(nu)'
Copied!
will output
1
the dog meows
Copied!
Replace strings with envsubst(ne), missing variables with defaults
Fails, because the variable is explicitly set to blank.
Running
1
myEmptyEnv="" yq --null-input '"the ${myEmptyEnv-dog} meows" | envsubst(ne)'
Copied!
will output
1
Error: variable ${myEmptyEnv} set but empty
Copied!
Replace string environment variable in document
Given a sample.yml file of:
1
v: ${myenv}
Copied!
then
1
myenv="cat meow" yq '.v |= envsubst' sample.yml
Copied!
will output
1
v: cat meow
Copied!
(Default) Return all envsubst errors
By default, all errors are returned at once.
Running
1
yq --null-input '"the ${notThere} ${alsoNotThere}" | envsubst(nu)'
Copied!
will output
1
Error: variable ${notThere} not set
2
variable ${alsoNotThere} not set
Copied!
Fail fast, return the first envsubst error (and abort)
Running
1
yq --null-input '"the ${notThere} ${alsoNotThere}" | envsubst(nu,ff)'
Copied!
will output
1
Error: variable ${notThere} not set
Copied!