skip to navigation
skip to content

shyaml 0.5.0

YAML for command line


Simple scripts that allow read access to YAML files through command line.

This can be handy, if you want to get access to YAML data in your shell scripts.

This scripts supports only read access and it might not support all the subtilties of YAML specification. But it should support some handy basic query of YAML file.


You don’t need to download the GIT version of the code as shyaml is available on the PyPI. So you should be able to run:

pip install shyaml

If you have downloaded the GIT sources, then you could add install the current version via traditional:

python install

And if you don’t have the GIT sources but would like to get the latest master or branch from github, you could also:

pip install git+

Or even select a specific revision (branch/tag/commit):

pip install git+


shyaml takes its YAML input file from standard input ONLY. So there are some sample routine:

Let’s create a sample yaml file:

$ cat <<EOF > test.yaml
name: "MyName !!"
    how-much: 1.1
    how-many: 2
        - first
        - second
        - third
    maintainer: "Valentin Lab"
    description: |
        Multiline description:
        Line 1
        Line 2 1.2\more: 1.3\.more: 1.4

General browsing struct and displaying simple values

Simple query of simple attribute:

$ cat test.yaml | shyaml get-value name
MyName !!

Query nested attributes by using ‘.’ between key labels:

$ cat test.yaml | shyaml get-value

Get type of attributes:

$ cat test.yaml | shyaml get-type name
$ cat test.yaml | shyaml get-type

Parse structure

Get sub YAML from a structure attribute:

$ cat test.yaml | shyaml get-type subvalue
$ cat test.yaml | shyaml get-value subvalue
description: 'Multiline description:

  Line 1

  Line 2

how-many: 2
how-much: 1.1
maintainer: Valentin Lab
- first
- second
- third

Iteration through keys only:

$ cat test.yaml | shyaml keys

Iteration through keys only (0 terminated strings):

$ cat test.yaml | shyaml keys-0 subvalue | xargs -0 -n 1 echo "VALUE:"
VALUE: how-much
VALUE: things
VALUE: how-many
VALUE: maintainer
VALUE: description

Iteration through values only (0 terminated string highly recommended):

$ cat test.yaml | shyaml values-0 subvalue |
  while read -r -d $'\0' value; do
      echo "RECEIVED: '$value'"
RECEIVED: '- first
- second
- third'
RECEIVED: 'Valentin Lab'
RECEIVED: 'Multiline description:
Line 1
Line 2'

Iteration through keys and values (0 terminated string highly recommended):

$ read-0() {
    while [ "$1" ]; do
        IFS=$'\0' read -r -d '' "$1" || return 1

$ cat test.yaml | shyaml key-values-0 subvalue |
  while read-0 key value; do
      echo "KEY: '$key'"
      echo "VALUE: '$value'"
KEY: 'how-much'
VALUE: '1.1'

KEY: 'things'
VALUE: '- first
- second
- third

KEY: 'how-many'
VALUE: '2'

KEY: 'maintainer'
VALUE: 'Valentin Lab'

KEY: 'description'
VALUE: 'Multiline description:
Line 1
Line 2

Notice, that you’ll get the same result using get-values. get-values will support sequences and struct, and key-values support only struct. (for a complete table of which function support what you can look at the usage line)

Parse sequence

Query a sequence with get-value:

$ cat test.yaml | shyaml get-value subvalue.things
- first
- second
- third
$ cat test.yaml | shyaml get-value subvalue.things.0
$ cat test.yaml | shyaml get-value subvalue.things.-1
$ cat test.yaml | shyaml get-value subvalue.things.5
Error: invalid path 'subvalue.things.5', index 5 is out of range (3 elements in sequence).

More usefull, parse a list in one go with get-values:

$ cat test.yaml | shyaml get-values subvalue.things

Note that the action is called get-values, and that output is separated by \n chars, this can bring havoc if you are parsing values containing this character. Hopefully, shyaml has a get-values-0 to terminate strings by \0 char, which allows complete support of any type of values, including YAML. get-values outputs key and values for struct types and only values for sequence types:

$ cat test.yaml | shyaml get-values-0 subvalue |
  while IFS='' read -r -d '' key &&
        IFS='' read -r -d '' value; do
      echo "'$key' -> '$value'"
'how-much' -> '1.1'
'things' -> '- first
- second
- third
'how-many' -> '2'
'maintainer' -> 'Valentin Lab'
'description' -> 'Multiline description:
Line 1
Line 2

Please note that, if get-values{,-0} actually works on struct, it’s maybe more explicit to use the equivalent key-values{,0}. It should be noted that key-values{,0} is not completly equivalent as it is meant to be used with struct only and will complain if not.

You should also notice that values that are displayed are YAML compatible. So if they are complex, you can re-use shyaml on them to parse their content.

Keys containing ‘.’

Use and \\ to access keys with \ and \. to access keys with literal . in them. Just be mindful of shell escaping (example uses single quotes):

$ cat test.yaml | shyaml get-value 'subvalue\.how-much'
$ cat test.yaml | shyaml get-value 'subvalue\.how-much\\more'
$ cat test.yaml | shyaml get-value 'subvalue\.how-much\\.more' default

This last one didn’t escape correctly the last ., this is the correct version:

$ cat test.yaml | shyaml get-value 'subvalue\.how-much\\\.more' default

empty string keys

Yep, shyaml supports empty stringed keys. You might never have use for this one, but it’s in YAML specification. So shyaml supports it:

$ cat <<EOF > test.yaml
       a: foo
       "": bar
"": wiz

$ cat test.yaml | shyaml get-value empty-sub-key..
$ cat test.yaml | shyaml get-value ''

Please notice that one empty string is different than no string at all:

$ cat <<EOF > test.yaml
   a: foo
   b: bar
"x": wiz
$ cat test.yaml | shyaml keys

$ cat test.yaml | shyaml keys ''

The first asks for keys of the root YAML, the second asks for keys of the content of the empty string named element located in the root YAML.

Default Value

There is a third argument on the command line of shyaml which is the DEFAULT argument. If the given KEY was not found in the YAML structure, then shyaml would return what you provided as DEFAULT.

As of version < 0.3, this argument was defaulted to the empty string. For all version above 0.3 (included), if not provided, then an error message will be printed:

$ echo "a: 3" | shyaml get-value a mydefault

$ echo "a: 3" | shyaml get-value b mydefault

$ echo "a: 3" | shyaml get-value b
Error: invalid path 'b', missing key 'b' in struct.

You can emulate pre v0.3 behavior by specifying explicitely an empty string as third argument:

$ echo "a: 3" | shyaml get-value b ''

Ordered mappings

Currently, using shyaml in a shell script involves happily taking YAML inputs and outputting YAML outputs that will further be processed.

And this works very well.

Before version 0.4.0, shyaml would boldly re-order (sorting them alphabetically) the keys in mappings. If this should be considered harmless per specification (mappings are indeed supposed to be unordered, this means order does not matter), in practical, YAML users could feel wronged by shyaml when there YAML got mangled and they wanted to give a meaning to the basic YAML mapping.

Who am I to forbid such usage of YAML mappings ? So starting from version 0.4.0, shyaml will happily keep the order of your mappings:

cat <<EOF > /tmp/test.yml
  a: 1
  c: 2
  b: 3

For shyaml version before 0.4.0:

$ shyaml get-value mapping < test.yml
a: 1
b: 3
c: 2

For shyaml version including and after 0.4.0:

$ shyaml get-value mapping < test.yml
a: 1
c: 2
b: 3

Strict YAML for further processing

Processing yaml can be done recursively and extensively through using the output of shyaml into shyaml. Most of its output is itself YAML. Most ? Well, for ease of use, literal keys (string, numbers) are outputed directly without YAML quotes, which is often convenient.

But this has the consequence of introducing inconsistent behavior. So when processing YAML coming out of shyaml, you should probably think about using the --yaml (or -y) option to output only strict YAML.

With the drawback that when you’ll want to output string, you’ll need to call a last time shyaml get-value to explicitely unquote the YAML.

Usage string

A quick reminder of what is available:

$ shyaml --help
Parses and output chosen subpart or values from YAML input.
It reads YAML in stdin and will output on stdout it's return value.


    %(exname)s [-y|--yaml] ACTION KEY [DEFAULT]


    -y, --yaml
              Output only YAML safe value, more precisely, even
              literal values will be YAML quoted. This behavior
              is required if you want to output YAML subparts and
              further process it. If you know you have are dealing
              with safe literal value, then you don't need this.
              (Default: no safe YAML output)

    ACTION    Depending on the type of data you've targetted
              thanks to the KEY, ACTION can be:

              These ACTIONs applies to any YAML type:

                get-type          ## returns a short string
                get-value         ## returns YAML

              This ACTION applies to 'sequence' and 'struct' YAML type:

                get-values{,-0}   ## return list of YAML

              These ACTION applies to 'struct' YAML type:

                keys{,-0}         ## return list of YAML
                values{,-0}       ## return list of YAML
                key-values,{,-0}  ## return list of YAML

              Note that any value returned is returned on stdout, and
              when returning ``list of YAML``, it'll be separated by
              ``\n`` or ``NUL`` char depending of you've used the
              ``-0`` suffixed ACTION.

    KEY       Identifier to browse and target subvalues into YAML
              structure. Use ``.`` to parse a subvalue. If you need
              to use a literal ``.`` or ``\``, use ``\`` to quote it.

              Use struct keyword to browse ``struct`` YAML data and use
              integers to browse ``sequence`` YAML data.

    DEFAULT   if not provided and given KEY do not match any value in
              the provided YAML, then DEFAULT will be returned. If no
              default is provided and the KEY do not match any value
              in the provided YAML, shyaml will fail with an error


     ## get last grocery
     cat recipe.yaml       | shyaml get-value groceries.-1

     ## get all words of my french dictionary
     cat dictionaries.yaml | shyaml keys-0 french.dictionary

     ## get YAML config part of 'myhost'
     cat hosts_config.yaml | shyaml get-value cfgs.myhost


Any suggestion or issue is welcome. Push request are very welcome, please check out the guidelines.

Push Request Guidelines

You can send any code. I’ll look at it and will integrate it myself in the code base and leave you as the author. This process can take time and it’ll take less time if you follow the following guidelines:

  • check your code with PEP8 or pylint. Try to stick to 80 columns wide.
  • separate your commits per smallest concern.
  • each commit should pass the tests (to allow easy bisect)
  • each functionality/bugfix commit should contain the code, tests, and doc.
  • prior minor commit with typographic or code cosmetic changes are very welcome. These should be tagged in their commit summary with !minor.
  • the commit message should follow gitchangelog rules (check the git log to get examples)
  • if the commit fixes an issue or finished the implementation of a feature, please mention it in the summary.

If you have some questions about guidelines which is not answered here, please check the current git log, you might find previous commit that would show you how to deal with your issue.


Copyright (c) 2015 Valentin Lab.

Licensed under the BSD License.


0.5.0 (2017-03-23)


  • Introduce -y option to force full yaml output. [Valentin Lab]

    By default, output of literal string where directly printed unquoted and useable. If this is very useful, there are many cases where this is not consistent and is ambiguous, especially when this string is itself a YAML representation.

    This could actually lead to subtle bugs occuring when re-using shyaml output for further parsing.

    So if you want unquoted literal types to further process these elements, use -y. If you expect a string and wan’t it plain raw, avoid -y.

0.4.2 (2017-02-08)


  • <<: YAML merging facility support. [Valentin Lab]

0.4.1 (2016-08-29)


  • On python2, unicode strings would be displayed literaly (fixes #26). [Valentin Lab]

    str is not the correct type to match all type of strings in python 2. So unicode strings (usually produced thanks to accentuated characters) would be printed quoted (the python representation).

0.4.0 (2016-01-11)


  • Avoid reordering mapping keys in the output. [Valentin Lab]

    Several commands from shyaml will output YAML themselves. But in the process, the whole content is parsed and re-dumped. This can lead to differences with the original inputs. The ordering of keys can be annoying in some use cases, even if, well mappings should not be ordered, these are ordered by the sequential nature of a file, and using ‘omap’ is often tedious. shyaml now keep the original order the keys were met.

0.3.4 (2015-03-06)


  • Added a nice --help doc. [Valentin Lab]
  • Added key-values{,-0} argument to get key and values in one go. [Valentin Lab]
  • Error is casted if no default specified and the key is not existent. [Valentin Lab]


  • Be more informative in some key related error message. (fixed #7) [Valentin Lab]

0.2.2 (2014-03-19)


  • No argument at all was treated as one empty string argument. Thx Yassa Bb. (fixes #6) [Valentin Lab]

0.2.1 (2013-11-23)


  • Python3 support. [Valentin Lab]


  • Keys can now be empty or contains dots . if they are properly escaped (fixes #5, thanks to Daniel Giribet) [Daniel Giribet]

0.2.0 (2013-05-03)


  • Support for iteration in sequence and struct in one go. [Valentin Lab]


  • Forgot to mention ./ execution when getting the code from git, and be more clear about other means of installation. [Valentin Lab]

0.1.3 (2013-03-29)


  • Removed the spurious line feed at the end of any shyaml output. [Valentin Lab]

  • Support querying for… nothing. Which now returns the whole input YAML. [Valentin Lab]

    Before this fix, you couldn’t ask for shyaml get-value alone, even if it makes sense but is completely useless as it returns the whole YAML input.

0.1.2 (2013-03-23)


  • Support for list indexes (see README.rst). [Valentin Lab]
  • Catch exceptions when parsing structure and output a clean error message. [Valentin Lab]

0.1.1 (2013-02-27)


  • Some minor enhancements, and an “Install” section. [Valentin Lab]

0.1.0 (2013-02-27)

  • First import. [Valentin Lab]
File Type Py Version Uploaded on Size
shyaml-0.5.0-py2.py3-none-any.whl (md5) Python Wheel py2.py3 2017-03-27 19KB
shyaml-0.5.0.tar.gz (md5) Source 2017-03-27 13KB