YQ(1)

📦 version 4.53.3, in ubuntu stonking

💖 YQ 💖

okay so bestie, this is yq(1) — from the User Commands crew — and it's about to become your entire personality. no fr, this one's a keeper.

✨ NAME ✨

yq — the portable command-line processor for YAML, JSON, XML, CSV, TOML, HCL and properties files. one tool, all the formats, main character energy 💅

🌸 DESCRIPTION 🌸

yq is a portable command-line data file processor — you can find it over at https://github.com/mikefarah/yq/ 🫶

for all the detailed documentation and examples your little heart desires, go look at https://mikefarah.gitbook.io/yq/ ✨

🦋 Usage 🦋

yq [flags] yq [command]

💜 EXAMPLES 💜

okay so first thing you gotta know: yq tries to auto-detect the file format based off the extension, and it defaults to YAML if that extension is unknown (or if you're piping through STDIN, iykyk). and if auto-detect isn't giving, you can always specify a format type yourself with the -p/--input-format flag. 🎀

cat file.xml | yq -p xml

reading the "stuff" node out of "myfile.yml"? literally one line bestie:

yq '.stuff' < myfile.yml

updating myfile.yml in place (yes, in place, be careful, no take-backs):

yq -i '.stuff = "foo"' myfile.yml

and printing the contents of sample.json as idiomatic YAML? slay:

yq -P -oy sample.json

🌈 Available Commands 🌈

  • completion — generate the autocompletion script for the specified shell. go set it up, your future self says thank you ✨
  • eval — the default one. applies the expression to each document in each yaml file, in sequence. one at a time, no rushing 💅
  • eval-all — loads all the yaml documents of all the yaml files and runs the expression once. the whole group chat at once, periodt 🫶
  • help — help about any command. it's giving supportive bestie 😭

🎀 Flags 🎀

  • -C, --colors — force print with colors 🎨
  • --csv-auto-parse — parse CSV YAML/JSON values (default true)
  • --csv-separator char — CSV Separator character (default ,)
  • --debug-node-info — debug node info 🐛
  • -e, --exit-status — set exit status if there are no matches or null or false is returned
  • --expression string — forcibly set the expression argument. super useful when yq's argument detection thinks your expression is a file 🙈
  • --from-file string — Load expression from specified file.
  • -f, --front-matter string — (extract|process) first input as yaml front-matter. Extract will pull out the yaml content, process will run the expression against the yaml content, leaving the remaining data intact ✨
  • --header-preprocess — Slurp any header comments and separators before processing expression. (default true)
  • -h, --help — help for yq 🫶
  • -I, --indent int — sets indent level for output (default 2)
  • --ini-preserve-quotes — preserve surrounding quotes on INI values during round-trip
  • -i, --inplace — update the file in place of first file given. ⚠️ this one edits your actual file, no cap, so maybe keep a backup bestie
  • -p, --input-format string — parse format for input, one of [auto|a|yaml|y|kyaml|ky|json|j|props|p|csv|c|tsv|t|xml|x|base64|uri|toml|hcl|h|lua|l|ini|i] (default "auto")
  • --lua-globals — output keys as top-level global variables
  • --lua-prefix string — prefix (default "return ")
  • --lua-suffix string — suffix (default ";\n")
  • --lua-unquoted — output unquoted string keys (e.g. {foo="bar"})
  • -M, --no-colors — force print with no colors 🚫🎨
  • -N, --no-doc — Don't print document separators (---)
  • -0, --nul-output — Use NUL char to separate values. If unwrap scalar is also set, fail if unwrapped scalar contains NUL char.
  • -n, --null-input — Don't read input, simply evaluate the expression given. Useful for creating docs from scratch 🌱
  • -o, --output-format string — output format type, one of [auto|a|yaml|y|kyaml|ky|json|j|props|p|csv|c|tsv|t|xml|x|base64|uri|toml|hcl|h|shell|s|lua|l|ini|i] (default "auto")
  • -P, --prettyPrint — pretty print, shorthand for '... style = ""' 💅
  • --properties-array-brackets — use [x] in array paths (e.g. for SpringBoot)
  • --properties-separator string — separator to use between keys and values (default " = ")
  • --security-disable-env-ops — Disable env related operations.
  • --security-disable-file-ops — Disable file related operations (e.g. load)
  • --security-enable-system-operator — Enable system operator to allow execution of external commands. 👀
  • --shell-key-separator string — separator for shell variable key paths (default "_")
  • -s, --split-exp string — print each result (or doc) into a file named (exp). The [exp] argument must return a string. You can use $index in the expression as the result counter. The necessary directories will be created. 🗂️
  • --split-exp-file string — Use a file to specify the split-exp expression.
  • --string-interpolation — Toggles strings interpolation of \(exp) (default true)
  • --tsv-auto-parse — parse TSV YAML/JSON values (default true)
  • -r, --unwrapScalar — unwrap scalar, print the value with no quotes, colours or comments. Defaults to true for yaml (default true)
  • -v, --verbose — verbose mode 🗣️
  • -V, --version — Print version information and quit
  • --xml-attribute-prefix string — prefix for xml attributes (default "+@")
  • --xml-content-name string — name for xml content (if no attribute name is present). (default "+content")
  • --xml-directive-name string — name for xml directives (e.g. <!DOCTYPE thing cat>) (default "+directive")
  • --xml-keep-namespace — enables keeping namespace after parsing attributes (default true)
  • --xml-proc-inst-prefix string — prefix for xml processing instructions (e.g. <?xml version="1"?>) (default "+p_")
  • --xml-raw-token — enables using RawToken method instead Token. Commonly disables namespace translations. See https://pkg.go.dev/encoding/xml#Decoder.RawToken for details. (default true)
  • --xml-skip-directives — skip over directives (e.g. <!DOCTYPE thing cat>)
  • --xml-skip-proc-inst — skip over process instructions (e.g. <?xml version="1"?>)
  • --xml-strict-mode — enables strict parsing of XML. See https://pkg.go.dev/encoding/xml for more details.
  • -c, --yaml-compact-seq-indent — Use compact sequence indentation where '- ' is considered part of the indentation.
  • --yaml-fix-merge-anchor-to-spec — Fix merge anchor to match YAML spec. Will default to true in late 2025 🔮
and if you get lost (you won't, you got this), just run yq [command] --help for more information about a command 🫶

💫 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. go get that lore bestie 📖✨

that's the whole vibe 💖 this page comes to you from https://github.com/mikefarah/y..., dated August 2026, and it lives in section YQ(1). go forth and process all the formats, you absolute icon 👑🦋💅

📦 where this page comes from