### Download and install yq binary (Linux example)

Source: https://github.com/mikefarah/yq/blob/master/README.md

Download a specific version of the yq binary for Linux AMD64, extract it, and move it to the local bin directory. Adjust PLATFORM and VERSION variables as needed.

```bash
# Set your platform variables (adjust as needed)
VERSION=v4.2.0
PLATFORM=linux_amd64

# Download compressed binary
wget https://github.com/mikefarah/yq/releases/download/${VERSION}/yq_${PLATFORM}.tar.gz -O - |\
  tar xz && sudo mv yq_${PLATFORM} /usr/local/bin/yq

# Or download plain binary
wget https://github.com/mikefarah/yq/releases/download/${VERSION}/yq_${PLATFORM} -O /usr/local/bin/yq &&\
    chmod +x /usr/local/bin/yq
```

--------------------------------

### Install Cosign

Source: https://github.com/mikefarah/yq/blob/master/release_instructions.txt

Instructions for installing the cosign tool for verifying release artifacts.

```bash
brew install cosign
```

```bash
go install github.com/sigstore/cosign/v2/cmd/cosign@v2.6.1
```

--------------------------------

### Install yq with Webi

Source: https://github.com/mikefarah/yq/blob/master/README.md

Install yq using the Webi package installer.

```bash
webi yq
```

--------------------------------

### Install yq on Windows with Winget

Source: https://github.com/mikefarah/yq/blob/master/README.md

Install yq on Windows using the winget package manager.

```bash
winget install --id MikeFarah.yq
```

--------------------------------

### Install yq via Snap

Source: https://github.com/mikefarah/yq/blob/master/README.md

Install yq on Linux using the Snap package manager.

```bash
snap install yq
```

--------------------------------

### Install yq with Nix

Source: https://github.com/mikefarah/yq/blob/master/README.md

Install yq using the Nix package manager.

```bash
nix profile install nixpkgs#yq-go
```

--------------------------------

### Install Development Tools

Source: https://github.com/mikefarah/yq/blob/master/CONTRIBUTING.md

Run this script to install necessary development tools like golangci-lint and gosec.

```bash
scripts/devtools.sh
```

--------------------------------

### Install yq with Go

Source: https://github.com/mikefarah/yq/blob/master/README.md

Install the latest version of yq using the Go build tools.

```bash
go install github.com/mikefarah/yq/v4@latest
```

--------------------------------

### Install yq on Windows with Scoop

Source: https://github.com/mikefarah/yq/blob/master/README.md

Install yq on Windows using the Scoop package manager.

```bash
scoop install main/yq
```

--------------------------------

### Snapcraft - Install and Test Edge Version

Source: https://github.com/mikefarah/yq/blob/master/release_instructions.txt

Remove the current yq snap, install the edge version, and test it. This is a prerequisite before promoting to stable.

```bash
sudo snap remove yq
```

```bash
sudo snap install --edge yq
```

--------------------------------

### Example: Summing Array Elements

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/headers/reduce.md

Demonstrates a practical use case of the reduce operator to sum all elements in an array. The accumulator starts at 0 and adds each item.

```yaml
.[] as $item ireduce (0; . + $item)
```

--------------------------------

### Install yq on MacOS/Linux via gah

Source: https://github.com/mikefarah/yq/blob/master/README.md

Install yq on macOS and Linux systems using the 'gah' installation tool.

```bash
gah install yq
```

--------------------------------

### Install yq on Windows with Chocolatey

Source: https://github.com/mikefarah/yq/blob/master/README.md

Install yq on Windows using the Chocolatey package manager.

```powershell
choco install yq
```

--------------------------------

### Install Vendor Dependencies

Source: https://github.com/mikefarah/yq/blob/master/CONTRIBUTING.md

Use this make command to install project dependencies. Use `make [local] vendor` for local development.

```bash
make [local] vendor
```

--------------------------------

### Install yq with Flox

Source: https://github.com/mikefarah/yq/blob/master/README.md

Install yq on Linux, macOS, and Windows (via WSL) using the Flox package manager.

```bash
flox install yq
```

--------------------------------

### XML Raw Token Example

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/usage/headers/xml.md

Demonstrates the `--xml-raw-token` flag. When true, it bypasses checks for matching start and end elements and does not translate namespace prefixes to URLs.

```bash
echo '<root><item>value</item></root>' | yq --xml-raw-token
```

--------------------------------

### Install yq on Arch Linux

Source: https://github.com/mikefarah/yq/blob/master/README.md

Install yq on Arch Linux using the pacman package manager.

```bash
pacman -S go-yq
```

--------------------------------

### Install yq on Alpine Linux (up to v3.19)

Source: https://github.com/mikefarah/yq/blob/master/README.md

Install yq on Alpine Linux versions up to 3.19 using apk.

```bash
apk add yq
```

--------------------------------

### Install yq on Alpine Linux (v3.20+)

Source: https://github.com/mikefarah/yq/blob/master/README.md

Install yq on Alpine Linux versions 3.20 and newer using apk.

```bash
apk add yq-go
```

--------------------------------

### Install yq via Homebrew

Source: https://github.com/mikefarah/yq/blob/master/README.md

Install yq on macOS or Linux using the Homebrew package manager.

```bash
brew install yq
```

--------------------------------

### Install yq with MacPorts

Source: https://github.com/mikefarah/yq/blob/master/README.md

Install yq on macOS using the MacPorts package manager.

```bash
sudo port selfupdate
sudo port install yq
```

--------------------------------

### Install latest yq binary (Linux AMD64)

Source: https://github.com/mikefarah/yq/blob/master/README.md

Download the latest yq binary for Linux AMD64 directly to /usr/local/bin and make it executable.

```bash
wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/local/bin/yq &&\
    chmod +x /usr/local/bin/yq
```

--------------------------------

### XML Processing Instruction Prefix Example

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/usage/headers/xml.md

Demonstrates how to configure the prefix for XML processing instructions using the `--xml-proc-inst-prefix` flag.

```bash
echo '<?xml version="1"?>' | yq --xml-proc-inst-prefix '+p_'
```

--------------------------------

### YAML Document Example

Source: https://github.com/mikefarah/yq/blob/master/how-it-works.md

This is the input document used to demonstrate the relative update operator.

```yaml
a: 1
b: thing
```

--------------------------------

### ALL Operator Example (Empty Array)

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/boolean-operators.md

Demonstrates that 'all' returns true for an empty array. Requires an array as input.

```yaml
[]
```

```bash
yq 'all' sample.yml
```

--------------------------------

### Update and Set Style Using Path Variables

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/style.md

This example demonstrates setting a node's value and style using the `with` operator and path variables for more complex updates.

```bash
yq 'with(.a.b ; . = "new" | . style="double")' sample.yml
```

--------------------------------

### Verify Release Artifacts with Cosign

Source: https://github.com/mikefarah/yq/blob/master/release_instructions.txt

Use cosign to verify the integrity of release artifacts. Ensure cosign is installed via Homebrew or Go.

```bash
cosign verify-blob --bundle checksums.bundle checksums
```

--------------------------------

### XML Skip Processing Instructions Example

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/usage/headers/xml.md

Shows how to use the `--xml-skip-proc-inst` flag to ignore XML processing instructions, such as the XML declaration.

```bash
echo '<?xml version="1"?><root>data</root>' | yq --xml-skip-proc-inst
```

--------------------------------

### ANY Operator Example (Empty Array)

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/boolean-operators.md

Demonstrates that 'any' returns false for an empty array. Requires an array as input.

```yaml
[]
```

```bash
yq 'any' sample.yml
```

--------------------------------

### Simple Pipe Example

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/pipe.md

Demonstrates piping the result of one expression to another to extract a nested value.

```yaml
a:
  b: cat
```

```bash
yq '.a | .b' sample.yml
```

```yaml
cat
```

--------------------------------

### ALL Operator Example (True)

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/boolean-operators.md

Shows how 'all' returns true if all boolean elements in an array sequence are true. Requires an array as input.

```yaml
- true
- true
```

```bash
yq 'all' sample.yml
```

--------------------------------

### Create YAML from scratch with a single object

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/create-collect-into-object.md

Generate a new YAML document from scratch with a simple key-value pair. The `--null-input` flag is used to start with an empty document.

```bash
yq --null-input '{"wrap": "frog"}'
```

--------------------------------

### Load YAML File

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/headers/load.md

Use the `load` operator to include the content of a YAML file. The example shows loading `../../examples/thing.yml`.

```yaml
yq -n ". + load(\"../../examples/thing.yml\")"
```

--------------------------------

### ANY Operator Example (True)

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/boolean-operators.md

Shows how 'any' returns true if at least one boolean in an array sequence is true. Requires an array as input.

```yaml
- false
- true
```

```bash
yq 'any' sample.yml
```

--------------------------------

### Documentation Header File

Source: https://github.com/mikefarah/yq/blob/master/AGENTS.md

Create `pkg/yqlib/doc/operators/headers/<type>.md`. Use the exact operator name as the title and include a concise 1-2 sentence summary. Add additional context or examples if the operator is complex.

```markdown
# <type>

<Concise 1-2 sentence summary>

<Additional context or examples if the operator is complex>
```

--------------------------------

### Get Line Comment Example

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/comment-operators.md

Retrieve the line comment associated with a scalar value.

```bash
yq '.a | line_comment' sample.yml
```

--------------------------------

### Get All Parents

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/parent.md

The `parents` operator returns an array of all ancestor nodes, starting from the immediate parent up to the root. This is useful for tracing the full path to a node.

```bash
yq '.a.b.c | parents' sample.yml
```

--------------------------------

### NOT Operator Example (False)

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/boolean-operators.md

Demonstrates the 'not' operator flipping a false boolean to true.

```bash
yq --null-input 'false | not'
```

--------------------------------

### Sum Numbers with yq

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/reduce.md

This example shows how to sum a list of numbers from a YAML file using the `ireduce` operator. The output is the total sum.

```bash
yq '.[] as $item ireduce (0; . + $item)' sample.yml
```

--------------------------------

### Read root file with snap confinement

Source: https://github.com/mikefarah/yq/blob/master/README.md

When yq is installed via snap, it has strict confinement. To read root files, use `sudo cat` to pipe the content to yq.

```bash
sudo cat /etc/myfile | yq '.a.path'
```

--------------------------------

### XML Directive Name Example

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/usage/headers/xml.md

Shows how to set a custom name for XML directives (like DOCTYPE) using the `--xml-directive-name` flag.

```bash
echo '<!DOCTYPE config system "blah">' | yq --xml-directive-name '+directive'
```

--------------------------------

### NOT Operator Example (True)

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/boolean-operators.md

Demonstrates the 'not' operator flipping a true boolean to false.

```bash
yq --null-input 'true | not'
```

--------------------------------

### OR Operator Example

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/boolean-operators.md

Demonstrates the basic usage of the 'or' operator. Returns true if either operand is true.

```bash
yq --null-input 'true or false'
```

--------------------------------

### XML Skip Directives Example

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/usage/headers/xml.md

Demonstrates the `--xml-skip-directives` flag, which allows skipping over XML directives like DOCTYPE declarations.

```bash
echo '<!DOCTYPE config> <root>data</root>' | yq --xml-skip-directives
```

--------------------------------

### Line Operator Starts at 1

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/line.md

The line operator returns 1-based line numbers. This example demonstrates that the first line of the YAML is correctly identified as line 1.

```bash
yq '.a | line' sample.yml
```

--------------------------------

### Create a New CandidateNode

Source: https://github.com/mikefarah/yq/blob/master/AGENTS.md

Use the `NewCandidate()` function to create a new `CandidateNode` instance. This is the starting point for representing and manipulating YAML nodes.

```go
NewCandidate()
```

--------------------------------

### Run yq as Root User with Podman

Source: https://github.com/mikefarah/yq/blob/master/README.md

Execute yq commands as the root user within a Podman container to manage permissions or install additional tools.

```bash
podman run --user="root" -it --entrypoint sh mikefarah/yq
```

--------------------------------

### Load XML File

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/headers/load.md

Use the `load_xml` operator to parse and include the content of an XML file. The example demonstrates loading `small.xml`.

```yaml
yq -n ". + load_xml(\"small.xml\")"
```

--------------------------------

### Vendor Dependencies

Source: https://github.com/mikefarah/yq/blob/master/AGENTS.md

Use 'make local vendor' to manage and install project dependencies locally. This command is intended for use when Docker is unavailable.

```bash
make local vendor
```

--------------------------------

### XML Attribute Prefix Example

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/usage/headers/xml.md

Demonstrates how the `--xml-attribute-prefix` flag controls the prefix for XML attributes. This is useful for avoiding name collisions with other XML elements.

```bash
echo '<cat legs="4"/>' | yq --xml-attribute-prefix '+'
```

--------------------------------

### ALL_C Operator Example

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/boolean-operators.md

Illustrates 'all_c' which checks if all elements in an array satisfy a given condition. The condition is applied to each element.

```yaml
a:
  - rad
  - awesome
b:
  - meh
  - 12
```

```bash
yq '.[] |= all_c(tag == "!!str")' sample.yml
```

```yaml
a: true
b: false
```

--------------------------------

### GitHub Action: Set yq Value

Source: https://github.com/mikefarah/yq/blob/master/README.md

Example of a GitHub Action step to set a value in a YAML file using yq.

```yaml
  - name: Set foobar to cool
    uses: mikefarah/yq@master
    with:
      cmd: yq -i '.foo.bar = "cool"' 'config.yml'
```

--------------------------------

### Configure Dockerfile to Run yq as Root

Source: https://github.com/mikefarah/yq/blob/master/README.md

Modify a Dockerfile to set the user to root, allowing for package installations, and then switch back to the yq user.

```dockerfile
FROM mikefarah/yq

USER root
RUN apk add --no-cache bash
USER yq
```

--------------------------------

### Add Test Scenario for Addition Operator

Source: https://github.com/mikefarah/yq/blob/master/CONTRIBUTING.md

Example of adding a test scenario for the addition operator. Ensure to include `skipDoc: true` if documentation generation is not desired for this specific test.

```go
var addOperatorScenarios = []expressionScenario{
    {
        skipDoc:    true,
        expression: "\"foo\" + \"bar\"",
        expected: []string{
            "D0, P[], (!!str)::foobar\n",
        },
    },
    {
        document:   "apples: 3",
        expression: ".apples + 3",
        expected: []string{
            "D0, P[apples], (!!int)::6\n",
        },
    },
}
```

--------------------------------

### Load Properties File

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/headers/load.md

Use the `load_props` operator to load and parse a Java properties file. The example shows loading `small.properties`.

```yaml
yq -n ". + load_props(\"small.properties\")"
```

--------------------------------

### Roundtrip TOML with Sample Table

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/usage/toml.md

Demonstrates reading a TOML file with a sample table and outputting it.

```toml
var = "x"

[owner.contact]
name = "Tom Preston-Werner"
age = 36

```

```bash
yq '.' sample.toml
```

```yaml
var = "x"

[owner.contact]
name = "Tom Preston-Werner"
age = 36

```

--------------------------------

### Run Unit Tests Locally

Source: https://github.com/mikefarah/yq/blob/master/AGENTS.md

Execute the unit test suite using 'make local test' or 'bash scripts/test.sh'. Ensure golangci-lint is in your PATH.

```bash
make local test
```

```bash
bash scripts/test.sh
```

--------------------------------

### Split Array into Separate Documents

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/split-into-documents.md

This example demonstrates how to split an array into individual YAML documents, with each element of the array becoming a separate document separated by '---'.

```yaml
- a: cat
- b: dog
```

```bash
yq '.[] | split_doc' sample.yml
```

--------------------------------

### Docker - Build and Tag Images

Source: https://github.com/mikefarah/yq/blob/master/release_instructions.txt

Build the Docker image and tag it for both the latest version and the specific new version.

```docker
docker build .  -t mikefarah/yq:latest -t mikefarah/yq:3 -t mikefarah/yq:3.X
```

--------------------------------

### Get Array Length with yq

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/length.md

Use the length operator on an array to get the number of elements.

```yaml
- 2
- 4
- 6
- 8
```

```bash
yq 'length' sample.yml
```

--------------------------------

### Load Plain Text File

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/headers/load.md

Use the `load_str` operator to load the raw content of a text file as a string. The example shows loading `base64.txt`.

```yaml
yq -n ". + load_str(\"base64.txt\")"
```

--------------------------------

### GitHub Action: Get Value with Dynamic Key

Source: https://github.com/mikefarah/yq/blob/master/README.md

Demonstrates retrieving a value from a YAML file using a dynamic key from a GitHub Actions matrix.

```yaml
  - name: Get an entry with a variable that might contain dots or spaces
    id: get_username
    uses: mikefarah/yq@master
    with:
      cmd: yq '.all.children.["${{ matrix.ip_address }}"].username' ops/inventories/production.yml
```

--------------------------------

### Get Map Length with yq

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/length.md

Use the length operator on a map to get the number of key-value pairs.

```yaml
a: cat
c: dog
```

```bash
yq 'length' sample.yml
```

--------------------------------

### Get String Length with yq

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/length.md

Use the length operator to get the number of characters in a string value.

```yaml
a: cat
```

```bash
yq '.a | length' sample.yml
```

--------------------------------

### Run yq as Root User with Docker

Source: https://github.com/mikefarah/yq/blob/master/README.md

Execute yq commands as the root user within a Docker container to manage permissions or install additional tools.

```bash
docker run --user="root" -it --entrypoint sh mikefarah/yq
```

--------------------------------

### Operator Implementation File Structure

Source: https://github.com/mikefarah/yq/blob/master/AGENTS.md

Create a Go file for your operator implementation. Implement the `operatorHandler` function, process nodes from `context.MatchingNodes`, and return a new `Context` using `context.ChildContext()`. Use `candidate.CreateReplacement()` or `candidate.CreateReplacementWithComments()` to create new nodes and handle errors gracefully.

```go
package yqlib

import (
	"fmt"
	"strings"
)

func <type>Operator(context Context, expression Expression) (Context, error) {
	return context.ChildContext(), nil
}

func <type>Handler(context Context, expression Expression) (Context, error) {
	var newNodes []interface{}

	for _, candidate := range context.MatchingNodes {
		// Process nodes from context.MatchingNodes
		// Example: create a new node
		newNode := candidate.CreateReplacementWithComments(candidate.Node, candidate.Path, candidate.LeadingContent)
		newNodes = append(newNodes, newNode)
	}

	return context.ChildContext(newNodes...), nil
}
```

--------------------------------

### Build yq Binary

Source: https://github.com/mikefarah/yq/blob/master/CONTRIBUTING.md

Command to build the yq executable. Use `make [local] build` for local development.

```bash
make [local] build
```

--------------------------------

### Get Array Index with yq

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/path.md

To get only the index of an array element, pipe the result of `path` to `.[-1]` after selecting the element.

```bash
yq '.a.[] | select(. == "dog") | path | .[-1]' sample.yml
```

--------------------------------

### Lint Code Locally

Source: https://github.com/mikefarah/yq/blob/master/AGENTS.md

Run the code linter to check for potential issues and enforce code quality standards using 'make local check'. Requires golangci-lint to be installed.

```bash
make local check
```

--------------------------------

### Build yq Binary Locally

Source: https://github.com/mikefarah/yq/blob/master/AGENTS.md

Compile the yq binary directly using 'go build' or via the 'make local build' command. 'make local build' also runs the full CI chain.

```bash
go build -o yq .
```

```bash
make local build
```

--------------------------------

### XML Content Name Example

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/usage/headers/xml.md

Illustrates the use of `--xml-content-name` to specify a name for the text content within an XML element, especially when mixed with other child elements.

```bash
echo '<cat>Meow <fur>true</fur></cat>' | yq --xml-content-name '+content'
```

--------------------------------

### Get Map Key with yq

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/path.md

To get only the key of a map, pipe the result of `path` to `.[-1]` to extract the last element of the path array.

```bash
yq '.a.b | path | .[-1]' sample.yml
```

--------------------------------

### Get Map Path with yq

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/path.md

Use the `path` operator to get the traversal path to a map value. The path is returned as an array of keys.

```bash
yq '.a.b | path' sample.yml
```

--------------------------------

### Run yq with Podman (process files)

Source: https://github.com/mikefarah/yq/blob/master/README.md

Execute yq within a Podman container to process files in the current directory. Mount the current working directory to `/workdir` inside the container.

```bash
# Podman - same usage as Docker
podman run --rm -v "${PWD}":/workdir mikefarah/yq '.a.b[0].c' file.yaml
```

--------------------------------

### Get Map Keys with `keys`

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/keys.md

Use the `keys` operator to get a list of all keys from a map. This is useful when you need to iterate over or inspect the keys of a map.

```bash
yq 'keys' sample.yml
```

--------------------------------

### Get Line of Key Node

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/line.md

Pipe the output of the key operator to the line operator to get the line number of the key itself. This is useful for debugging or understanding the structure of your YAML.

```bash
yq '.b | key | line' sample.yml
```

--------------------------------

### Get Column of Key Node

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/column.md

Pipe the output of the key operator to the column operator to get the character offset of the key itself. This helps in analyzing the structure and formatting of your YAML.

```bash
yq '.b | key | column' sample.yml
```

--------------------------------

### Debian Package - Build Source Package

Source: https://github.com/mikefarah/yq/blob/master/release_instructions.txt

Build the Debian source package. GPG key signing is required for uploading to a PPA.

```bash
debuild -i -I -S -sa
```

--------------------------------

### Get Array Path with yq

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/path.md

Use the `path` operator with array traversal (`.[]`) and `select` to get the path to an element in an array. The path includes the array key and the element's index.

```bash
yq '.a.[] | select(. == "dog") | path' sample.yml
```

--------------------------------

### Get File Index Alias with YQ

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/file-operators.md

Use the short alias `fi` for `file_index` to get the zero-based index of a YAML document. This provides a more concise way to access file indices.

```bash
yq 'fi' sample.yml
```

--------------------------------

### Run All Checks and Tests

Source: https://github.com/mikefarah/yq/blob/master/CONTRIBUTING.md

Execute all code quality checks, formatting, security analysis, and tests. Use `make [local] test` for local development.

```bash
make [local] test
```

--------------------------------

### Slice Array - From Start

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/slice-array.md

Extracts a subarray from the beginning up to index 2 (exclusive).

```bash
yq '.[:2]' sample.yml
```

--------------------------------

### Format Code

Source: https://github.com/mikefarah/yq/blob/master/CONTRIBUTING.md

Use this make command to format the project's code according to established standards. Use `make [local] format` for local development.

```bash
make [local] format
```

--------------------------------

### Get Null Length with yq

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/length.md

The length operator returns 0 for null values.

```yaml
a: null
```

```bash
yq '.a | length' sample.yml
```

--------------------------------

### Slice String - From Start

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/slice-array.md

Extracts a substring from the beginning of the string up to index 5 (exclusive).

```bash
yq '.country[:5]' sample.yml
```

--------------------------------

### Recurse Map (Values and Keys)

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/recursive-descent-glob.md

Demonstrates the '...' operator on a simple map, showing that it returns the map's value, the map's key, and the map itself.

```yaml
a: frog
```

```bash
yq '...' sample.yml
```

--------------------------------

### Execute yq command to load YAML

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/load.md

This command demonstrates loading the content of a YAML file specified by a path within the input YAML.

```bash
yq 'load(.myFile)' sample.yml
```

--------------------------------

### Get Alias

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/anchor-and-alias-operators.md

Use the `alias` operator to retrieve the name of an alias associated with a YAML node.

```bash
yq '.a | alias' sample.yml
```

--------------------------------

### Run Test to Regenerate Operator Documentation

Source: https://github.com/mikefarah/yq/blob/master/CONTRIBUTING.md

Navigate to the `pkg/yqlib` directory and run this command to regenerate documentation from test scenarios. Ensure `skipDoc: false` for scenarios you want to document.

```bash
cd pkg/yqlib
go test -run TestAddOperatorScenarios
```

--------------------------------

### Get Anchor

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/anchor-and-alias-operators.md

Use the `anchor` operator to retrieve the name of an anchor associated with a YAML node.

```bash
yq '.a | anchor' sample.yml
```

--------------------------------

### Run Acceptance Tests

Source: https://github.com/mikefarah/yq/blob/master/AGENTS.md

Execute the end-to-end acceptance tests using 'bash scripts/acceptance.sh'. This requires the yq binary to be built first.

```bash
bash scripts/acceptance.sh
```

--------------------------------

### Get Foot Comment

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/comment-operators.md

Use the `foot_comment` operator to extract all comments from the end of a YAML document.

```yaml
# welcome!

a: cat # meow

# have a great day
# no really
```

```bash
yq '. | foot_comment' sample.yml
```

--------------------------------

### Run Tests with Coverage

Source: https://github.com/mikefarah/yq/blob/master/CONTRIBUTING.md

Generate test coverage reports. Use `make [local] cover` for local development.

```bash
make [local] cover
```

--------------------------------

### Get Head Comment

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/comment-operators.md

Use the `head_comment` operator to retrieve the very first comment in a YAML document.

```yaml
# welcome!

a: cat # meow

# have a great day
```

```bash
yq '. | head_comment' sample.yml
```

--------------------------------

### AND Operator Example

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/boolean-operators.md

Demonstrates the basic usage of the 'and' operator. Returns true only if both operands are true.

```bash
yq --null-input 'true and false'
```

--------------------------------

### Test Coverage Example

Source: https://github.com/mikefarah/yq/blob/master/AGENTS.md

Ensure test coverage includes basic data types, nested structures, edge cases like empty inputs or type errors, multiple outputs, and format-specific features. Use `documentScenarios` to generate testcase documentation.

```go
func TestOperator<Type>AllScenarios(t *testing.T) {
	documentScenarios(t, "Operator <type>", usage, allExpressionScenarios)
}
```

--------------------------------

### Get Filename with YQ

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/file-operators.md

Retrieve the filename of the current YAML document being processed. This is useful for conditional logic or logging.

```bash
yq 'filename' sample.yml
```

--------------------------------

### Set Value on Empty Document with yq

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/path.md

Demonstrates setting a path and value on an empty document using `setpath`. This initializes the structure.

```bash
yq --null-input 'setpath(["a", "b"]; "things")'
```

--------------------------------

### Parse XML: Custom DTD

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/usage/xml.md

DTD entities are processed as directives. This example shows how yq handles them during parsing.

```xml
<?xml version="1.0"?>
<!DOCTYPE root [
<!ENTITY writer "Blah.">
<!ENTITY copyright "Blah">
]>
<root>
    <item>&writer;&copyright;</item>
</root>
```

```bash
yq sample.xml
```

```xml
<?xml version="1.0"?>
<!DOCTYPE root [
<!ENTITY writer "Blah.">
<!ENTITY copyright "Blah">
]>
<root>
  <item>&amp;writer;&amp;copyright;</item>
</root>
```

--------------------------------

### Execute yq Expression File with Comments

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/usage/formatting-expressions.md

Use whitespace and comments to break up complex expressions and explain what's going on. Ensure the expression file is executable.

```yaml
a:
  b: old
```

```bash
#! yq

# This is a yq expression that updates the map
# for several great reasons outlined here.

.a.b = "new" # line comment here
| .a.c = "frog"

# Now good things will happen.
```

```bash
./update.yq sample.yaml
```

```yaml
a:
  b: new
  c: frog
```

--------------------------------

### Decode Properties to YAML

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/usage/properties.md

Decodes a properties file into a YAML structure. This example shows the basic decoding functionality.

```properties
# block comments come through
# comments on values appear
person.name = Mike Wazowski


```

```bash
yq -p props sample.properties
```

--------------------------------

### Update Generated Documentation

Source: https://github.com/mikefarah/yq/blob/master/CONTRIBUTING.md

If generated documentation does not update after test changes, navigate to `pkg/yqlib` and run `go test -run TestSpecificOperatorScenarios`. Verify the update in `pkg/yqlib/doc/`.

```bash
cd pkg/yqlib
go test -run TestSpecificOperatorScenarios
```

--------------------------------

### Group by Field

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/group-by.md

Use `group_by` to group array elements by the value of a specified field. This example groups by the 'foo' field.

```yaml
- foo: 1
  bar: 10
- foo: 3
  bar: 100
- foo: 1
  bar: 1
```

```bash
yq 'group_by(.foo)' sample.yml
```

```yaml
- - foo: 1
    bar: 10
  - foo: 1
    bar: 1
- - foo: 3
    bar: 100
```

--------------------------------

### ANY_C Operator Example

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/boolean-operators.md

Illustrates 'any_c' which checks if any element in an array satisfies a given condition. The condition is applied to each element.

```yaml
a:
  - rad
  - awesome
b:
  - meh
  - whatever
```

```bash
yq '.[] |= any_c(. == "awesome")' sample.yml
```

```yaml
a: true
b: false
```

--------------------------------

### Format Preferences Structure

Source: https://github.com/mikefarah/yq/blob/master/AGENTS.md

Define preferences for format-specific output, such as indentation levels. Ensure a Copy method is implemented.

```go
type <format>Preferences struct {
    Indent int
}

func (prefs *<format>Preferences) Copy() <format>Preferences {
    return *prefs
}
```

--------------------------------

### Run yq Interactively with Podman

Source: https://github.com/mikefarah/yq/blob/master/README.md

Use this command to run yq interactively within a Podman container, mounting the current directory for file access.

```bash
podman run --rm -it -v "${PWD}":/workdir --entrypoint sh mikefarah/yq
```

--------------------------------

### Extracting a Field from Filtered Nodes

Source: https://github.com/mikefarah/yq/blob/master/how-it-works.md

After filtering, you can extract specific fields from the remaining nodes. This example extracts the 'name' field.

```yaml
.root.items[] | select(.type == "fruit") | .name
```

--------------------------------

### Splatting Merge Anchor Lists (Legacy)

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/traverse-read.md

Demonstrates splatting a list of merge anchors, showcasing the legacy override behavior where later anchors take precedence. The output reflects the merged and overridden values.

```bash
yq '.foobarList[]' sample.yml
```

--------------------------------

### Retrieve Document Index

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/document-index.md

Use `document_index` to get the 0-based index of the current document. This is useful when you need to know which document you are operating on.

```bash
yq '.a | document_index' sample.yml
```

--------------------------------

### Enable and Use System Operator

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/headers/system-operators.md

Demonstrates how to enable the system operator and use it to execute an external command. The current node's value is piped to the command's stdin, and its stdout is returned.

```bash
yq --security-enable-system-operator --null-input '.field = system("command"; "arg1")'
```

--------------------------------

### Get Day of the Week

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/datetime.md

Extracts the day of the week from a date string using `format_datetime` with a format string that specifies only the day name.

```yaml
a: 2001-12-15
```

```bash
yq '.a | format_datetime("Monday")' sample.yml
```

--------------------------------

### Encode XML: Attributes

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/usage/xml.md

Fields prefixed with '+@' are treated as XML attributes. This example shows how to encode a YAML map with an attribute.

```yaml
cat:
  +@name: tiger
  meows: true
```

```bash
yq -o=xml sample.yml
```

```xml
<cat name="tiger">
  <meows>true</meows>
</cat>
```

--------------------------------

### Create YAML from scratch with multiple objects

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/create-collect-into-object.md

Construct a new YAML document containing multiple distinct objects. This is achieved by chaining assignment operations.

```bash
yq --null-input '(.a.b = "foo") | (.d.e = "bar")'
```

--------------------------------

### Load Properties file content

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/load.md

Use `load_props` to load a Java properties file and convert its key-value pairs into a YAML object. This is convenient for migrating configurations.

```yaml
cool: things
```

```bash
yq '.more_stuff = load_props("../../examples/small.properties")' sample.yml
```

--------------------------------

### Add Go Binaries to PATH

Source: https://github.com/mikefarah/yq/blob/master/AGENTS.md

After running scripts/devtools.sh, ensure Go tool binaries are accessible by adding the go bin directory to your PATH environment variable.

```bash
export PATH="$HOME/go/bin:$PATH"
```

--------------------------------

### Decoder Interface Methods

Source: https://github.com/mikefarah/yq/blob/master/AGENTS.md

Implement these methods to initialize the decoder and read data from an input reader, returning decoded documents. The `Decode` method should return `io.EOF` when finished.

```go
Init() - Initialize the decoder with the input reader and set up any needed state
Decode() - Decode one document from the input and return a `CandidateNode`, or `io.EOF` when finished
```

--------------------------------

### Set Array Path on Empty Document with yq

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/path.md

Demonstrates setting an array element on an empty document using `setpath`. This initializes the array and sets the element.

```bash
yq --null-input 'setpath(["a", 0]; "things")'
```

--------------------------------

### Get Node Tags

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/tag.md

Use the 'tag' operator to retrieve the YAML tag for all nodes in a document. This is useful for understanding the data types present.

```yaml
a: cat
b: 5
c: 3.2
e: true
f: []
```

```bash
yq '.. | tag' sample.yml
```

```yaml
!!map
!!str
!!int
!!float
!!bool
!!seq
```

--------------------------------

### Get Top (Root) Parent

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/parent.md

Use `parent(-1)` to retrieve the root parent, which is the top-level node of the document. This is equivalent to the `root` operator.

```bash
yq '.a.b.c | parent(-1)' sample.yml
```

--------------------------------

### Create YAML File with Assign Operator

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/assign-update.md

Demonstrates creating a new YAML structure by assigning values to nodes using the `=` operator.

```bash
yq --null-input '.a.b = "cat" | .x = "frog"'
```

--------------------------------

### Format and Check Code

Source: https://github.com/mikefarah/yq/blob/master/CONTRIBUTING.md

Run these commands to automatically fix code formatting issues and then check for linting errors. Use `[local]` to specify running within a Docker container if needed.

```bash
make [local] format  # Auto-fix formatting
# Manually fix remaining linting issues
make [local] check   # Verify fixes
```

--------------------------------

### Run yq with Docker (restricted privileges)

Source: https://github.com/mikefarah/yq/blob/master/README.md

Run yq in a Docker container with enhanced security by dropping all capabilities and disabling new privileges.

```bash
docker run --rm --security-opt=no-new-privileges --cap-drop all --network none \
  -v "${PWD}":/workdir mikefarah/yq '.a.b[0].c' file.yaml
```

--------------------------------

### Run Command with Argument

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/system-operators.md

Shows how to successfully run an external command with an argument using the system operator after enabling it. The output of the command replaces the node's value.

```yaml
country: Australia
```

```bash
yq --security-enable-system-operator '.country = system("/bin/echo"; "test")' sample.yml
```

```yaml
country: test
```

--------------------------------

### Format Code Locally

Source: https://github.com/mikefarah/yq/blob/master/AGENTS.md

Apply code formatting rules to the project using the 'make local format' command. This ensures consistent code style.

```bash
make local format
```

--------------------------------

### Enable Optional Format Compilation with Build Tags

Source: https://github.com/mikefarah/yq/blob/master/AGENTS.md

Use build tags to conditionally compile formats. Add the `//go:build !yq_no<format>` directive to your encoder/decoder files and create a no-build version in `pkg/yqlib/no_<format>.go`.

```go
//go:build !yq_no<format>
```

--------------------------------

### Load Base64 Encoded File

Source: https://github.com/mikefarah/yq/blob/master/pkg/yqlib/doc/operators/headers/load.md

Use the `load_base64` operator to load a Base64 encoded UTF-8 string from a file. The example loads `base64.txt`.

```yaml
yq -n ". + load_base64(\"base64.txt\")"
```

--------------------------------

### Write to root file with snap confinement using temporary file

Source: https://github.com/mikefarah/yq/blob/master/README.md

An alternative method to write to root files with snap confinement is to use a temporary file, then move it to the target location.

```bash
sudo cat /etc/myfile | yq '.a.path = "value"' | sudo tee /etc/myfile.tmp
sudo mv /etc/myfile.tmp /etc/myfile
rm /etc/myfile.tmp
```

--------------------------------

### Pipe data to yq with Docker

Source: https://github.com/mikefarah/yq/blob/master/README.md

Process data piped via STDIN to yq running in a Docker container. Use the `-i --interactive` flag.

```bash
# Process piped data
docker run -i --rm mikefarah/yq '.this.thing' < myfile.yml
```

--------------------------------

### Filtering Nodes Based on a Condition

Source: https://github.com/mikefarah/yq/blob/master/how-it-works.md

Use the 'select' function to filter nodes based on a condition. This example selects items where the 'type' is 'fruit'.

```yaml
.root.items[] | select(.type == "fruit")
```