shyaml: YAML for the Command Line (Python version)

0.6.2 · maintenance · verified Sat Apr 11

The original `shyaml` Python library (v0.6.2) is a command-line tool designed for reading and querying YAML files. It enables shell scripts to easily access YAML data using simple dot-notation paths. While it remains available on PyPI, this Python version is in a low-maintenance state with no new features planned. Active development has transitioned to `shyaml-rs`, a Rust rewrite that offers significant performance improvements and additional features like write capabilities, while maintaining command-line interface compatibility.

Warnings

gotcha The Python `shyaml` library is in maintenance mode. `shyaml-rs`, a Rust rewrite, is the actively developed and recommended replacement. `shyaml-rs` is designed as a drop-in CLI replacement, offering 14-42x faster performance and new write capabilities (e.g., `set-value`, `del`, `apply`) not present in the Python version.
Fix: Consider migrating to `shyaml-rs` for performance and new features. If you rely solely on CLI parsing, `shyaml-rs` should work seamlessly: `cargo install shyaml-rs` (if Rust is installed) or download a pre-built binary.
breaking Handling of missing paths changed significantly in version 0.3. Prior to 0.3, if a specified key was not found, `shyaml` would return an empty string by default. From version 0.3 onwards (inclusive), if a key is not found and no default value is explicitly provided as the third argument, `shyaml` will print an error message and exit.
Fix: Always provide a default value as the third argument to `shyaml get-value` if the key might be missing and you don't want an error: `cat file.yaml | shyaml get-value some.path 'my_default_value'`
breaking Ordered mappings behavior changed in version 0.4.0. Before 0.4.0, `shyaml` would alphabetically re-order keys in mappings. While YAML specification considers mappings unordered, this behavior could be unexpected for users. From version 0.4.0 onwards, `shyaml` preserves the order of keys in mappings.
Fix: Ensure your scripts do not rely on a specific (or alphabetically sorted) order of keys if using older versions, or upgrade to 0.4.0+ if order preservation is critical. The current version (0.6.2) preserves order.
gotcha By default, `shyaml` outputs simple string or number values directly without YAML quotes for convenience. This means the output is not strictly valid YAML in all cases. If you need strict YAML output (e.g., for piping to another YAML processor), you must use the `--yaml` or `-y` option.
Fix: Use `shyaml --yaml get-value ...` or `shyaml -y get-value ...` to ensure strict YAML output for all values.

Install

pip install shyaml Install with pip

Imports

shyaml.do
```
import shyaml
# ... then call shyaml.do(stdin_stream, args)
```
The Python `shyaml` library is primarily intended as a command-line tool. While a Python API exists via `shyaml.do()`, its typical usage involves piping YAML data from standard input to the `shyaml` executable rather than direct Python imports for general-purpose YAML manipulation.

Quickstart

The primary use of `shyaml` is via the command line to extract values from YAML. It reads YAML from standard input and outputs the requested value to standard output. Paths are specified using dot notation.

cat <<EOF > config.yaml
database:
  host: localhost
  port: 5432
  credentials:
    username: admin
    password: ${DB_PASSWORD:-fallback_pass}
EOF

DB_PASSWORD="secure_pass" \
  cat config.yaml | shyaml get-value database.credentials.password

view raw JSON →