yaml set

1. Introduction
2. Self-Help Documentation

Introduction

The yaml-set command-line tool enables making changes to existing YAML/JSON/Compatible documents (files or data piped in along STDIN). Users can either change the value(s) at the end of a YAML Path, in most cases create a novel data structure within the target file to receive the new value, or even deliberately destroy nodes. A 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.

When not instructed to --delete, this command applies the same Scalar value to one or more nodes in the document. This precludes applying complex data like Hashes and Arrays with this tool. When you need to apply multiple different values in the same operation or to set complex data, use yaml-merge, instead. The yaml-merge command also accepts complex input from STDIN, allowing for very flexible interactions.

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 | -A ANCHOR | -f FILE | -i | -R LENGTH | -N | -D]
                [-F {bare,boolean,default,dquote,float,folded,int,literal,squote}]
                [-c CHECK] [-s YAML_PATH] [-m] [-b]
                [-t ['.', '/', 'auto', 'dot', 'fslash']] [-M CHARS] [-H ANCHOR]
                [-T TAG] [-e] [-x EYAML] [-r PRIVATEKEY] [-u PUBLICKEY] [-S]
                [-d | -v | -q]
                [YAML_FILE]

Changes one or more Scalar values in a YAML/JSON/Compatible document 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; omit or use - to read from
                        STDIN

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
  -H ANCHOR, --anchor ANCHOR
                        when --aliasof|-A points to a value which is not already
                        Anchored, a new Anchor with this name is created;
                        renames an existing Anchor if already set
  -T TAG, --tag TAG     assign a custom YAML (data-type) tag to the changed
                        nodes; can be used without other input options to assign
                        or change a tag
  -S, --nostdin         Do not implicitly read from STDIN, even when there is no
                        YAML_FILE with a non-TTY session
  -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
  -A ANCHOR, --aliasof ANCHOR
                        set the value as a YAML Alias of an existing Anchor, by
                        name (merely copies the target value for non-YAML files)
  -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
  -N, --null            sets the value to null
  -D, --delete          delete rather than change target node(s); implies
                        --mustexist|-m

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/wiki. To report issues with this tool or
to request enhancements, please visit
https://github.com/wwkimball/yamlpath/issues.

For a deeper dive into these options:

• YAML_FILE is the YAML/JSON/EYAML/Compatible file to change. When omitted or set to the - pseudo-file, this program will attempt to read from STDIN.
• --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.
• --delete (-D) destroys all nodes which match --change (-g). Enables --mustexist when set; there is no benefit to destroying already nonexistent nodes.
• --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.
• --nostdin (-S) is useful only when using this command-line tool in a context where data is available on STDIN but you do not wish this command to consume it or you need to block access to STDIN against any unintended attempts to read from 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.