yq
v4.x
v4.x
  • yq
  • How It Works
  • Recipes
  • Upgrading from V3
  • Commands
    • Evaluate
    • Evaluate All
    • Shell Completion
  • Operators
    • Add
    • Alternative (Default value)
    • Anchor and Alias Operators
    • Array to Map
    • Assign (Update)
    • Boolean Operators
    • Collect into Array
    • Column
    • Comment Operators
    • Compare Operators
    • Contains
    • Create, Collect into Object
    • Date Time
    • Delete
    • Divide
    • Document Index
    • Encode / Decode
    • Entries
    • Env Variable Operators
    • Equals
    • Eval
    • File Operators
    • Filter Operator
    • Flatten
    • Group By
    • Has
    • Keys
    • Kind
    • Length
    • Line
    • Load
    • Min
    • Map
    • Max
    • Modulo
    • Multiply (Merge)
    • Omit
    • Parent
    • Path
    • Pick
    • Pipe
    • Pivot
    • Recursive Descent (Glob)
    • Reduce
    • Reverse
    • Select
    • Shuffle
    • Slice Array
    • Sort
    • Sort Keys
    • Split into Documents
    • String Operators
    • Style
    • Subtract
    • Tag
    • To Number
    • Traverse (Read)
    • Union
    • Unique
    • Variable Operators
    • With
  • Usage
    • Output format
    • Working with CSV, TSV
    • Working with JSON
    • Working with Properties
    • Working with XML
    • Working with LUA
    • Working with TOML
    • Working with Shell Output
    • Front Matter
    • Split into multiple files
    • GitHub Action
    • Tips, Tricks, Troubleshooting
  • Github Page
Powered by GitBook
On this page
  • EnvSubst Options
  • Tip
  • Read string environment variable
  • Read boolean environment variable
  • Read numeric environment variable
  • Read yaml environment variable
  • Read boolean environment variable as a string
  • Read numeric environment variable as a string
  • Dynamically update a path from an environment variable
  • Dynamic key lookup with environment variable
  • Replace strings with envsubst
  • Replace strings with envsubst, missing variables
  • Replace strings with envsubst(nu), missing variables
  • Replace strings with envsubst(ne), missing variables
  • Replace strings with envsubst(ne), empty variable
  • Replace strings with envsubst, missing variables with defaults
  • Replace strings with envsubst(nu), missing variables with defaults
  • Replace strings with envsubst(ne), missing variables with defaults
  • Replace string environment variable in document
  • (Default) Return all envsubst errors
  • Fail fast, return the first envsubst error (and abort)

Was this helpful?

  1. Operators

Env Variable Operators

PreviousEntriesNextEquals

Last updated 2 years ago

Was this helpful?

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 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 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:

yq '(.. | select(tag == "!!str")) |= envsubst' file.yaml

Read string environment variable

Running

myenv="cat meow" yq --null-input '.a = env(myenv)'

will output

a: cat meow

Read boolean environment variable

Running

myenv="true" yq --null-input '.a = env(myenv)'

will output

a: true

Read numeric environment variable

Running

myenv="12" yq --null-input '.a = env(myenv)'

will output

a: 12

Read yaml environment variable

Running

myenv="{b: fish}" yq --null-input '.a = env(myenv)'

will output

a: {b: fish}

Read boolean environment variable as a string

Running

myenv="true" yq --null-input '.a = strenv(myenv)'

will output

a: "true"

Read numeric environment variable as a string

Running

myenv="12" yq --null-input '.a = strenv(myenv)'

will output

a: "12"

Dynamically update a path from an environment variable

The env variable can be any valid yq expression.

Given a sample.yml file of:

a:
  b:
    - name: dog
    - name: cat

then

pathEnv=".a.b[0].name"  valueEnv="moo" yq 'eval(strenv(pathEnv)) = strenv(valueEnv)' sample.yml

will output

a:
  b:
    - name: moo
    - name: cat

Dynamic key lookup with environment variable

Given a sample.yml file of:

cat: meow
dog: woof

then

myenv="cat" yq '.[env(myenv)]' sample.yml

will output

meow

Replace strings with envsubst

Running

myenv="cat" yq --null-input '"the ${myenv} meows" | envsubst'

will output

the cat meows

Replace strings with envsubst, missing variables

Running

yq --null-input '"the ${myenvnonexisting} meows" | envsubst'

will output

the  meows

Replace strings with envsubst(nu), missing variables

(nu) not unset, will fail if there are unset (missing) variables

Running

yq --null-input '"the ${myenvnonexisting} meows" | envsubst(nu)'

will output

Error: variable ${myenvnonexisting} not set

Replace strings with envsubst(ne), missing variables

(ne) not empty, only validates set variables

Running

yq --null-input '"the ${myenvnonexisting} meows" | envsubst(ne)'

will output

the  meows

Replace strings with envsubst(ne), empty variable

(ne) not empty, will fail if a references variable is empty

Running

myenv="" yq --null-input '"the ${myenv} meows" | envsubst(ne)'

will output

Error: variable ${myenv} set but empty

Replace strings with envsubst, missing variables with defaults

Running

yq --null-input '"the ${myenvnonexisting-dog} meows" | envsubst'

will output

the dog meows

Replace strings with envsubst(nu), missing variables with defaults

Having a default specified skips over the missing variable.

Running

yq --null-input '"the ${myenvnonexisting-dog} meows" | envsubst(nu)'

will output

the dog meows

Replace strings with envsubst(ne), missing variables with defaults

Fails, because the variable is explicitly set to blank.

Running

myEmptyEnv="" yq --null-input '"the ${myEmptyEnv-dog} meows" | envsubst(ne)'

will output

Error: variable ${myEmptyEnv} set but empty

Replace string environment variable in document

Given a sample.yml file of:

v: ${myenv}

then

myenv="cat meow" yq '.v |= envsubst' sample.yml

will output

v: cat meow

(Default) Return all envsubst errors

By default, all errors are returned at once.

Running

yq --null-input '"the ${notThere} ${alsoNotThere}" | envsubst(nu)'

will output

Error: variable ${notThere} not set
variable ${alsoNotThere} not set

Fail fast, return the first envsubst error (and abort)

Running

yq --null-input '"the ${notThere} ${alsoNotThere}" | envsubst(nu,ff)'

will output

Error: variable ${notThere} not set
envsubst
Imposing Restrictions