Skip to content

STDIN stream mode

When no file argument is given, nesdit reads from stdin and writes to stdout. This makes it a drop-in filter in shell pipelines.

--format is optional: nesdit auto-detects the input format by scanning the first bytes of the stream. JSON and JSONL are distinguished by whether the first non-whitespace byte opens an object/array (json) or whether the stream contains multiple top-level values separated by newlines (jsonl). YAML is detected by --- stream markers or YAML-specific syntax; TOML by key-value and section-header patterns. If detection is ambiguous or fails, pass --format explicitly.

# --format is optional when the content is unambiguous
echo '{"x": 1}' | nesdit --query '.x = 2'

# Use --format to be explicit or override detection
cat config.yaml | nesdit --format yaml --query '.version = 2'

Single-document STDIN

echo '{"x":1,"y":2}' | nesdit --format json --query '.x = 99'

Stdout:

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

# Multi-line JSON is handled correctly — no need for --format json when auto-detecting
printf '{\n  "x": 1,\n  "y": 2\n}\n' | nesdit --query '.x = 99'

Multi-document YAML stream

YAML documents separated by --- are each transformed independently:

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

Input (stream.yaml):

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

Stdout:

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

Key order is preserved per document (NFR-3): name appears before version in each output document because it appeared before version in each input document.

JSONL stream

JSON Lines (one JSON object per line) are also supported. Each line is treated as a separate document:

printf '{"id":1}\n{"id":2}\n{"id":3}\n' | nesdit --format jsonl --create-missing --query '.processed = true'

Stdout:

{"id":1,"processed":true}
{"id":2,"processed":true}
{"id":3,"processed":true}

--format jsonl explicitly selects JSON Lines mode. --format json also works and auto-detects the stream format from content.

TOML

TOML is single-document only on input. Piping a multi-document TOML input stream is an error:

cat multi.toml | nesdit --format toml --query '.'

nesdit: error: -: format.unsupported: TOML input contains multiple top-level documents; TOML is single-doc only

Multi-document TOML output

When the output format is toml and the input stream contains more than one document, nesdit separates each output document with +++ (a line containing only three plus signs). This follows the Hugo-style multi-document TOML convention and is not part of the TOML specification.

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

Stdout:

a = 1
+++
b = 2

A YAML multi-document stream can be transcoded the same way:

nesdit --format yaml --output-format toml < stream.yaml

--where: selective transform

Transform only documents matching a predicate; others pass through unchanged:

nesdit --format yaml --where '.env == "prod"' --query '.version = 99' < input.yaml

Input:

env: prod
version: 1
---
env: staging
version: 1
---
env: prod
version: 1

Stdout:

---
env: prod
version: 99
---
env: staging
version: 1
---
env: prod
version: 99

Skipped documents emit a warning on stderr:

nesdit: warn: -:2: where.skipped: document did not match --where predicate

--strict and --keep-going

With --strict (the default), processing halts at the first document error:

# Stream where doc 3 causes a query error — halts at doc 3.
nesdit --format yaml --query '.name | ascii_downcase' < stream.yaml

With --keep-going, errored documents are skipped and processing continues:

nesdit --format yaml --query '.name | ascii_downcase' --keep-going < stream.yaml

Stderr shows the per-document error:

nesdit: error: -:3: query.error: string required but got number

The run exits 1 if any document failed, even with --keep-going.

Cross-format transcoding on STDIN

cat input.json | nesdit --format json --output-format yaml

Input (input.json):

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

Stdout:

---
name: alice
version: 1

Note

In STDIN stream mode, nesdit adds --- separators between documents in YAML output. In file→stdout mode, single-document YAML output does not include a leading ---.

TOML pretty-print

Use --pretty to emit human-readable TOML output. Arrays with more than one element are expanded across multiple lines with 2-space indentation, and blank lines are inserted between top-level entries:

printf '{"name":"alice","tags":["go","toml"]}\n' | nesdit --format json --output-format toml --pretty

Stdout:

name = "alice"

tags = [
  "go",
  "toml",
]

--pretty is silently ignored for non-TOML output formats (JSON, YAML, JSONL). Compact TOML output (no --pretty) is unchanged from today's behaviour.

  • --format — override format detection for STDIN.
  • --where — filter documents by a jq predicate.
  • --strict / --keep-going — error policy for multi-document streams.
  • --output-format — transcode output to a different format.
  • --pretty — emit human-friendly TOML output (currently only affects TOML).