Jamie-BitFlight/dasel-Referenz

dasel v3 Syntax-Referenz

Ein-Binär-CLI zum Abfragen, Ändern und Konvertieren von strukturierten Daten. Ersetzt jq + yq + xmllint durch eine einheitliche Abfragesyntax über alle Formate hinweg.

Stabile Version zum Zeitpunkt der Erstellung (Datum: 2026-02-23): v3.2.3

Unterstützte Formate

json, yaml, toml, xml, csv, hcl, ini

Grundlegende Verwendung

# Abfrage von stdin (Format erforderlich)
echo '{"foo": "bar"}' | dasel -i json 'foo'

# Abfrage aus Datei über stdin
cat config.yaml | dasel -i yaml 'database.host'

# Ändern und vollständiges Dokument ausgeben
echo '{"port": 3000}' | dasel -i json --root 'server.port = 8080'

# Formate konvertieren
cat data.json | dasel -i json -o yaml

Formatbehandlung

dasel v3 erkennt das Format NICHT automatisch an der Dateierweiterung. Es gibt kein -f/--file-Flag. Die Eingabe wird immer über stdin gelesen. Das Format muss explizit mit -i und/oder -o angegeben werden. Wenn nur eines angegeben ist, wird das andere standardmäßig darauf gesetzt. Wenn keines angegeben ist, wird standardmäßig json verwendet (konfigurierbar über ~/dasel.yaml mit dem Schlüssel default_format).

Quelle: internal/cli/query.go:10-11, internal/cli/run.go:37-43, internal/cli/config.go:19-21

Wichtige Flags

-i, --in <format>         Eingabe-Parser (json, yaml, toml, xml, csv, hcl, ini)
-o, --out <format>        Ausgabe-Parser (standardmäßig Eingabe-Format)
--root                    Vollständiges Dokument nach Änderung ausgeben
--var <name>=<value>      Variablen in Abfrage übergeben (wiederholbar)
--compact                 Kompakte Ausgabe (keine hübsche Formatierung)
--rw-flag <name>=<value>  Lese-/Schreib-Flag (z. B. --rw-flag csv-delimiter=;)
--read-flag <name>=<val>  Lese-Flag (z. B. --read-flag xml-mode=structured)
--write-flag <name>=<val> Schreib-Flag (z. B. --write-flag csv-delimiter=;)
-c, --config <path>       Konfigurationsdateipfad (Standard: ~/dasel.yaml)

Kurzreferenz der Kernselektoren

Selektor	Syntax	Beispiel
Punktnotation	foo.bar.baz	cat f.json | dasel -i json 'foo.bar'
Array-Index	[0], [2]	cat f.json | dasel -i json 'items[0]'
Array-Ausschnitt	[0:3]	cat f.json | dasel -i json 'items[0:2]'
Rekursiver Abstieg	.., ..name	cat f.json | dasel -i json '..name'
Alle Werte rekursiv	..*	cat f.json | dasel -i json '..*'
Objektkonstruktion	{ key1, key2 }	cat f.json | dasel -i json '{ name, age }'
Spread	obj...	cat f.json | dasel -i json '{ defaults..., overrides... }'

Kurzreferenz der Schlüsselfunktionen

19 eingebaute Funktionen in DefaultFuncCollection (Quelle: execution/func.go:12-33) plus der sortBy-Komplexausdruck.

Funktion	Zweck	Beispiel
filter(pred)	Arrays filtern	users.filter(active == true)
map(expr)	Arrays transformieren	users.map(name)
each(expr)	Jedes Element ändern	each($this = $this * 2)
search(pred)	Rekursive Suche	search(has("id"))
sortBy(expr)	Array sortieren	sortBy($this, desc)
has(key)	Prüfen, ob Schlüssel existiert	has("name")
get(key)	Wert bei Schlüssel/Index abrufen	get("name")
contains(val)	Prüfen, ob Ausschnitt Wert enthält	contains(42)
len(expr)	Länge	len($this)
join(sep)	Zu String verbinden	join(",")
sum(expr)	Numerisches Array summieren	sum($this)
add(args...)	Zahlen addieren	add(1, 2, 3)
max(args...)	Maximalwert	max(1, 5, 3)
min(args...)	Minimalwert	min(1, 5, 3)
merge(args...)	Maps zusammenführen	merge(defaults, overrides)
keys(expr)	Map-Schlüssel abrufen	keys($this)
reverse(expr)	Array umkehren	reverse($this)
typeOf(expr)	Typstring abrufen	typeOf($this)
toString(expr)	In String umwandeln	toString($this)
toInt(expr)	In Integer umwandeln	toInt($this)
toFloat(expr)	In Float umwandeln	toFloat($this)
base64e(str)	Base64 kodieren	base64e("hello")
base64d(str)	Base64 dekodieren	base64d("aGVsbG8=")
parse(fmt, data)	Daten zur Laufzeit parsen	parse("json", rawStr)
readFile(path)	Dateiinhalt lesen	readFile("config.json")
ignore()	Von Verzweigung ausschließen	ignore()

Änderungssyntax

v3 hat die Unterbefehle put und delete entfernt. Verwenden Sie Zuweisung mit --root:

# Einen Wert setzen
echo '{"count": 1}' | dasel -i json --root 'count = 42'

# Boolesche Zuweisung
echo '{"enabled": false}' | dasel -i json --root 'enabled = true'

# An Array anhängen
echo '[1,2,3]' | dasel -i json --root '[$this..., 4]'

# Schlüssel entfernen (ohne ihn neu aufbauen)
echo '{"keep": "yes", "drop": "no"}' | dasel -i json --root '{ keep }'

Formatkonvertierung

# JSON zu YAML
cat data.json | dasel -i json -o yaml

# YAML zu TOML
cat config.yaml | dasel -i yaml -o toml

# TOML zu JSON
cat config.toml | dasel -i toml -o json

Spezielle Variablen

• $root – verweist auf das Stammdokument
• $this – verweist auf den aktuellen Knoten (innerhalb von each, map, filter, search)

Variablenzuweisung

# Mehrere Anweisungen mit Semikolons
cat data.json | dasel -i json '$active = users.filter(active == true); $active.map(name)'

Bedingungen

echo '{"count": 7}' | dasel -i json 'if(count > 5) { "many" } else { "few" }'

v3 Breaking Changes gegenüber v2

• Die Unterbefehle put und delete wurden entfernt; verwenden Sie Inline-Zuweisung mit --root
• Das Flag -f/--file wurde entfernt; die Eingabe erfolgt immer über stdin per Pipe
• Die Abfrage-/Selektor-Syntax wurde komplett überarbeitet; die v2-Syntax ist NICHT kompatibel mit v3
• Das CLI-Framework wurde von Cobra zu Kong geändert
• Der Go-Modulpfad wurde zu github.com/tomwright/dasel/v3 geändert

Detaillierte Referenzen

• Selektoren und Syntax – Punktnotation, Arrays, rekursiver Abstieg, Objektkonstruktion, Variablen, Bedingungen, Vergleichsoperatoren
• Funktionen-Referenz – vollständige Funktionssignaturen, Beschreibungen und Beispiele
• Formatspezifische Muster – Muster und Konvertierungshinweise für JSON, YAML, TOML, XML, CSV, HCL, INI

Quellen

1. dasel README: https://raw.githubusercontent.com/TomWright/dasel/master/README.md (abgerufen am 2026-02-19)
2. dasel-Dokumentation: https://daseldocs.tomwright.me (abgerufen am 2026-02-19)
3. Abfragesyntax: https://daseldocs.tomwright.me/syntax/query-syntax.md (abgerufen am 2026-02-19)
4. Funktionen-Index: https://daseldocs.tomwright.me/functions (abgerufen am 2026-02-19)
5. CHANGELOG: https://raw.githubusercontent.com/TomWright/dasel/master/CHANGELOG.md (abgerufen am 2026-02-19)
6. Releases: https://github.com/TomWright/dasel/releases (abgerufen am 2026-02-19)
7. Quellcode-Analyse: execution/func.go, internal/cli/query.go, internal/cli/run.go, internal/cli/config.go, execution/execute_binary.go, execution/execute_unary.go (analysiert am 2026-02-19)
8. Faktencheck: FACT_CHECK_REPORT.md (2026-02-23)