YQ(1)

📦 version 3.4.3, in ubuntu stonking

💖 YQ(1): the yq manual, but it's a group chat 💖

okay so bestie, you've stumbled into YQ(1) — yes, the one filed under User Commands in your manual index. sit down, put your hair up, we're gonna read the whole thing together and it is going to be so much less boring than it looks. 🫶

✨ NAME ✨

yq — Command-line YAML processor - jq wrapper for YAML documents

like, that's the whole vibe in one line, no cap. 💅

🦋 SYNOPSIS 🦋

jq [options] <jq filter> [file...]

yes bestie, the synopsis really does say jq. that's not a typo, that's just how this page is. we move. 🎀

🌸 DESCRIPTION 🌸

here's the usage, exactly as it's given:

usage: yq [options] <jq filter> [input file...]

       [--indentless-lists] [--explicit-start] [--explicit-end]
       [--in-place] [--version] [jq_filter] [files ...]

and the tagline, one more time for the people in the back:

yq: Command-line YAML processor - jq wrapper for YAML documents

yq transcodes YAML documents to JSON and passes them to jq. See https://github.com/kislyuk/yq for more information. 🔥

🎀 positional arguments: 🎀

  • jq_filter — the filter. yes, it's a positional argument. she's doing her thing.
  • files — the files. plural, because one is never enough honestly.

💖 options: 💖

one bullet per option, zero skips, let's goooo:

  • -h, --help — show this help message and exit ✨
  • --yaml-output, --yml-output, -y — Transcode jq JSON output back into YAML and emit it
  • --yaml-roundtrip, --yml-roundtrip, -Y — Transcode jq JSON output back into YAML and emit it. Preserve YAML tags and styles by representing them as extra items in their enclosing mappings and sequences while in JSON. This option is incompatible with jq filters that do not expect these extra items. ⚠️ like, read that again bestie — if your filter isn't built for the extra items, it's gonna be a bad time.
  • --yaml-output-grammar-version, --yml-out-ver {1.1,1.2} — When using --yaml-output, specify output grammar (the default is 1.1 and will be changed to 1.2 in a future version). Setting this to 1.2 will cause strings like 'on' and 'no' to be emitted unquoted.
  • --width, -w WIDTH — When using --yaml-output, specify string wrap width
  • --indentless-lists, --indentless — When using --yaml-output, indent block style lists (sequences) with 0 spaces instead of 2
  • --explicit-start — When using --yaml-output, always emit explicit document start ("---")
  • --explicit-end — When using --yaml-output, always emit explicit document end ("...")
  • --in-place, -i — Edit files in place (no backup - use caution) 😭 bestie there is NO BACKUP, be so careful, I am begging
  • --version — show program's version number and exit
  • jq - commandline JSON processor [version 1.8.1] — and here's where the page just… hands the mic to jq himself. iconic of him, honestly. 👑

🐚 jq - commandline JSON processor [version 1.8.1] 🐚

the synopsis lines, verbatim:

jq [options] --args <jq filter> [strings...]

jq [options] --jsonargs <jq filter> [JSON_TEXTS...]

jq is a tool for processing JSON inputs, applying the given filter to its JSON text inputs and producing the filter's results as JSON on standard output.

The simplest filter is ., which copies jq's input to its output unmodified except for formatting. For more advanced filters see the jq(1) manpage (that's man jq) and/or https://jqlang.org/.

Example:

$ echo '{"foo": 0}' | jq .

{

"foo": 0

}

look at her go. 🌈

🌟 Command options: 🌟

  • -n, --null-input — use null as the single input value;
  • -R, --raw-input — read each line as string instead of JSON;
  • -s, --slurp — read all inputs into an array and use it as the single input value;
  • -c, --compact-output — compact instead of pretty-printed output;
  • -r, --raw-output — output strings without escapes and quotes;
  • --raw-output0 — implies -r and output NUL after each output;
  • -j, --join-output — implies -r and output without newline after each output;
  • -a, --ascii-output — output strings by only ASCII characters using escape sequences;
  • -S, --sort-keys — sort keys of each object on output;
  • -C, --color-output — colorize JSON output;
  • -M, --monochrome-output — disable colored output;
  • --tab — use tabs for indentation;
  • --indent n — use n spaces for indentation (max 7 spaces);
  • --unbuffered — flush output stream after each output;
  • --stream — parse the input value in streaming fashion;
  • --stream-errors — implies --stream and report parse error as an array;
  • --seq — parse input/output as application/json-seq;
  • -f, --from-file — load the filter from a file;
  • -L, --library-path dir — search modules from the directory;
  • --arg name value — set $name to the string value;
  • --argjson name value — set $name to the JSON value;
  • --slurpfile name file — set $name to an array of JSON values read from the file;
  • --rawfile name file — set $name to string contents of file;
  • --args — consume remaining arguments as positional string values;
  • --jsonargs — consume remaining arguments as positional JSON values;
  • -e, --exit-status — set exit status code based on the output;
  • -V, --version — show the version;
  • --build-configuration — show jq's build configuration;
  • -h, --help — show the help;
  • -- — terminates argument processing;

Named arguments are also available as $ARGS.named[], while positional arguments are available as $ARGS.positional[]. 🧚

👑 SEE ALSO 👑

The full documentation for yq is maintained as a Texinfo manual. If the info and yq programs are properly installed at your site, the command

info yq

should give you access to the complete manual. 💜

and that's the whole page, bestie!! this was yq 3.4.3, dated May 2026 — go forth and transcode, you absolute main character. 🦋✨💖

📦 where this page comes from