yq
Process YAML data from the command line
TLDR
Output a YAML file, in pretty-print format (v4+)
Output a YAML file, in pretty-print format (v3)
Output the first element in a YAML file that contains only an array (v4+)
Output the first element in a YAML file that contains only an array (v3)
Set (or overwrite) a key to a value in a file (v4+)
Set (or overwrite) a key to a value in a file (v3)
Merge two files and print to stdout (v4+)
Merge two files and print to stdout (v3)
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.