jq y yq CHEATSHEET

Que resuelve

Cheatsheet para leer, filtrar y transformar JSON con jq y YAML con yq desde terminal.

jq basico

Formatear JSON

jq . {FILE_JSON}

Leer una propiedad

jq '.{KEY}' {FILE_JSON}

Leer propiedad anidada

jq '.{KEY}.{SUBKEY}' {FILE_JSON}

Leer array

jq '.{ARRAY}[]' {FILE_JSON}

Leer campo de cada elemento

jq '.{ARRAY}[].{KEY}' {FILE_JSON}

jq con curl

API y formateo

curl -fsS https://{HOST}/{PATH} | jq .

Extraer campo

curl -fsS https://{HOST}/{PATH} | jq -r '.{KEY}'

-r imprime texto raw, util para scripts.

Filtros utiles

Seleccionar por valor

jq '.[] | select(.{KEY} == "{VALUE}")' {FILE_JSON}

Seleccionar por numero

jq '.[] | select(.{KEY} > {NUMBER})' {FILE_JSON}

Comprobar existencia

jq '.[] | select(has("{KEY}"))' {FILE_JSON}

Valor por defecto

jq '.{KEY} // "{DEFAULT}"' {FILE_JSON}

Transformaciones

Crear objeto nuevo

jq '{name: .name, id: .id}' {FILE_JSON}

Crear lista de campos

jq '[.[] | {name: .name, id: .id}]' {FILE_JSON}

Convertir a TSV

jq -r '.[] | [.id, .name] | @tsv' {FILE_JSON}

Ordenar por campo

jq 'sort_by(.{KEY})' {FILE_JSON}

Agrupar por campo

jq 'group_by(.{KEY})' {FILE_JSON}

jq en scripts

Pasar variable shell

jq --arg value "{VALUE}" '.[] | select(.{KEY} == $value)' {FILE_JSON}

Pasar numero

jq --argjson n {NUMBER} '.[] | select(.{KEY} > $n)' {FILE_JSON}

Fallar si el filtro no devuelve nada

jq -e '.{KEY}' {FILE_JSON}

yq basico

Formatear YAML

yq . {FILE_YAML}

Leer propiedad

yq '.{KEY}' {FILE_YAML}

Leer propiedad anidada

yq '.{KEY}.{SUBKEY}' {FILE_YAML}

Leer array

yq '.{ARRAY}[]' {FILE_YAML}

yq para editar

Cambiar valor en salida

yq '.{KEY} = "{VALUE}"' {FILE_YAML}

Editar archivo in-place

yq -i '.{KEY} = "{VALUE}"' {FILE_YAML}

Anadir elemento a array

yq -i '.{ARRAY} += ["{VALUE}"]' {FILE_YAML}

⚠️warning

Antes de usar -i, prueba el filtro sin modificar el archivo o guarda backup.

Recetas

Ver imagenes de un Compose

yq '.services[].image' docker-compose.yml

Extraer puertos de Compose

yq '.services[].ports[]' docker-compose.yml

Extraer nombres de contenedores de Docker JSON

docker inspect {CONTAINER} | jq -r '.[].Name'

Listar claves de un objeto

jq 'keys' {FILE_JSON}

Validar JSON

jq empty {FILE_JSON}

Validar YAML

yq e '.' {FILE_YAML} >/dev/null

Variables

Variable	Descripcion
{FILE_JSON}	Archivo JSON
{FILE_YAML}	Archivo YAML
{KEY}	Clave del objeto
{SUBKEY}	Clave anidada
{ARRAY}	Nombre de array
{VALUE}	Valor de comparacion o escritura

Errores comunes

Sintoma	Causa probable	Solucion
Sale con comillas	Salida JSON	Usa -r
null inesperado	Ruta inexistente	Comprueba con keys
yq -i rompe formato	Edicion directa	Prueba sin -i antes
Filtro falla en arrays	Falta []	Usa .items[] o similar

Checklist final

• Usa comillas simples alrededor del filtro.

• Usa -r cuando la salida alimenta otro comando.

• Usa --arg para variables de shell.

• Prueba yq sin -i antes de editar.

- EOF -