jq builtin

Bashkit ships an embedded jq JSON processor backed by jaq with a thin compatibility shim layered on top. This guide documents which jq features are supported so callers (and LLM agents that generate jq filters against bashkit) can avoid surprises.

Reported version

jq --version prints jq-1.8. Filters generated for stedfan/jq 1.7 and 1.8 are the intended target.

Command-line flags

Implemented:

Flag	Description
`-r`, `--raw-output`	Strings are written without quotes
`-R`, `--raw-input`	Each line of input becomes a JSON string
`-s`, `--slurp`	Read every input value into one array
`-n`, `--null-input`	Use `null` as the (single) input value
`-c`, `--compact-output`	One JSON value per line, no pretty-printing
`-S`, `--sort-keys`	Sort object keys recursively
`-e`, `--exit-status`	Set exit code based on the output
`-j`	Like `-r` but suppresses trailing newlines
`--tab`	Use tabs for indentation
`--arg name value`	Bind `$name` to a string
`--argjson name json`	Bind `$name` to a parsed JSON value
`-V`, `--version`	Print the version
`-h`, `--help`	Print help
Combined flags like `-snr`	Treated as the union of the individual flags

Variables

Variable	Behaviour
`$ENV`	Bound to the shell environment as an object — same map as the `env` filter. (#1486)
`$name`	Variables defined with `--arg` / `--argjson` are passed through.

Notable filters

The full jq stdlib is mostly available via jaq-std. The compatibility shim adds or overrides:

Filter	Notes
`env`	Reads from the shell env map (not the host process env), avoiding the unsafe `std::env::set_var` path.
`setpath(p; v)`	Bashkit ships a recursive definition because jaq’s stdlib doesn’t expose one.
`leaf_paths`	Defined as `paths(scalars)` since jaq’s stdlib lacks it.
`match(re; flags)` / `match(re)`	Overridden to add `"name": null` to unnamed captures, matching jq output.
`scan(re; flags)` / `scan(re)`	Overridden so `scan` defaults to global (“g”) matching, matching jq.
`input_filename`	Stub returning `null` (#1486). Bashkit reads inputs as a single concatenated stream via shell redirection, so per-input filenames are not tracked.
`input_line_number`	Stub returning `0` (#1486). Per-line input tracking is not implemented.
`input` / `inputs`	Real jaq implementations — pull from the shared input iterator.
Most other 1.7/1.8 stdlib filters	Forwarded from `jaq-std` (`getpath`, `paths`, `to_entries`, `group_by`, `ltrimstr`/`rtrimstr`, `splits`, `test`, `now`, `debug`, `limit`, etc.).

Errors

Filter parse failures and runtime errors return exit code 3 and 5 respectively, matching jq. Long error operands are summarised so failures do not blow up an LLM context window — see #1485.

Known gaps

Bashkit’s jq is intentionally minimal in places where the host model differs from upstream jq:

File inputs are concatenated into a single stream by the shell, so per-file metadata (input_filename, input_line_number) is stubbed.
Exotic numeric formatting modes (@base32, @base64d, etc.) follow whatever jaq-json ships.

If you hit a missing builtin, please open an issue with the failing filter.