Skip to content

Format examples

nesdit reads and writes JSON, YAML, and TOML. By default the output format equals the input format. Use --output-format to transcode to a different format.

Current limitations

  • Comments are not preserved across round-trips. This is an explicit non-goal for v1. If your files contain comments that matter, keep the source-of-truth file elsewhere and generate the deployed copy from it.
  • YAML anchors and aliases are resolved on decode and not re-emitted. Output contains the fully expanded values. Merge keys (<<: *anchor) are applied at decode time — merged fields appear as regular keys in the output map, with explicit keys taking precedence over merged defaults.
  • JSON output is always compact (single-line, no indentation). --pretty currently only affects TOML output.
  • YAML quoted strings are normalized to bare scalars on output. A value like "100m" becomes 100m. This applies to all keys in the document, not only those touched by the query.

JSON → JSON

Input (config.json):

{"x":1,"y":2}

Identity round-trip (no mutation):

nesdit config.json --query '.'

Stdout:

{"x":1,"y":2}

Key order is preserved exactly. The output is byte-identical to the input.

Field mutation:

nesdit config.json --query '.x = 99'

Stdout:

{"x":99,"y":2}

Field deletion:

nesdit config.json --create-missing --query 'del(.y)'

Stdout:

{"x":1}

YAML → YAML

Input (values.yaml):

name: alpha
version: 1

Identity round-trip:

nesdit values.yaml --query '.'

Stdout:

name: alpha
version: 1

Multi-document stream:

Input (stream.yaml):

name: alpha
version: 1
---
name: beta
version: 1
---
name: gamma
version: 1

nesdit --format yaml --query '.version = 2' < stream.yaml

Stdout:

---
name: alpha
version: 2
---
name: beta
version: 2
---
name: gamma
version: 2

TOML → TOML

Input (project.toml):

version = "1.0"
name = "project"

Mutation:

nesdit project.toml --query '.version = "2.0"'

Stdout:

version = "2.0"
name = "project"

Note

nesdit always emits TOML using inline-table syntax for nested structures. This preserves your key order exactly. Your idiomatic [section] TOML input is read correctly; the output looks like {key = value} for nested tables. This is a deliberate trade-off for round-trip fidelity (see DR-006 in the spec).

JSON → YAML (--output-format=yaml)

Cross-format transcoding: read JSON, write YAML.

Input (input.json):

{"name":"alice","version":1}

File mode (no --- prefix for single-document output):

nesdit input.json --output-format yaml

Stdout:

name: alice
version: 1

STDIN stream mode (adds --- prefix):

nesdit --format json --output-format yaml < input.json

Stdout:

---
name: alice
version: 1

Warning

Running --check on a cross-format invocation with an identity query always exits 2 — even when nothing changed semantically — because the two serializations are never byte-identical: 

nesdit input.json --check --output-format yaml --query '.'
# exits 2

YAML → JSON (--output-format=json)

Input (input.yaml):

name: alice
version: 1

File mode:

nesdit input.yaml --output-format json

Stdout:

{"name":"alice","version":1}

Key order is preserved: name precedes version in the input and in the output.

YAML → TOML (--output-format=toml)

Input (input.yaml):

name: alice
version: 1

nesdit input.yaml --output-format toml

Stdout:

name = "alice"
version = 1

JSON → TOML (--output-format=toml)

Input (input.json):

{"name":"alice","version":1}

nesdit input.json --output-format toml

Stdout:

name = "alice"
version = 1

Multi-document stream → TOML

When the input stream contains more than one document, TOML output documents are separated by +++ (Hugo-style multi-document TOML convention; not part of the TOML specification):

printf '{"a":1}\n{"b":2}\n' | nesdit --format jsonl --output-format toml

Stdout:

a = 1
+++
b = 2

TOML → YAML (--output-format=yaml)

Input (input.toml):

name = "alice"
version = 1

File mode:

nesdit input.toml --output-format yaml

Stdout:

name: alice
version: 1

--output-format conflict with -i

--output-format and -i are mutually exclusive. Writing a different format back into the same file would silently corrupt it:

nesdit -i values.json --output-format yaml --query '.'

nesdit: error: flag.conflict: --output-format and -i are mutually exclusive: --output-format with -i would write a different format into the same file; use a separate output path

Use redirection instead:

nesdit values.json --output-format yaml --query '.' > values.yaml