yaml set

1. Introduction
2. Self-Help Documentation

Introduction

The yaml-set command-line tool enables making changes to existing YAML/JSON/Compatible data files. Users can either change the value(s) at the end of a YAML Path, or -- in most cases -- create a novel data structure within the target file to receive the new value. The new value can be supplied on the command-line, from STDIN, from a different file (which contains only the new value), or from a secure random value generator (of a specific length and for which the characters to select from can be specified). The value can be encrypted as long as an appropriate EYAML public key is available or supplied.

This page explores the various command-line arguments understood by yaml-set. For real-world examples of using it, please check yaml-set Examples.

Self-Help Documentation

When the --help (-h) flag is passed into yaml-set, it produces this output:

usage: yaml-set [-h] [-V] -g YAML_PATH [-a VALUE | -f FILE | -i | -R LENGTH]
                [-F {bare,boolean,default,dquote,float,folded,int,literal,squote}]
                [-c CHECK] [-s YAML_PATH] [-m] [-b]
                [-t ['.', '/', 'auto', 'dot', 'fslash']] [-M CHARS] [-e]
                [-x EYAML] [-r PRIVATEKEY] [-u PUBLICKEY] [-d | -v | -q]
                YAML_FILE

Changes one or more Scalar values in a YAML/JSON/Compatible file at a
specified YAML Path. Matched values can be checked before they are replaced to
mitigate accidental change. When matching singular results, the value can be
archived to another key before it is replaced. Further, EYAML can be employed
to encrypt the new values and/or decrypt an old value before checking it.

positional arguments:
  YAML_FILE             the YAML file to update

optional arguments:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  -F {bare,boolean,default,dquote,float,folded,int,literal,squote}, --format {bare,boolean,default,dquote,float,folded,int,literal,squote}
                        override automatic formatting of the new value
  -c CHECK, --check CHECK
                        check the value before replacing it
  -s YAML_PATH, --saveto YAML_PATH
                        save the old value to YAML_PATH before replacing it;
                        implies --mustexist
  -m, --mustexist       require that the --change YAML_PATH already exist in
                        YAML_FILE
  -b, --backup          save a backup YAML_FILE with an extra .bak file-
                        extension
  -t ['.', '/', 'auto', 'dot', 'fslash'], --pathsep ['.', '/', 'auto', 'dot', 'fslash']
                        indicate which YAML Path seperator to use when
                        rendering results; default=dot
  -M CHARS, --random-from CHARS
                        characters from which to build a value for --random;
                        default=all upper- and lower-case letters and all
                        digits
  -d, --debug           output debugging details
  -v, --verbose         increase output verbosity
  -q, --quiet           suppress all output except errors

required settings:
  -g YAML_PATH, --change YAML_PATH
                        YAML Path where the target value is found

input options:
  -a VALUE, --value VALUE
                        set the new value from the command-line instead of
                        STDIN
  -f FILE, --file FILE  read the new value from file (discarding any trailing
                        new-lines)
  -i, --stdin           accept the new value from STDIN (best for sensitive
                        data)
  -R LENGTH, --random LENGTH
                        randomly generate a replacement value of a set length

EYAML options:
  Left unset, the EYAML keys will default to your system or user defaults.
  You do not need to supply a private key unless you enable --check and the
  old value is encrypted.

  -e, --eyamlcrypt      encrypt the new value using EYAML
  -x EYAML, --eyaml EYAML
                        the eyaml binary to use when it isn't on the PATH
  -r PRIVATEKEY, --privatekey PRIVATEKEY
                        EYAML private key
  -u PUBLICKEY, --publickey PUBLICKEY
                        EYAML public key

When no changes are made, no backup is created, even when -b/--backup is
specified. For more information about YAML Paths, please visit
https://github.com/wwkimball/yamlpath.

For a deeper dive into these options:

• --format (-F) manually specifies the precise data-type of the new value. This can be used either to customize the presentation of values within the resulting document (like specifying multi-line text values be presented in block format, preserving or discarding new-lines), change the handling of otherwise determinate types (like deliberately wrapping numeric values in quotes), or to workaround data handling issues (some values may seem like one type of data when they really aren't, like Boolean True/False/On/Off/Yes/No can sometimes be misinterpreted as an Integer).
• --check (-c) ensures the value being changed is expected, lest the change be cancelled. This is particularly useful for automated value rotation systems which you must ensure does not run more times than required; it restricts changes only when the old value is still set.
• --saveto (-s) copies the original value being changed to the designated YAML Path before changing it. This is allowed only when the value being changed is singular and is most useful for value rotation solutions, such as periodic changes to credentials or other secrets.
• --mustexist (-m) requires that the YAML Path specified for --change (-g) points to at least one pre-existing node within the data; dynamic structure will not be built in order to give the new value a new node. As one means of ensuring your command is running against the expected file, this is particularly helpful for ensuring that the node being changed is already present before attempting to change it.
• --backup (-b) copies the original YAML_FILE to a file with an additional .bak file-name extension before the updated data is written.
• --pathsep (-t) is (rarely) used to override automatic detection of the separator used in the YAML Paths for --change (-g) and --saveto (-s); this is useful for "weird" YAML Paths where it would not typically be obvious which separator is in use.
• --random-from (-M) is used only when --random (-R) is also set; it specifies the full spectrum of characters from which to securely generate a random value for --change (-g). Be careful to provide adequate characters lest the resulting value be insufficiently random. The default value is comprised of all capital- and lower-case letters along with all digits per the locale of the running session with no other non-alpha-numeric characters.
• --change (-g) is a YAML Path which indicates which nodes within the YAML_FILE are to receive the replacement value.
• --value (-a) facilitates specifying the replacement value from the command-line. USE WITH CAUTION! Values set using this option are visible to any other user or process which can review the running process list on your machine, whom can review the command history on that machine, or whom are running a key-logger on the machine.
• --file (-f) is an alternative to --value (-a), enabling the replacement value to be stored in advance within an external file. The full contents of the file are used as the replacement value. This is also particularly useful when you need to store particularly large content in the target YAML/JSON/Compatible file, like base64-encoded binary data or multi-line text.
• --stdin (-i) is an alternative to --value (-a), enabling the replacement value to be supplied via STDIN. This option is useful when the replacement value is generated by or otherwise passed through another process. Done carefully, this enables protecting the new value from process and key-log snooping.
• --random (-R) is an alternative to --value (-a) and perhaps the most secure. However, it is useful only when you do not need to predetermine or otherwise know the replacement value. When combined with --eyamlcrypt (-e) and a very large --random-from (-M), this is the most secure means of setting a new secret value among the alternatives.
• --eyamlcrypt (-e) employs EYAML to encrypt the replacement value, provided the necessary public key is available to the eyaml command or is supplied via --publickey (-u). Depending on the version of EYAML installed, you may also be required to supply --privatekey (-r); this is a known bug in certain versions of the external eyaml command.
• --eyaml (-x) specifies the fully-qualified path to the external eyaml command. This is useful whenever you need to employ a custom version of eyaml or the command is not on the system PATH.
• --privatekey (-r) specifies the EYAML private key to use with the external eyaml command when using --check (-c) to enforce that an old encrypted value is expected before replacing it. For certain versions of the external eyaml command, it may also be required when encrypting new values with --eyamlcrypt (-e). This value is necessary only when your user or system EYAML configuration does not already supply this key or you need to override it.
• --publickey (-u) specifies the EYAML public key to use with the external eyaml command when using --eyamlcrypt (-e). This value is necessary only when your user or system EYAML configuration does not already supply this key or you need to override it.
• --debug (-d) generates a vast amount of detailed information as the document is parsed and the value changed. It is particularly helpful when tracing YAML Path behavior or troubleshooting other options.
• --verbose (-v) generates slightly more status messages as the value is changed.
• --quiet (-q) suppresses normal status and processing messages.