yaml get

1. Introduction
2. Self-Help Documentation

Introduction

The yaml-get command-line tool queries YAML/JSON/compatible data, returning the results to STDOUT. The input data can be read from a single file or STDIN (explicitly by using the - pseudo-file or implicitly by not providing a YAML_FILE positional argument while yaml-get is in a non-TTY session usually created by piping data into it via | or <<<). Results are printed one per line to simplify downstream parsing. Complex results (Hashes and Arrays) are rendered as JSON so they can also be printed one result per line. EYAML files can also be queried, returning decrypted results when the appropriate encryption keys are supplied.

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

Self-Help Documentation

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

usage: yaml-get [-h] [-V] -p YAML_PATH
                [-t ['.', '/', 'auto', 'dot', 'fslash']] [-S] [-x EYAML]
                [-r PRIVATEKEY] [-u PUBLICKEY] [-d | -v | -q]
                [YAML_FILE]

Retrieves one or more values from a YAML/JSON/Compatible file at a specified
YAML Path. Output is printed to STDOUT, one line per result. When a result is
a complex data-type (Array or Hash), a JSON dump is produced to represent it.
EYAML can be employed to decrypt the values.

positional arguments:
  YAML_FILE             the YAML file to query; 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
  -t ['.', '/', 'auto', 'dot', 'fslash'], --pathsep ['.', '/', 'auto', 'dot', 'fslash']
                        indicate which YAML Path seperator to use when
                        rendering results; default=dot
  -S, --nostdin         Do not implicitly read from STDIN, even when YAML_FILE
                        is not set and the session is non-TTY
  -d, --debug           output debugging details
  -v, --verbose         increase output verbosity
  -q, --quiet           suppress all output except errors

required settings:
  -p YAML_PATH, --query YAML_PATH
                        YAML Path to query

EYAML options:
  Left unset, the EYAML keys will default to your system or user defaults.
  Both keys must be set either here or in your system or user EYAML
  configuration file when 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

For more information about YAML Paths, please visit
https://github.com/wwkimball/yamlpath.

For a deeper dive into these options:

• YAML_FILE is the YAML/JSON/EYAML/Compatible file to parse. When omitted or set to the - pseudo-file, this program will attempt to read from STDIN.
• --query (-p) accepts a YAML Path which comprises the query against YAML_FILE or STDIN (when YAML_FILE is not set and data is available on STDIN).
• --pathsep (-t) is (rarely) used to override automatic detection of the separator used in the YAML Paths for --query (-p); this is useful for "weird" YAML Paths where it would not typically be obvious which separator is in use.
• --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.
• --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 querying encrypted data. 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. This value is necessary only when your user or system EYAML configuration does not already supply this key or you need to override it and your version of the eyaml command requires it to decrypt data.
• --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.