.\" Man page generated from reStructuredText
.\" by the Docutils 0.22.4 manpage writer.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "FY-TOOL" "1" "Mar 18, 2026" "1.0.0" "libfyaml"
.SH NAME
fy-tool \- fy-tool documentation 
.SH SYNOPSIS
.sp
\fBfy\-tool\fP [\fIOPTIONS\fP] [<\fIfile\fP> …]
.sp
\fBfy\-dump\fP [\fIOPTIONS\fP] [<\fIfile\fP> …]
.sp
\fBfy\-testsuite\fP [\fIOPTIONS\fP] <\fIfile\fP>
.sp
\fBfy\-filter\fP [\fIOPTIONS\fP] [\-f \fIFILE\fP] [<\fIpath\fP> …]
.sp
\fBfy\-join\fP [\fIOPTIONS\fP] [\-T \fIPATH\fP] [\-F \fIPATH\fP] [\-t \fIPATH\fP] [<\fIfile\fP> …]
.sp
\fBfy\-ypath\fP [\fIOPTIONS\fP] <\fIypath\-expression\fP> [<\fIfile\fP> …]
.sp
\fBfy\-compose\fP [\fIOPTIONS\fP] [<\fIfile\fP> …]
.sp
\fBfy\-b3sum\fP [\fIOPTIONS\fP] [<\fIfile\fP> …]
.SH DESCRIPTION
.sp
\fBfy\-tool\fP is the libfyaml command\-line front\-end for parsing,
rewriting, querying, joining, testing, reflecting on, and hashing YAML and
JSON data.
.sp
The executable changes behaviour either by the invoked program name
(\fBfy\-dump\fP, \fBfy\-testsuite\fP, \fBfy\-filter\fP, \fBfy\-join\fP, \fBfy\-ypath\fP,
\fBfy\-compose\fP, \fBfy\-b3sum\fP) or by an explicit mode\-select option such as
\fB\-\-dump\fP or \fB\-\-filter\fP\&.
.sp
The default mode is \fBdump\fP\&.
.SH OPTIONS
.sp
General options
.INDENT 0.0
.TP
.B \-h, \-\-help
Display the built\-in help message.
.UNINDENT
.INDENT 0.0
.TP
.B \-v, \-\-version
Display the libfyaml version.
.UNINDENT
.INDENT 0.0
.TP
.B \-q, \-\-quiet
Suppress informational and non\-fatal diagnostic output.
.UNINDENT
.INDENT 0.0
.TP
.B \-d LEVEL, \-\-debug\-level LEVEL
Set the minimum diagnostic severity emitted by the library. The default is
\fB3\fP (warning level).
.UNINDENT
.INDENT 0.0
.TP
.B \-C MODE, \-\-color MODE
Control ANSI color output. Supported values are \fBon\fP, \fBoff\fP, and
\fBauto\fP\&. The default is \fBauto\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-V, \-\-visible
Make spaces, tabs, and line breaks visible in text output.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-dry\-run
Parse the input but suppress normal output generation.
.UNINDENT
.sp
Diagnostic options
.INDENT 0.0
.TP
.B \-\-disable\-diag MODULE
Disable diagnostic output for the named module.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-enable\-diag MODULE
Enable diagnostic output for the named module.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-show\-diag OPTION
Show the named diagnostic field. Supported values are \fBsource\fP,
\fBposition\fP, \fBtype\fP, and \fBmodule\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-hide\-diag OPTION
Hide the named diagnostic field.
.UNINDENT
.sp
Parser options
.INDENT 0.0
.TP
.B \-I DIR, \-\-include DIR
Add \fBDIR\fP to the input include search path.
.UNINDENT
.INDENT 0.0
.TP
.B \-j MODE, \-\-json MODE
Select JSON input handling. Supported values are \fBno\fP, \fBforce\fP, and
\fBauto\fP\&. The default is \fBauto\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-r, \-\-resolve
Resolve anchors and merge keys while parsing.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-yaml\-1.1
Force YAML 1.1 rules when the input does not declare a version.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-yaml\-1.2
Force YAML 1.2 rules when the input does not declare a version.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-yaml\-1.3
Force YAML 1.3 rules when the input does not declare a version.
.UNINDENT
.INDENT 0.0
.TP
.B \-l, \-\-follow
Follow aliases during path traversal and related path\-based operations.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-sloppy\-flow\-indentation
Accept relaxed indentation rules in flow mode.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-prefer\-recursive
Prefer recursive algorithms over iterative ones.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-ypath\-aliases
Enable alias processing for ypath evaluation.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-allow\-duplicate\-keys
Allow duplicate mapping keys.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-collect\-errors
Collect multiple parsing errors before reporting failure.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-disable\-accel
Disable parser/emitter acceleration features.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-disable\-buffering
Disable stdio buffering and use direct file\-descriptor reads.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-disable\-mmap
Disable memory\-mapped input.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-disable\-depth\-limit
Disable the normal nesting\-depth limit.
.UNINDENT
.sp
Emitter options
.INDENT 0.0
.TP
.B \-i INDENT, \-\-indent INDENT
Set the output indentation width. The default is \fB2\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-w WIDTH, \-\-width WIDTH
Set the preferred output width. Use \fBinf\fP for no width limit. The default
is \fB80\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-m MODE, \-\-mode MODE
Select the output style. Supported values are \fBoriginal\fP, \fBblock\fP,
\fBflow\fP, \fBflow\-oneline\fP, \fBjson\fP, \fBjson\-tp\fP, \fBjson\-oneline\fP,
\fBdejson\fP, \fBpretty\fP, \fBflow\-compact\fP, and \fBjson\-compact\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-s, \-\-sort
Sort mapping keys before emitting output.
.UNINDENT
.INDENT 0.0
.TP
.B \-c, \-\-comment
Preserve and emit comments where supported.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-strip\-labels
Strip anchors and aliases from emitted output.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-strip\-tags
Strip emitted tags.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-strip\-doc
Strip document start and end markers.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-strip\-empty\-kv
Omit keys whose values are empty or null.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-null\-output
Suppress normal output generation.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-ending\-newline
Do not append a final trailing newline.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-preserve\-flow\-layout
Preserve single\-line flow collection layout when possible.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-indented\-seq\-in\-map
Indent block sequences that appear inside block mappings.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-streaming
Use streaming output mode. This is the default.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-streaming
Disable streaming output mode.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-recreating
Recreate streaming events instead of passing them through directly.
.UNINDENT
.sp
Testsuite options
.INDENT 0.0
.TP
.B \-\-disable\-flow\-markers
Omit testsuite flow markers.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-disable\-doc\-markers
Omit testsuite document markers.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-disable\-scalar\-styles
Omit testsuite scalar\-style markers.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-document\-event\-stream
Build a document first and then generate the event stream from it.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-tsv\-format
Emit testsuite output in TSV format.
.UNINDENT
.sp
Input options
.INDENT 0.0
.TP
.B \-f FILE, \-\-file FILE
Read from \fBFILE\fP instead of standard input where the selected mode uses a
single input source. If \fBFILE\fP begins with \fB>\fP, the remaining text is
treated as literal input content.
.UNINDENT
.sp
Join options
.INDENT 0.0
.TP
.B \-T PATH, \-\-to PATH
Join into \fBPATH\fP\&. The default is \fB/\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-F PATH, \-\-from PATH
Take joined input from \fBPATH\fP\&. The default is \fB/\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-t PATH, \-\-trim PATH
Emit only \fBPATH\fP from the joined result. The default is \fB/\fP\&.
.UNINDENT
.sp
YPATH options
.INDENT 0.0
.TP
.B \-F PATH, \-\-from PATH
Start evaluation from \fBPATH\fP\&. The default is \fB/\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-dump\-pathexpr
Dump the parsed path expression before evaluation.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-noexec
Parse the expression but do not execute it.
.UNINDENT
.sp
Compose options
.INDENT 0.0
.TP
.B \-\-dump\-path
Dump the path while composing a document.
.UNINDENT
.sp
B3SUM options
.INDENT 0.0
.TP
.B \-\-b3sum
Enable BLAKE3 hashing mode.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-derive\-key CONTEXT
Use key\-derivation mode with \fBCONTEXT\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-names
Omit file names from checksum output.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-raw
Emit raw digest bytes.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-length N
Emit only \fBN\fP output bytes, up to the BLAKE3 maximum.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-check
Verify checksums read from input files.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-keyed
Use keyed hashing, reading the secret key from standard input.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-backend BACKEND
Select the BLAKE3 backend implementation.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-list\-backends
List available BLAKE3 backends.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-num\-threads N
Set the worker\-thread count. \fB0\fP means automatic selection and \fB\-1\fP
disables threaded hashing.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-file\-buffer N
Set the per\-file I/O buffer size.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-mmap\-min\-chunk N
Set the minimum chunk size used for memory\-mapped hashing input.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-mmap\-max\-chunk N
Set the maximum chunk size used for memory\-mapped hashing input.
.UNINDENT
.sp
Reflection options
.INDENT 0.0
.TP
.B \-\-reflect
Enable reflection mode.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-generate\-c
Generate C definitions from reflection input.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-generate\-blob BLOB
Generate a packed reflection blob and write it to \fBBLOB\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-import\-blob BLOB
Import reflection metadata from \fBBLOB\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-import\-c\-file FILE
Import reflection metadata from \fBFILE\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-cflags FLAGS
Pass compiler flags to reflection imports of C source files.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-entry\-type TYPE
Select the reflection entry\-point type.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-packed\-roundtrip
Round\-trip reflection data through the packed representation.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-prune\-system
Keep system types in the reflection database.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-type\-include REGEX
Include only reflected types matching \fBREGEX\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-type\-exclude REGEX
Exclude reflected types matching \fBREGEX\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-dump\-reflection
Dump reflection structures for debugging.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-debug\-reflection
Enable verbose reflection debug output.
.UNINDENT
.sp
Generic options
.INDENT 0.0
.TP
.B \-\-generic
Enable generic data\-structure dumping mode.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-generic\-testsuite
Enable generic testsuite mode.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-builder\-policy
Select the generic builder policy.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-generic\-parse\-dump
Parse and dump using the generic layer.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-dedup
Enable generic deduplication.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-dedup
Disable generic deduplication.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-dump\-primitives
Dump generic primitive values explicitly.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-create\-markers
Create source markers in generated generic data.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-pyyaml\-compat
Enable PyYAML compatibility mode.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-keep\-style
Preserve style information in generic data.
.UNINDENT
.sp
Modes
.INDENT 0.0
.TP
.B \-\-dump
Select dump mode. This is the default and also the mode used by
\fBfy\-dump\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-testsuite
Select testsuite mode. This is also the mode used by
\fBfy\-testsuite\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-filter
Select filter mode. This is also the mode used by \fBfy\-filter\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-join
Select join mode. This is also the mode used by \fBfy\-join\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-ypath
Select ypath query mode. This is also the mode used by \fBfy\-ypath\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-scan\-dump
Select the internal scan\-dump mode.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-parse\-dump
Select the internal parse\-dump mode.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-compose
Select composer\-driver dump mode. This is also the mode used by
\fBfy\-compose\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-yaml\-version\-dump
Print YAML version information.
.UNINDENT
.SH EXAMPLES
.sp
Dump a YAML file back out using the default emitter mode:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ fy\-dump invoice.yaml
.EE
.UNINDENT
.UNINDENT
.sp
Resolve anchors and strip labels from the result:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ fy\-dump \-r \-\-strip\-labels simple\-anchors.yaml
.EE
.UNINDENT
.UNINDENT
.sp
Read literal input text via \fB\-\-file\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ fy\-filter \-\-file \e\(dq>foo: bar\e\(dq /
.EE
.UNINDENT
.UNINDENT
.sp
Select data from a file using a path expression:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ fy\-filter \-\-file simple\-anchors.yaml /baz/bar
.EE
.UNINDENT
.UNINDENT
.sp
Join two root mappings into a single document:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ fy\-join simple\-anchors.yaml invoice.yaml
.EE
.UNINDENT
.UNINDENT
.sp
Generate testsuite event output:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ fy\-testsuite invoice.yaml
.EE
.UNINDENT
.UNINDENT
.sp
List available BLAKE3 backends:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ fy\-b3sum \-\-list\-backends
.EE
.UNINDENT
.UNINDENT
.SH AUTHOR
.sp
Pantelis Antoniou <\%<pantelis\:.antoniou@\:konsulko\:.com>>
.SH BUGS
.INDENT 0.0
.IP \(bu 2
The only supported input and output character encoding is UTF8.
.IP \(bu 2
Sorting does not respect language settings.
.IP \(bu 2
There is no way for the user to specific a different coloring scheme.
.UNINDENT
.SH SEE ALSO
.sp
\fBlibfyaml(3)\fP
.SH Copyright
2019-2026, Pantelis Antoniou
.\" End of generated man page.