FY-TOOL(1)

📦
version 0.9.6 · 2 versions
, in arch rolling, nixpkgs unstable

💅 FY-TOOL(1) — the libfyaml girlies' guide

okay so first things first: this is the FY-TOOL(1) page from libfyaml, and it's literally the whole tour of the command-line front-end. buckle up bestie 🎀

✨ NAME ✨

fy-tool — the docs for fy-tool, periodt. yes that's the whole name section, it's giving minimalism 💅

🌸 SYNOPSIS 🌸

fy-tool [OPTIONS] [<file> …]

fy-dump [OPTIONS] [<file> …]

fy-testsuite [OPTIONS] <file>

fy-filter [OPTIONS] [-f FILE] [<path> …]

fy-join [OPTIONS] [-T PATH] [-F PATH] [-t PATH] [<file> …]

fy-ypath [OPTIONS] <ypath-expression> [<file> …]

fy-compose [OPTIONS] [<file> …]

fy-b3sum [OPTIONS] [<file> …]

seven whole personalities, and honestly? all of them slay 🦋

💖 DESCRIPTION 💖

fy-tool is the libfyaml command-line front-end, and it's out here doing the absolute most: parsing, rewriting, querying, joining, testing and hashing YAML and JSON data. main character energy fr 🔥

the executable switches up its behaviour one of two ways:

  • by the invoked program name — fy-dump, fy-testsuite, fy-filter, fy-join, fy-ypath, fy-compose, fy-b3sum
  • by an explicit mode-select option, like --dump or --filter

and the default mode? that's dump. no cap 💜

🌈 OPTIONS 🌈

🫶 General options

  • -h, --help — shows the built-in help message.
  • -v, --version — prints the libfyaml version.
  • -q, --quiet — mutes informational output and non-fatal diagnostic output. quiet queen behaviour 🙈
  • -d LEVEL, --debug-level LEVEL — sets the minimum diagnostic severity the library will emit. default is 3 (warning level).
  • -C MODE, --color MODE — controls ANSI color output. values: on, off, auto. default is auto.
  • -V, --visible — makes spaces, tabs and line breaks actually visible in text output. see the invisible, iconic ✨
  • --dry-run — parses the input but suppresses normal output generation. all vibes, no output 💀

🔍 Diagnostic options

  • --disable-diag MODULE — turns off diagnostic output for the named module.
  • --enable-diag MODULE — turns on diagnostic output for the named module.
  • --show-diag OPTION — shows the named diagnostic field. values: source, position, type, module.
  • --hide-diag OPTION — hides the named diagnostic field.

🧚 Parser options

  • -I DIR, --include DIR — adds DIR to the input include search path.
  • -j MODE, --json MODE — picks the JSON input handling. values: no, force, auto. default is auto.
  • -r, --resolve — resolves anchors and merge keys while parsing. lowkey a lifesaver 🫶
  • --yaml-1.1 — forces YAML 1.1 rules when the input doesn't declare a version.
  • --yaml-1.2 — forces YAML 1.2 rules when the input doesn't declare a version.
  • --yaml-1.3 — forces YAML 1.3 rules when the input doesn't declare a version.
  • -l, --follow — follows aliases during path traversal and related path-based operations.
  • --sloppy-flow-indentation — accepts relaxed indentation rules in flow mode. we love a chill parser 🍓
  • --prefer-recursive — prefers recursive algorithms over iterative ones.
  • --ypath-aliases — enables alias processing for ypath evaluation.
  • --allow-duplicate-keys — allows duplicate mapping keys.
  • --collect-errors — collects multiple parsing errors before reporting failure. efficient 💅
  • --disable-accel — disables parser/emitter acceleration features.
  • --disable-buffering — disables stdio buffering and uses direct file-descriptor reads.
  • --disable-mmap — disables memory-mapped input.
  • --disable-depth-limit — disables the normal nesting-depth limit. deep nesting girlies, be free 🦋

🎀 Emitter options

  • -i INDENT, --indent INDENT — sets the output indentation width. default is 2.
  • -w WIDTH, --width WIDTH — sets the preferred output width. use inf for no width limit. default is 80.
  • -m MODE, --mode MODE — selects the output style. values: original, block, flow, flow-oneline, json, json-tp, json-oneline, dejson, pretty, flow-compact, json-compact. the buffet of aesthetics 😭
  • -s, --sort — sorts mapping keys before emitting output.
  • -c, --comment — preserves and emits comments where supported. protect the commentary 👑
  • --strip-labels — strips anchors and aliases from emitted output.
  • --strip-tags — strips emitted tags.
  • --strip-doc — strips document start and end markers.
  • --strip-empty-kv — omits keys whose values are empty or null.
  • --null-output — suppresses normal output generation.
  • --no-ending-newline — doesn't append a final trailing newline.
  • --preserve-flow-layout — preserves single-line flow collection layout when possible.
  • --indented-seq-in-map — indents block sequences that appear inside block mappings.
  • --streaming — uses streaming output mode. this is the default.
  • --no-streaming — disables streaming output mode.
  • --recreating — recreates streaming events instead of passing them through directly.

💀 Testsuite options

  • --disable-flow-markers — omits testsuite flow markers.
  • --disable-doc-markers — omits testsuite document markers.
  • --disable-scalar-styles — omits testsuite scalar-style markers.
  • --document-event-stream — builds a document first and then generates the event stream from it.
  • --tsv-format — emits testsuite output in TSV format.

🍓 Input options

  • -f FILE, --file FILE — reads from FILE instead of standard input, wherever the selected mode uses a single input source. and plot twist: if FILE begins with >, the remaining text is treated as literal input content 🫶

🧵 Join options

  • -T PATH, --to PATH — joins into PATH. default is /.
  • -F PATH, --from PATH — takes joined input from PATH. default is /.
  • -t PATH, --trim PATH — emits only PATH from the joined result. default is /.

🔮 YPATH options

  • -F PATH, --from PATH — starts evaluation from PATH. default is /.
  • --dump-pathexpr — dumps the parsed path expression before evaluation.
  • --noexec — parses the expression but doesn't execute it.

🧚‍♀️ Compose options

  • --dump-path — dumps the path while composing a document.

⭐ B3SUM options

  • --b3sum — enables BLAKE3 hashing mode.
  • --derive-key CONTEXT — uses key-derivation mode with CONTEXT.
  • --no-names — omits file names from checksum output.
  • --raw — emits raw digest bytes.
  • --length N — emits only N output bytes, up to the BLAKE3 maximum.
  • --check — verifies checksums read from input files.
  • --keyed — uses keyed hashing, reading the secret key from standard input. 🤫
  • --backend BACKEND — selects the BLAKE3 backend implementation.
  • --list-backends — lists the available BLAKE3 backends.
  • --num-threads N — sets the worker-thread count. 0 means automatic selection, and -1 disables threaded hashing.
  • --file-buffer N — sets the per-file I/O buffer size.
  • --mmap-min-chunk N — sets the minimum chunk size used for memory-mapped hashing input.
  • --mmap-max-chunk N — sets the maximum chunk size used for memory-mapped hashing input.

👑 Modes

  • --dump — selects dump mode. this is the default, and it's also the mode used by fy-dump.
  • --testsuite — selects testsuite mode. also the mode used by fy-testsuite.
  • --filter — selects filter mode. also the mode used by fy-filter.
  • --join — selects join mode. also the mode used by fy-join.
  • --ypath — selects ypath query mode. also the mode used by fy-ypath.
  • --scan-dump — selects the internal scan-dump mode.
  • --parse-dump — selects the internal parse-dump mode.
  • --compose — selects composer-driver dump mode. also the mode used by fy-compose.
  • --yaml-version-dump — prints YAML version information.

🦋 EXAMPLES 🦋

dump a YAML file back out using the default emitter mode:

$ fy-dump invoice.yaml

resolve anchors and strip labels from the result:

$ fy-dump -r --strip-labels simple-anchors.yaml

read literal input text via --file:

$ fy-filter --file ">foo: bar" /

select data from a file using a path expression:

$ fy-filter --file simple-anchors.yaml /baz/bar

join two root mappings into a single document:

$ fy-join simple-anchors.yaml invoice.yaml

generate testsuite event output:

$ fy-testsuite invoice.yaml

list available BLAKE3 backends:

$ fy-b3sum --list-backends

every single one of these? ate. 🔥

💜 AUTHOR 💜

Pantelis Antoniou <pantelis.antoniou@konsulko.com> — the icon behind it all 👑

🙈 BUGS 🙈 (known Ls, not gonna lie)

  • the only supported input and output character encoding is UTF8. that's it, that's the whole encoding buffet 💀
  • sorting does not respect language settings. sorry locale girlies 😭
  • there is no way for the user to specify a different coloring scheme. we get the colors we get 🎨

🌸 SEE ALSO 🌸

  • libfyaml(3) — go read the main character's page too 🫶

2019-2026, Pantelis Antoniou

and that's the whole page bestie — written by the libfyaml girlies, version-and-date stamp Mar 15, 2026, FY-TOOL(1) forever 💅✨ no cap, see you in the group chat 🦋

📦 where this page comes from