# yq — YAML und JSON auf der Kommandozeile verarbeiten > Praxis-Guide zu yq (mikefarah): YAML, JSON und XML auf der Kommandozeile abfragen, transformieren und bearbeiten — mit jq-ähnlicher Syntax. Source: https://www.jpkc.com/db/cheatsheets/files-text/yq/ yq ist ein schlanker Kommandozeilen-Prozessor für strukturierte Daten – wie `jq`, nur in erster Linie für YAML (und obendrein für JSON, XML, CSV, TOML und Properties). Achte darauf, welches yq du installiert hast: Dieser Guide bezieht sich auf das in Go geschriebene **mikefarah/yq** mit seiner eigenen, jq-ähnlichen Ausdruckssyntax (`yq eval`, `yq '.foo'`, `-i` für In-Place-Bearbeitung, `-o=json` für die Ausgabe). Das ältere **kislyuk/yq** ist hingegen ein Python-Wrapper um `jq` und verwendet eine andere Syntax – die folgenden Beispiele funktionieren dort so nicht. Du fragst damit Werte ab, filterst Listen, änderst Dateien direkt und konvertierst zwischen Formaten, und das nahtlos in Pipelines mit Tools wie `kubectl` oder `docker compose`. ## Lesen & Abfragen `yq ` — Gibt eine YAML-Datei formatiert aus. ```bash yq config.yaml ``` `yq '.' ` — Liest einen bestimmten Schlüssel. ```bash yq '.server.port' config.yaml ``` `yq '..' ` — Liest einen verschachtelten Wert. ```bash yq '.database.connection.host' config.yaml ``` `yq '.[]' ` — Liest ein Array-Element über seinen Index. ```bash yq '.services[0].name' docker-compose.yml ``` `yq '.[]' ` — Iteriert über alle Array-Elemente. ```bash yq '.users[].email' config.yaml ``` `yq '.[] | key' ` — Listet alle Schlüssel der obersten Ebene auf. ```bash yq '.[] | key' config.yaml ``` ## Ändern & Aktualisieren `yq '. = ""' ` — Setzt einen Wert (Ausgabe nach stdout). ```bash yq '.server.port = 8080' config.yaml ``` `yq -i '. = ""' ` — Setzt einen Wert direkt in der Datei (In-Place). ```bash yq -i '.version = "2.0.0"' config.yaml ``` `yq '. += ""' ` — Hängt einen Wert an ein Array an. ```bash yq -i '.tags += ["new-tag"]' config.yaml ``` `yq 'del(.)' ` — Löscht einen Schlüssel. ```bash yq -i 'del(.deprecated_setting)' config.yaml ``` `yq '. |= . + 1' ` — Erhöht einen numerischen Wert. ```bash yq -i '.build_number |= . + 1' version.yaml ``` ## Filtern & Auswählen `yq '.[] | select(. == "")' ` — Wählt Elemente aus, die eine Bedingung erfüllen. ```bash yq '.users[] | select(.role == "admin")' users.yaml ``` `yq '.[] | select(. > )' ` — Wählt Elemente per numerischem Vergleich aus. ```bash yq '.items[] | select(.price > 100)' catalog.yaml ``` `yq '. | length' ` — Zählt die Elemente eines Arrays. ```bash yq '.services | length' docker-compose.yml ``` `yq '.[] | keys' ` — Listet die Schlüssel einer Map auf. ```bash yq '.services | keys' docker-compose.yml ``` `yq 'has("")' ` — Prüft, ob ein Schlüssel existiert. ```bash yq 'has("database")' config.yaml ``` ## Formatkonvertierung `yq -o=json ` — Konvertiert YAML nach JSON. ```bash yq -o=json config.yaml > config.json ``` `yq -p=json ` — Liest JSON ein und gibt YAML aus. ```bash yq -p=json config.json > config.yaml ``` `yq -p=json -o=yaml ` — Konvertiert JSON nach YAML (explizit). ```bash yq -p=json -o=yaml package.json ``` `yq -o=xml ` — Konvertiert YAML nach XML. ```bash yq -o=xml config.yaml ``` `yq -o=csv ` — Konvertiert YAML nach CSV. ```bash yq -o=csv '.users' data.yaml ``` `yq -o=props ` — Konvertiert YAML ins Java-Properties-Format. ```bash yq -o=props config.yaml ``` ## Zusammenführen & Multi-Dokument `yq '. * load("")' ` — Führt zwei YAML-Dateien tief zusammen (die zweite überschreibt die erste). ```bash yq '. * load("overrides.yaml")' base.yaml ``` `yq eval-all '. as $item ireduce ({}; . * $item)' ` — Führt mehrere Dateien zusammen. ```bash yq eval-all '. as $item ireduce ({}; . * $item)' defaults.yaml env.yaml ``` `yq -s '"doc_" + $index' ` — Teilt ein Multi-Dokument-YAML in einzelne Dateien auf. ```bash yq -s '"doc_" + $index' multi.yaml ``` `yq 'select(documentIndex == 0)' ` — Wählt ein bestimmtes Dokument aus einem Multi-Dokument-YAML aus. ```bash yq 'select(documentIndex == 0)' multi.yaml ``` ## Pipes & gängige Muster `cat | yq '.'` — Liest von stdin. ```bash kubectl get pod mypod -o yaml | yq '.metadata.labels' ``` `yq -r '.' ` — Rohe Ausgabe (ohne Anführungszeichen um Strings). ```bash yq -r '.image' deployment.yaml ``` `yq -i '.image = "nginx:1.25"' deployment.yaml` — Aktualisiert eine Container-Image-Version in einem Kubernetes-Manifest. ```bash yq -i '.spec.template.spec.containers[0].image = "nginx:1.25"' deployment.yaml ``` `yq '.env_file' docker-compose.yml` — Inspiziert eine Docker-Compose-Konfiguration auf der Kommandozeile. ```bash yq '.services.web.environment' docker-compose.yml ``` ## Fazit yq macht das Lesen und Umbauen von YAML, JSON und Co. auf der Kommandozeile so bequem, wie `jq` es für JSON ist – ideal für Pipelines mit `kubectl`, `docker compose` oder CI-Skripten. Behalte aber im Kopf, dass alle hier gezeigten Beispiele für **mikefarah/yq** (Go) gelten; mit dem Python-Wrapper **kislyuk/yq** sehen viele Ausdrücke anders aus. Besondere Vorsicht ist bei `-i` (In-Place) geboten: yq überschreibt die Datei direkt und ohne Rückfrage – lege vorher ein Backup an oder arbeite unter Versionskontrolle, und teste neue Ausdrücke zuerst ohne `-i`, indem du die Ausgabe nach stdout prüfst. Beachte außerdem, dass yq beim In-Place-Bearbeiten Kommentare und Formatierung weitgehend erhält, die Datei aber dennoch normalisieren kann. ## Weiterführende Links - [mikefarah/yq – Dokumentation](https://mikefarah.gitbook.io/yq/) – offizielles Handbuch mit allen Operatoren und Beispielen (englisch) - [mikefarah/yq auf GitHub](https://github.com/mikefarah/yq) – Quellcode, Installationsanleitung und Release-Notes (englisch) ## Verwandte Kommandos - [jq](https://www.jpkc.com/db/cheatsheets/files-text/jq/) – das Pendant zu yq für JSON-Daten - [sed](https://www.jpkc.com/db/cheatsheets/files-text/sed/) – Stream-Editor für zeilenbasierte Textbearbeitung - [grep](https://www.jpkc.com/db/cheatsheets/files-text/grep/) – durchsucht Text nach Mustern