dasel v3 Syntax Reference
Single-binary CLI for querying, modifying, and converting structured data. Replaces jq + yq + xmllint with one unified query syntax across all formats.
Stable version at writing (date: 2026-02-23): v3.2.3
Supported Formats
json, yaml, toml, xml, csv, hcl, ini
Basic Usage
# Query from stdin (format required)
echo '{"foo": "bar"}' | dasel -i json 'foo'
# Query from file via stdin
cat config.yaml | dasel -i yaml 'database.host'
# Modify and output full document
echo '{"port": 3000}' | dasel -i json --root 'server.port = 8080'
# Convert formats
cat data.json | dasel -i json -o yaml
Format Handling
dasel v3 does NOT auto-detect format from file extension. There is no -f/--file flag. Input is always read from stdin. Format must be specified explicitly with -i and/or -o. If only one is given, the other defaults to it. If neither is given, both default to json (configurable via ~/dasel.yaml with default_format key).
Source: internal/cli/query.go:10-11, internal/cli/run.go:37-43, internal/cli/config.go:19-21
Key Flags
-i, --in <format> Input parser (json, yaml, toml, xml, csv, hcl, ini)
-o, --out <format> Output parser (defaults to input format)
--root Output full document after modification
--var <name>=<value> Pass variables into query (repeatable)
--compact Compact output (no pretty-printing)
--rw-flag <name>=<value> Read/write flag (e.g., --rw-flag csv-delimiter=;)
--read-flag <name>=<val> Reader flag (e.g., --read-flag xml-mode=structured)
--write-flag <name>=<val> Writer flag (e.g., --write-flag csv-delimiter=;)
-c, --config <path> Config file path (default: ~/dasel.yaml)
Core Selectors Quick Reference
| Selector |
Syntax |
Example |
| Dot notation |
foo.bar.baz |
cat f.json | dasel -i json 'foo.bar' |
| Array index |
[0], [2] |
cat f.json | dasel -i json 'items[0]' |
| Array slice |
[0:3] |
cat f.json | dasel -i json 'items[0:2]' |
| Recursive descent |
.., ..name |
cat f.json | dasel -i json '..name' |
| All values recursive |
..* |
cat f.json | dasel -i json '..*' |
| Object construction |
{ key1, key2 } |
cat f.json | dasel -i json '{ name, age }' |
| Spread |
obj... |
cat f.json | dasel -i json '{ defaults..., overrides... }' |
Key Functions Quick Reference
19 built-in functions in DefaultFuncCollection (source: execution/func.go:12-33) plus the sortBy complex expression.
| Function |
Purpose |
Example |
filter(pred) |
Filter arrays |
users.filter(active == true) |
map(expr) |
Transform arrays |
users.map(name) |
each(expr) |
Modify each element |
each($this = $this * 2) |
search(pred) |
Recursive search |
search(has("id")) |
sortBy(expr) |
Sort array |
sortBy($this, desc) |
has(key) |
Check key exists |
has("name") |
get(key) |
Get value at key/index |
get("name") |
contains(val) |
Check slice contains value |
contains(42) |
len(expr) |
Length |
len($this) |
join(sep) |
Join to string |
join(",") |
sum(expr) |
Sum numeric array |
sum($this) |
add(args...) |
Add numbers |
add(1, 2, 3) |
max(args...) |
Maximum value |
max(1, 5, 3) |
min(args...) |
Minimum value |
min(1, 5, 3) |
merge(args...) |
Merge maps |
merge(defaults, overrides) |
keys(expr) |
Get map keys |
keys($this) |
reverse(expr) |
Reverse array |
reverse($this) |
typeOf(expr) |
Get type string |
typeOf($this) |
toString(expr) |
Cast to string |
toString($this) |
toInt(expr) |
Cast to integer |
toInt($this) |
toFloat(expr) |
Cast to float |
toFloat($this) |
base64e(str) |
Base64 encode |
base64e("hello") |
base64d(str) |
Base64 decode |
base64d("aGVsbG8=") |
parse(fmt, data) |
Parse data at runtime |
parse("json", rawStr) |
readFile(path) |
Read file contents |
readFile("config.json") |
ignore() |
Exclude from branch |
ignore() |
Modification Syntax
v3 removed put and delete subcommands. Use assignment with --root:
# Set a value
echo '{"count": 1}' | dasel -i json --root 'count = 42'
# Boolean assignment
echo '{"enabled": false}' | dasel -i json --root 'enabled = true'
# Append to array
echo '[1,2,3]' | dasel -i json --root '[$this..., 4]'
# Remove key (reconstruct without it)
echo '{"keep": "yes", "drop": "no"}' | dasel -i json --root '{ keep }'
Format Conversion
# JSON to YAML
cat data.json | dasel -i json -o yaml
# YAML to TOML
cat config.yaml | dasel -i yaml -o toml
# TOML to JSON
cat config.toml | dasel -i toml -o json
Special Variables
$root -- references the root document$this -- references the current node (inside each, map, filter, search)
Variable Assignment
# Multi-statement with semicolons
cat data.json | dasel -i json '$active = users.filter(active == true); $active.map(name)'
Conditionals
echo '{"count": 7}' | dasel -i json 'if(count > 5) { "many" } else { "few" }'
v3 Breaking Changes from v2
put and delete subcommands removed; use inline assignment with --root-f/--file flag removed; input always comes from stdin via pipe- Query/selector syntax completely revamped; v2 syntax is NOT compatible with v3
- CLI framework changed from Cobra to Kong
- Go module path changed to
github.com/tomwright/dasel/v3
Detailed References
- Selectors and Syntax -- dot notation, arrays, recursive descent, object construction, variables, conditionals, comparison operators
- Functions Reference -- complete function signatures, descriptions, and examples
- Format-Specific Patterns -- JSON, YAML, TOML, XML, CSV, HCL, INI patterns and conversion caveats
Sources
- dasel README: https://raw.githubusercontent.com/TomWright/dasel/master/README.md (fetched 2026-02-19)
- dasel docs: https://daseldocs.tomwright.me (fetched 2026-02-19)
- Query syntax: https://daseldocs.tomwright.me/syntax/query-syntax.md (fetched 2026-02-19)
- Functions index: https://daseldocs.tomwright.me/functions (fetched 2026-02-19)
- CHANGELOG: https://raw.githubusercontent.com/TomWright/dasel/master/CHANGELOG.md (fetched 2026-02-19)
- Releases: https://github.com/TomWright/dasel/releases (fetched 2026-02-19)
- Source code analysis:
execution/func.go, internal/cli/query.go, internal/cli/run.go, internal/cli/config.go, execution/execute_binary.go, execution/execute_unary.go (analyzed 2026-02-19)
- Fact-check: FACT_CHECK_REPORT.md (2026-02-23)
1---2name: dasel-reference3description: Use when querying, modifying, or converting JSON, YAML, TOML, XML, CSV, HCL, or INI with dasel v3. Complete reference for selectors, functions, conditionals, variables, spread operator, type casting, and format-specific patterns.4---56# dasel v3 Syntax Reference78Single-binary CLI for querying, modifying, and converting structured data. Replaces `jq` + `yq` + `xmllint` with one unified query syntax across all formats.910Stable version at writing (date: 2026-02-23): **v3.2.3**1112## Supported Formats1314`json`, `yaml`, `toml`, `xml`, `csv`, `hcl`, `ini`1516## Basic Usage1718```bash19# Query from stdin (format required)20echo '{"foo": "bar"}' | dasel -i json 'foo'2122# Query from file via stdin23cat config.yaml | dasel -i yaml 'database.host'2425# Modify and output full document26echo '{"port": 3000}' | dasel -i json --root 'server.port = 8080'2728# Convert formats29cat data.json | dasel -i json -o yaml30```3132## Format Handling3334dasel v3 does NOT auto-detect format from file extension. There is no `-f`/`--file` flag. Input is always read from stdin. Format must be specified explicitly with `-i` and/or `-o`. If only one is given, the other defaults to it. If neither is given, both default to `json` (configurable via `~/dasel.yaml` with `default_format` key).3536Source: `internal/cli/query.go:10-11`, `internal/cli/run.go:37-43`, `internal/cli/config.go:19-21`3738## Key Flags3940```text41-i, --in <format> Input parser (json, yaml, toml, xml, csv, hcl, ini)42-o, --out <format> Output parser (defaults to input format)43--root Output full document after modification44--var <name>=<value> Pass variables into query (repeatable)45--compact Compact output (no pretty-printing)46--rw-flag <name>=<value> Read/write flag (e.g., --rw-flag csv-delimiter=;)47--read-flag <name>=<val> Reader flag (e.g., --read-flag xml-mode=structured)48--write-flag <name>=<val> Writer flag (e.g., --write-flag csv-delimiter=;)49-c, --config <path> Config file path (default: ~/dasel.yaml)50```5152## Core Selectors Quick Reference5354| Selector | Syntax | Example |55|----------|--------|---------|56| Dot notation | `foo.bar.baz` | `cat f.json \| dasel -i json 'foo.bar'` |57| Array index | `[0]`, `[2]` | `cat f.json \| dasel -i json 'items[0]'` |58| Array slice | `[0:3]` | `cat f.json \| dasel -i json 'items[0:2]'` |59| Recursive descent | `..`, `..name` | `cat f.json \| dasel -i json '..name'` |60| All values recursive | `..*` | `cat f.json \| dasel -i json '..*'` |61| Object construction | `{ key1, key2 }` | `cat f.json \| dasel -i json '{ name, age }'` |62| Spread | `obj...` | `cat f.json \| dasel -i json '{ defaults..., overrides... }'` |6364## Key Functions Quick Reference656619 built-in functions in `DefaultFuncCollection` (source: `execution/func.go:12-33`) plus the `sortBy` complex expression.6768| Function | Purpose | Example |69|----------|---------|---------|70| `filter(pred)` | Filter arrays | `users.filter(active == true)` |71| `map(expr)` | Transform arrays | `users.map(name)` |72| `each(expr)` | Modify each element | `each($this = $this * 2)` |73| `search(pred)` | Recursive search | `search(has("id"))` |74| `sortBy(expr)` | Sort array | `sortBy($this, desc)` |75| `has(key)` | Check key exists | `has("name")` |76| `get(key)` | Get value at key/index | `get("name")` |77| `contains(val)` | Check slice contains value | `contains(42)` |78| `len(expr)` | Length | `len($this)` |79| `join(sep)` | Join to string | `join(",")` |80| `sum(expr)` | Sum numeric array | `sum($this)` |81| `add(args...)` | Add numbers | `add(1, 2, 3)` |82| `max(args...)` | Maximum value | `max(1, 5, 3)` |83| `min(args...)` | Minimum value | `min(1, 5, 3)` |84| `merge(args...)` | Merge maps | `merge(defaults, overrides)` |85| `keys(expr)` | Get map keys | `keys($this)` |86| `reverse(expr)` | Reverse array | `reverse($this)` |87| `typeOf(expr)` | Get type string | `typeOf($this)` |88| `toString(expr)` | Cast to string | `toString($this)` |89| `toInt(expr)` | Cast to integer | `toInt($this)` |90| `toFloat(expr)` | Cast to float | `toFloat($this)` |91| `base64e(str)` | Base64 encode | `base64e("hello")` |92| `base64d(str)` | Base64 decode | `base64d("aGVsbG8=")` |93| `parse(fmt, data)` | Parse data at runtime | `parse("json", rawStr)` |94| `readFile(path)` | Read file contents | `readFile("config.json")` |95| `ignore()` | Exclude from branch | `ignore()` |9697## Modification Syntax9899v3 removed `put` and `delete` subcommands. Use assignment with `--root`:100101```bash102# Set a value103echo '{"count": 1}' | dasel -i json --root 'count = 42'104105# Boolean assignment106echo '{"enabled": false}' | dasel -i json --root 'enabled = true'107108# Append to array109echo '[1,2,3]' | dasel -i json --root '[$this..., 4]'110111# Remove key (reconstruct without it)112echo '{"keep": "yes", "drop": "no"}' | dasel -i json --root '{ keep }'113```114115## Format Conversion116117```bash118# JSON to YAML119cat data.json | dasel -i json -o yaml120121# YAML to TOML122cat config.yaml | dasel -i yaml -o toml123124# TOML to JSON125cat config.toml | dasel -i toml -o json126```127128## Special Variables129130- `$root` -- references the root document131- `$this` -- references the current node (inside `each`, `map`, `filter`, `search`)132133## Variable Assignment134135```bash136# Multi-statement with semicolons137cat data.json | dasel -i json '$active = users.filter(active == true); $active.map(name)'138```139140## Conditionals141142```bash143echo '{"count": 7}' | dasel -i json 'if(count > 5) { "many" } else { "few" }'144```145146## v3 Breaking Changes from v2147148- `put` and `delete` subcommands removed; use inline assignment with `--root`149- `-f`/`--file` flag removed; input always comes from stdin via pipe150- Query/selector syntax completely revamped; v2 syntax is NOT compatible with v3151- CLI framework changed from Cobra to Kong152- Go module path changed to `github.com/tomwright/dasel/v3`153154## Detailed References155156- [Selectors and Syntax](./references/selectors-and-syntax.md) -- dot notation, arrays, recursive descent, object construction, variables, conditionals, comparison operators157- [Functions Reference](./references/functions.md) -- complete function signatures, descriptions, and examples158- [Format-Specific Patterns](./references/format-patterns.md) -- JSON, YAML, TOML, XML, CSV, HCL, INI patterns and conversion caveats159160## Sources1611621. **dasel README**: <https://raw.githubusercontent.com/TomWright/dasel/master/README.md> (fetched 2026-02-19)1632. **dasel docs**: <https://daseldocs.tomwright.me> (fetched 2026-02-19)1643. **Query syntax**: <https://daseldocs.tomwright.me/syntax/query-syntax.md> (fetched 2026-02-19)1654. **Functions index**: <https://daseldocs.tomwright.me/functions> (fetched 2026-02-19)1665. **CHANGELOG**: <https://raw.githubusercontent.com/TomWright/dasel/master/CHANGELOG.md> (fetched 2026-02-19)1676. **Releases**: <https://github.com/TomWright/dasel/releases> (fetched 2026-02-19)1687. **Source code analysis**: `execution/func.go`, `internal/cli/query.go`, `internal/cli/run.go`, `internal/cli/config.go`, `execution/execute_binary.go`, `execution/execute_unary.go` (analyzed 2026-02-19)1698. **Fact-check**: [FACT_CHECK_REPORT.md](./FACT_CHECK_REPORT.md) (2026-02-23)
Jamie-BitFlight