#cli #jq #c #yaml #yq

app whyq

yet another jq wrapper

7 releases (4 breaking)

0.8.2 Sep 19, 2023
0.8.1 Sep 18, 2023
0.7.1 Sep 18, 2023
0.6.0 Sep 17, 2023
0.4.0 Sep 7, 2023

#511 in Parser implementations

Download history 37/week @ 2023-09-06 105/week @ 2023-09-13 21/week @ 2023-09-20

163 downloads per month


249 lines

whyq - low overhead yq implementation

CI Crates.io

A lightweight and portable jq wrapper for doing arbitrary queries from YAML/TOML/JSON documents by converting to JSON and passing to jq, then returning the result either as raw jq output, or back into TOML or YAML.


Via cargo:

cargo install whyq

or download a prebuilt from releases either manually, or via binstall:

cargo binstall whyq

Note: Depends on jq being installed.

Why / Why Not

jq compatibility

  • arbitrary jq usage on any input format (yaml/toml/json)
  • same filter syntax (shells out to jq)
  • matches jq's cli interface (only some extra input/output format controlling flags)
  • supports jq output formatters such as -c, -r, and -j (compact, raw, joined output resp)
  • supports jq modules on all input formats


  • reads multidoc yaml input, handles yaml merge keys (expanding tags)
  • reads from stdin xor file (file if last arg is a file)
  • output conversion shortcuts: -y (YAML) or -t (TOML)
  • drop-in replacement to python-yq (provides: yq)
  • ~1MB in binary size (for small cloud CI images / binstalled ci actions)



YAML Input

Use as jq either via stdin:

$ yq '.[3].kind' -r < test/deploy.yaml

$ yq -y '.[3].metadata' < test/deploy.yaml
  app: controller
name: controller
namespace: default

or from a file arg (at the end):

$ yq '.[3].kind' -r test/deploy.yaml
$ yq -y '.[3].metadata' test/deploy.yaml

The default input format is YAML and is what the binary is named for (and the most common primary usage case).

TOML Input

Using say Cargo.toml from this repo as input, and aliasing tq='yq --input=toml':

$ tq '.package.categories[]' -r < Cargo.toml

$ tq -t '.package.metadata' < Cargo.toml
bin-dir = "yq-{ target }/{ bin }{ format }"
pkg-url = "{ repo }/releases/download/{ version }/yq-{ target }{ archive-suffix }"

$ tq -y '.dependencies.clap' < Cargo.toml
- cargo
- derive
version: 4.4.2

$ tq '.profile' -c < Cargo.toml

Add alias tq='yq --input=toml' to your .bashrc or .zshrc (etc) to make this permanent if you find it useful.

JSON Input

If you need to convert json to another format you pass --input=json:

$ yq --input=json '.ingredients | keys' -y < test/guacamole.json                                                                          ☸ production-eu-west-1󰛢monitoring
- avocado
- coriander
- cumin
- garlic
- lime
- onions
- pepper
- salt
- tomatoes

Advanced Examples

Select with nested query and raw output:

$ yq '.spec.template.spec.containers[].image' -r < test/grafana.yaml

Select on multidoc:

$ yq -y '.[] | select(.kind == "Deployment") | .spec.template.spec.containers[0].ports[0].containerPort' test/deploy.yaml

Escaping keys with slashes etc in them:

yq -y '.updates[] | select(.["package-ecosystem"] == "cargo") | .groups' .github/dependabot.yml

Using helpers from jq modules e.g. k.jq:

$ yq 'include "k"; .[] | gvk' -r -L$PWD/test/modules < test/deploy.yaml

Output Caveats

Output formatting such as -y for YAML or -t for TOML will require the output from jq to be parseable json. If you pass on -r,-c or -c for raw/compact output, then this will generally not be parseable as json.

Debug Logs

The project respects RUST_LOG when set, and sends these diagnostic logs to stderr:

$ RUST_LOG=debug yq '.version' test/circle.yml
2023-09-18T23:17:04.533055Z DEBUG yq: args: Args { input: Yaml, output: Jq, yaml_output: false, toml_output: false, in_place: false, jq_query: ".version", file: Some("test/circle.yml"), compact_output: false, raw_output: false, join_output: false, modules: None }
2023-09-18T23:17:04.533531Z DEBUG yq: found 1 documents
2023-09-18T23:17:04.533563Z DEBUG yq: input decoded as json: {"definitions":{"filters":{"on_every_commit":{"tags":{"only":"/.*/"}},"on_tag":{"branches":{"ignore":"/.*/"},"tags":{"only":"/v[0-9]+(\\.[0-9]+)*/"}}},"steps":[{"step":{"command":"chmod a+w . && cargo build --release","name":"Build binary"}},{"step":{"command":"rustc --version; cargo --version; rustup --version","name":"Version information"}}]},"jobs":{"build":{"docker":[{"image":"clux/muslrust:stable"}],"environment":{"IMAGE_NAME":"whyq"},"resource_class":"xlarge","steps":["checkout",{"run":{"command":"rustc --version; cargo --version; rustup --version","name":"Version information"}},{"run":{"command":"chmod a+w . && cargo build --release","name":"Build binary"}},{"run":"echo versions"}]},"release":{"docker":[{"image":"clux/muslrust:stable"}],"resource_class":"xlarge","steps":["checkout",{"run":{"command":"rustc --version; cargo --version; rustup --version","name":"Version information"}},{"run":{"command":"chmod a+w . && cargo build --release","name":"Build binary"}},{"upload":{"arch":"x86_64-unknown-linux-musl","binary_name":"${IMAGE_NAME}","source":"target/x86_64-unknown-linux-musl/release/${IMAGE_NAME}","version":"${CIRCLE_TAG}"}}]}},"version":2.1,"workflows":{"my_flow":{"jobs":[{"build":{"filters":{"tags":{"only":"/.*/"}}}},{"release":{"filters":{"branches":{"ignore":"/.*/"},"tags":{"only":"/v[0-9]+(\\.[0-9]+)*/"}}}}]},"version":2}}
2023-09-18T23:17:04.533650Z DEBUG yq: jq args: [".version"]
2023-09-18T23:17:04.538606Z DEBUG yq: jq stdout: 2.1



~180K SLoC