yq builtin#

Bashkit ships a yq structured-data processor for the command shape agents commonly use with mikefarah/yq. It parses YAML or JSON, evaluates the existing jq/jaq expression engine, then emits YAML or JSON. Bashkit deliberately does not maintain a second YAML-specific query language.

Enable the Cargo jq feature to register both jq and yq.

Examples#

yq '.server.port' config.yml
yq '.items[] | select(.enabled) | .name' config.yml
yq '.values | map(. * 2)' config.yml
yq -o=json -I=0 '.' config.yml
yq -p=json -o=yaml '.' data.json
yq -i '.server.port = 8080' config.yml

With no expression, . is used. Input comes from the listed VFS files or stdin. YAML streams containing --- are processed one document at a time; -s presents all input documents to the filter as one array. The optional e / eval subcommand alias is accepted for common generated invocations.

Flags#

Flag	Behaviour
-p, --input-format	auto, yaml, or json
-o, --output-format	yaml or json
-r, --raw-output	Unwrap string results
-c, --compact-output	Compact JSON output
-e, --exit-status	Nonzero for no output, null, or false
-s, --slurp	Read all documents into an array
-n, --null-input	Evaluate once with null input
-i, --inplace	Atomically replace exactly one input file
-I, --indent	Set JSON indentation; 0 is compact
-N, --no-doc	Omit separators between YAML results
--expression	Force an otherwise ambiguous argument to be the expression

Short boolean flags combine (-rce, -sn). Attached value forms such as -o=json, -p=json, and -I=0 are accepted.

In-place evaluation and serialization finish before a sibling temporary file is written and renamed over the source. A parse, filter, output-limit, write, or rename failure leaves the source unchanged.

Compatibility boundary#

The expression language is jq, not mikefarah/yq’s node/style language. Common selection, iteration, select, map, construction, reduction, and assignment filters work. mikefarah/yq-only operators for comments, styles, anchors, tags, file metadata, and cross-file evaluation are not implemented.

YAML custom tags and non-string mapping keys are rejected rather than silently losing information. Mapping keys are sorted deterministically at the JSON-value boundary. Comments, scalar style, and anchors are not retained after conversion. The parser follows YAML 1.1. TOML, CSV, and XML conversion are not part of this builtin; Bashkit’s separate tomlq and csv helpers remain available for their existing narrow command surfaces.

See also#

• jq_guide — the shared expression engine and its jq compatibility notes.
• threat_model — structured-input resource and information-disclosure controls.