Output & metadata

The same query can return a value, JSON, YAML, a node type, its expanded tag, or its source line.

Default value output#

Scalar nodes print decoded text:

ysh '.server.host' config.yml
# localhost

Mappings and sequences emit compact JSON because a collection cannot be represented safely as one unquoted shell value.

ysh '.server.ports' config.yml
# [8080,8443]

Expressions may return more than one node. Each scalar or compact JSON collection is written on its own line:

ysh '.services[] | select(.enabled) | .name' config.yml
# api
# web

JSON#

Use --json, -o=json, or --output-format=json:

ysh -o=json '.service' config.yml

Recognized nulls, booleans, integers, and finite floats become native JSON values. Strings, timestamps, and application-tagged scalars are JSON strings. Non-finite YAML floats are quoted because JSON has no equivalent value.

YAML#

Use -y, -o=yaml, or --output-format=yaml to serialize selected or transformed nodes:

ysh -o=yaml '.release.channel = "stable"' config.yml

Multiple results are separated with ---, producing a valid YAML stream. Anchors, aliases, tags, and merge edges are emitted when they still exist in the selected graph.

Set YAML indentation from one through nine spaces with -I N or --indent=N. Use --unwrap-scalar=false when default value output should retain a scalar's YAML quoting, tag, and line comment.

The emitter is semantic. It uses a stable layout while retaining recorded line comments and supported scalar/collection styles. Blank lines, spacing, head/foot comments, directive spelling, and exact scalar formatting are not reconstructed.

Version 1.9 keeps the rich -i presentation layer. Common replacements, direct block inserts/deletes, presentation-property edits, and pure sequence reorders patch the original source. Other structural changes use the semantic emitter.

With several inputs, every candidate is built before the first replacement. Preserved siblings allow rollback if a later commit fails or the process is interrupted. Permission bits survive, and symlinks are refused.

Type#

ysh --type '.release.date' config.yml
# timestamp

Possible reports are:

Type recognition never changes the default text returned for a scalar.

Tag#

ysh --tag '.widget' config.yml
# tag:example.com,2026:widget

Standard !! tags and handles declared with %TAG are expanded. Application constructors are not executed.

Source line#

ysh --line '.server.host' config.yml
# 3

For an alias selection, the reported line is the alias occurrence. Type, tag, and value output resolve through the alias target.

Computed expression values such as comparison results, length, keys, kind, and literals have source line zero because they do not occur in the YAML stream.

AST#

--ast prints the node table and its edges:

ysh --ast config.yml

The output includes node IDs, kinds, scalar values and types, tags, anchors, alias targets, source lines, mapping keys, indexes, and merge markers.

Events#

--events prints a parser-style view:

ysh --events config.yml

This is useful while extending the parser or reducing an unexpected input to a minimal test case.

Explain an edit#

--explain leaves normal output on stdout and reports evaluation behavior on stderr:

ysh --explain -i '.image.tag = "stable"' deploy.yml

The report includes parsed/generated node counts, result and mutation counts, changed paths, and whether presentation was preserved or regenerated. Values are intentionally omitted.

Use --explain=json for JSON Lines, with one value-free audit record per input:

ysh --explain=json -i '.image.tag = "stable"' services/*.yml 2>changes.jsonl

Transaction reports are released only after every file commits. An aborted or rolled-back transaction emits an error and no audit records.