yq — Output

Raw Output (-r)

By default yq emits YAML. The -r flag strips quotes from string output.

Default vs raw output

yq '.name' docs/antora.yml
# Output: captures

yq -r '.name' docs/antora.yml
# Output: captures

For strings, -r removes surrounding quotes. Critical when piping to other commands or capturing in variables.

Pipe-safe variable capture

version=$(yq -r '.version // "unset"' docs/antora.yml)
echo "Version: $version"
# Output: Version: unset

The // operator provides a default value when the result is null.

JSON Output (-o json)

Convert YAML to JSON

yq -o json '.asciidoc.attributes | with_entries(select(.key | test("^port-")))' docs/antora.yml
# Output:
# {
#   "port-https": "443",
#   "port-ssh": "22",
#   "port-kerberos": "88",
#   "port-ldap": "389",
#   "port-ldaps": "636",
#   "port-gc": "3268",
#   "port-dns": "53",
#   "port-dhcp-server": "67",
#   "port-dhcp-client": "68",
#   "port-ntp": "123",
#   "port-smtp": "25",
#   "port-submission": "587",
#   "port-imaps": "993"
# }

Pipe yq JSON output to jq for further processing

yq -o json '.' docs/antora.yml | jq '.asciidoc.attributes | keys | length'
# Output: ~134

This is the bridge between YAML and JSON toolchains.

Compact Output (-c)

Compact JSON — one line, no whitespace

yq -o json -c '.asciidoc.attributes | with_entries(select(.key | test("^vyos-")))' docs/antora.yml
# Output: {"vyos-vip":"10.50.1.1","vyos-01-hostname":"vyos-01.inside.domusdigitalis.dev","vyos-01-ip":"10.50.1.2","vyos-02-hostname":"vyos-02.inside.domusdigitalis.dev","vyos-02-ip":"10.50.1.3"}

Compact output is useful for logging, API payloads, and shell pipelines.

CSV and TSV Output

Output as tab-separated values

yq -r '.asciidoc.attributes | to_entries[] | select(.key | test("^port-")) | [.key, .value] | @tsv' docs/antora.yml
# Output:
# port-https	443
# port-ssh	22
# port-kerberos	88
# port-ldap	389
# ...

@tsv formats an array as tab-separated values.

Output as CSV

yq -r '.asciidoc.attributes | to_entries[] | select(.key | test("^port-")) | [.key, .value] | @csv' docs/antora.yml
# Output:
# "port-https","443"
# "port-ssh","22"
# "port-kerberos","88"
# ...

@csv adds quoting per RFC 4180. Use @tsv when piping to awk or column.

Format Strings

String interpolation with \()

yq -r '.asciidoc.attributes | to_entries[] | select(.key | test("^ise-")) | "export \(.key | upcase)=\(.value)"' docs/antora.yml
# Output:
# export ISE-HOSTNAME=ise-01.inside.domusdigitalis.dev
# export ISE-IP=10.50.1.20
# export ISE-ERS-PORT=9060
# ...

\() inside a string performs interpolation. upcase / downcase transform case.

Generate shell export statements

yq -r '.asciidoc.attributes | to_entries[] | select(.key | test("^vault-")) | "export \(.key | sub("-"; "_"; "g") | upcase)=\"\(.value)\""' docs/antora.yml
# Output:
# export VAULT_HOSTNAME="vault-01.inside.domusdigitalis.dev"
# export VAULT_01_HOSTNAME="vault-01.inside.domusdigitalis.dev"
# export VAULT_IP="10.50.1.60"
# export VAULT_01_IP="10.50.1.60"
# export VAULT_PORT="8200"
# ...

sub("-"; "_"; "g") replaces all hyphens with underscores (the "g" flag makes it global, equivalent to gsub).

@base64 Encoding/Decoding

Base64 encode a value

echo 'secret: "my-token-value"' | yq -r '.secret | @base64'
# Output: bXktdG9rZW4tdmFsdWU=

Base64 decode

echo 'encoded: bXktdG9rZW4tdmFsdWU=' | yq -r '.encoded | @base64d'
# Output: my-token-value

Common in Kubernetes secrets which store values as base64.

XML Output (-o xml)

Convert YAML to XML

cat <<'YAML' > /tmp/test.yml
server:
  name: ise-01
  ip: 10.50.1.20
  ports:
    - 443
    - 9060
YAML
yq -o xml '.' /tmp/test.yml
# Output:
# <server>
#   <name>ise-01</name>
#   <ip>10.50.1.20</ip>
#   <ports>443</ports>
#   <ports>9060</ports>
# </server>

Properties Output (-o props)

Convert to Java properties format

cat <<'YAML' > /tmp/test.yml
database:
  host: db-01.inside.domusdigitalis.dev
  port: 5432
  name: monad
YAML
yq -o props '.' /tmp/test.yml
# Output:
# database.host = db-01.inside.domusdigitalis.dev
# database.port = 5432
# database.name = monad

Useful for Spring Boot configuration or systemd environment files.

Combining Output Modes

JSON array, one line per element

yq -o json -r '.asciidoc.attributes | to_entries[] | select(.key | test("^k3s-")) | .key + "=" + .value' docs/antora.yml
# Output:
# k3s-master-ip=10.50.1.120
# k3s-master-hostname=k3s-master-01.inside.domusdigitalis.dev

YAML output piped to column for aligned display

yq -r '.asciidoc.attributes | to_entries[] | select(.key | test("-ip$")) | [.key, .value] | @tsv' docs/antora.yml | column -t
# Output:
# ise-ip       10.50.1.20
# vault-ip     10.50.1.60
# vault-01-ip  10.50.1.60
# pfsense-ip   10.50.1.1
# nas-ip       10.50.1.70
# keycloak-ip  10.50.1.80
# k3s-master-ip  10.50.1.120
# ad-dc-ip     10.50.1.50
# kvm-01-ip    10.50.1.100
# kvm-02-ip    10.50.1.101
# vyos-01-ip   10.50.1.2
# vyos-02-ip   10.50.1.3
# mail-ip      10.50.1.91
# bind-ip      10.50.1.90