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 (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.

(more to come)