yq — Basics

Key Access

yq uses jq-compatible syntax to navigate YAML structures. The . operator is the identity — the entire document. Dot-path notation descends into nested keys.

Read a top-level scalar

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

The bare .key expression returns the value at that key. No flags needed for simple reads — yq defaults to YAML output.

Read multiple scalars in one pass

yq '.name, .title, .version' docs/antora.yml
# Output:
# captures
# Work Chronicles
# null

Comma-separated expressions evaluate left to right. null means the key exists but has no value (YAML ~).

Nested Paths

Descend into nested keys with dot-path

yq '.asciidoc.attributes.domain' docs/antora.yml
# Output: inside.domusdigitalis.dev

Access a deeply nested attribute

yq '.asciidoc.attributes["ise-ip"]' docs/antora.yml
# Output: 10.50.1.20

Bracket notation is required when keys contain hyphens. attributes.ise-ip would be parsed as attributes.ise minus ip.

Access with bracket notation — always safe

yq '.asciidoc.attributes["vault-port"]' docs/antora.yml
# Output: 8200

Keys and Length

List top-level keys

yq 'keys' docs/antora.yml
# Output:
# - asciidoc
# - name
# - nav
# - start_page
# - title
# - version

Count all attribute keys

yq '.asciidoc.attributes | keys | length' docs/antora.yml
# Output: ~134 (varies as attributes are added)

List attribute keys alphabetically (default)

yq '.asciidoc.attributes | keys' docs/antora.yml | head -10
# Output:
# - ad-dc-hostname
# - ad-dc-ip
# - attribute-missing
# - author
# - bind-ip
# - bt-buds-mac
# - bt-buds-name
# - bt-kinesis-mac
# - bt-kinesis-name
# - category

Type Inspection

Check the type of a value

yq '.name | type' docs/antora.yml
# Output: !!str

Check type of a collection

yq '.nav | type' docs/antora.yml
# Output: !!seq

Check type of the attributes map

yq '.asciidoc.attributes | type' docs/antora.yml
# Output: !!map

!!str is string, !!seq is array/sequence, !!map is object/mapping. These are YAML tags — yq preserves them, jq does not.

Array Traversal

Access array elements by index

yq '.nav[0]' docs/antora.yml
# Output: modules/ROOT/nav.adoc

Iterate all array elements

yq '.nav[]' docs/antora.yml
# Output: modules/ROOT/nav.adoc

The [] operator iterates a sequence, producing one output per element. [0] selects by index. Negative indices work: [-1] is the last element.

Array length

yq '.nav | length' docs/antora.yml
# Output: 1

Has and Existence

Check if a key exists

yq '.asciidoc.attributes | has("domain")' docs/antora.yml
# Output: true

Check for a key that does not exist

yq '.asciidoc.attributes | has("nonexistent-key")' docs/antora.yml
# Output: false

has() returns a boolean. Use it in select() to filter collections.

Raw Output

Raw string output — no quotes

yq -r '.asciidoc.attributes.domain' docs/antora.yml
# Output: inside.domusdigitalis.dev

Without -r, string values are quoted in the output. With -r, the raw string is emitted — critical for shell variable capture:

Capture into a shell variable

domain=$(yq -r '.asciidoc.attributes.domain' docs/antora.yml)
echo "$domain"
# Output: inside.domusdigitalis.dev