LinuxCommandLibrary

yq

Process YAML data from the command line

TLDR

Output a YAML file, in pretty-print format (v4+)

$ yq eval [path/to/file.yaml]
copy

Output a YAML file, in pretty-print format (v3)
$ yq read [path/to/file.yaml] [[-C|--colors]]
copy

Output the first element in a YAML file that contains only an array (v4+)
$ yq eval '.[0]' [path/to/file.yaml]
copy

Output the first element in a YAML file that contains only an array (v3)
$ yq read [path/to/file.yaml] '[0]'
copy

Set (or overwrite) a key to a value in a file (v4+)
$ yq eval '.[key] = "[value]"' [[-i|--inplace]] [path/to/file.yaml]
copy

Set (or overwrite) a key to a value in a file (v3)
$ yq write [[-i|--inplace]] [path/to/file.yaml] '[key]' '[value]'
copy

Merge two files and print to stdout (v4+)
$ yq eval-all 'select(filename == "[path/to/file1.yaml]") * select(filename == "[path/to/file2.yaml]")' [path/to/file1.yaml] [path/to/file2.yaml]
copy

Merge two files and print to stdout (v3)
$ yq merge [path/to/file1.yaml] [path/to/file2.yaml] [[-C|--colors]]
copy

SYNOPSIS

yq [options] [...]
yq [options] [] [...]

PARAMETERS

-i, --inplace
    Edit files in place. Creates a backup file unless --inplace=false is specified.

-o, --output-format
    Set the output format. Supported formats include: yaml, json, xml, tsv, csv, properties.

-p, --prettyPrint
    Pretty print the output. This formats the output for readability.

-C, --colors
    Enable colored output for better readability in terminals.

-r, --raw-output
    Output raw strings, without quotes for string values.

--arg
    Pass a string argument to the expression, accessible as $name.

--from-file
    Read the yq expression from the specified file.

DESCRIPTION

yq is a portable command-line YAML, JSON, XML, TOML, CSV, and properties processor, often referred to as 'jq for YAML'. It provides a powerful and intuitive way to query, update, and transform structured data files directly from the terminal. Unlike traditional text processing tools, yq understands the underlying data structure, allowing for precise manipulation of elements based on their hierarchical path.

Its primary use cases include extracting specific values from configuration files, modifying Kubernetes manifests, converting data between different formats (e.g., YAML to JSON), and programmatically updating various structured documents. yq's syntax is inspired by jq, making it familiar to users already comfortable with JSON processing. It supports in-place editing, making it invaluable for scripting automated file modifications. Its ability to handle multiple input files and stream processing further enhances its utility for complex data workflows. yq is an essential tool for DevOps engineers, developers, and anyone working extensively with configuration or data files in a variety of structured formats.

CAVEATS

It's important to note that there are multiple tools named 'yq'. This analysis refers specifically to the mikefarah/yq project, which is widely adopted for its robust features and active development. A common caveat is that in-place editing (-i) can sometimes reformat comments or change the ordering of map keys, although efforts are continually made to preserve them. Complex YAML anchors and aliases might also behave unexpectedly during certain modification operations, or be lost entirely when rewriting files.

COMMON USE CASES

Extracting and manipulating values from YAML/JSON configuration files.
Automating modifications to Kubernetes manifests.
Converting data between YAML, JSON, XML, TOML, and other supported formats.
Filtering and transforming structured logs or data streams.

INSTALLATION

yq is typically distributed as a single static binary, making installation straightforward. It can often be installed via popular package managers like Homebrew (macOS/Linux), Scoop (Windows), or directly downloaded from its GitHub releases page.

For example, on macOS you can use: brew install yq

HISTORY

yq emerged as a versatile command-line tool to fill the gap for a robust YAML processor, much like jq serves for JSON. The mikefarah/yq implementation, developed by Mike Farah, quickly gained prominence due to its comprehensive feature set, cross-platform compatibility, and ability to handle complex YAML structures, including in-place editing. Its design philosophy aimed for jq-like syntax and power, making it an indispensable tool for modern infrastructure and data management workflows.

SEE ALSO

jq(1), sed(1), awk(1), grep(1), yaml(7)

Copied to clipboard