.\" Generated by gen_docs from crates/datui-cli. Do not edit.
.TH DATUI\-FORMATS 1 2026-10-08 "datui 0.4.4" "User Commands"
.nr HY 0
.ds AD l
.SH NAME
datui\-formats \- list the format specs and dictionaries (FIX, DBC) on the search path
.SH SYNOPSIS
.nf
\fBdatui formats\fR
\fBdatui formats check\fR \fISPEC\fR [\fIFILE\fR]
.fi
.SH DESCRIPTION
List the format specs and dictionaries (FIX, DBC) on the search path: each one's name, what it matches, its file, and the copies it overrides.
.PP
Format specs are TOML files that describe a binary format, or a family of delimited text files; datui-formats(7) describes them. The search path is \fICONFIG\fR/formats, then \fB$DATUI_FORMATS_PATH\fR, then \fB[formats] path\fR in the config.
.SH COMMANDS
.TP
\fBdatui formats check\fR
Check a format spec or a dictionary (QuickFIX XML, DBC or TOML), by name or by file; with FILE, print its first decoded rows, or what a dictionary names in the log. Exits non-zero on an error.
.RS
.TP
\fISPEC\fR
A format spec or dictionary on the search path, by name, or its file.
.TP
\fIFILE\fR
A file (or directory of column files) to read with it.
.RE
.SH OPTIONS
.TP
\fB\-c\fR, \fB\-\-config\fR \fIKEY=VALUE\fR
Set a config key for this run, as in the file: \-c display.\:row_numbers=true. Repeatable; a flag of the key's own still wins. \fBdatui config keys\fR lists them.
.TP
\fB\-h\fR, \fB\-\-help\fR
Print help.
.SH "EXIT STATUS"
.TP
\fB0\fR
Success: the session was quit (q, Ctrl+Q or Ctrl+C), or the command did what it was asked.
.TP
\fB1\fR
An error, printed to standard error: a PATH that is not there, a configuration file that cannot be used, nothing piped in for \-, or a command that failed (datui formats check on a spec with errors).
.TP
\fB2\fR
A usage error: an unknown option or command, or a value an option does not take.
.SH ENVIRONMENT
.TP
\fBDATUI_CONFIG_DIR\fR
The config directory, in place of the platform's (\fB~/.config/datui\fR on Linux). Saved views and format specs live there too.
.TP
\fBDATUI_FORMATS_PATH\fR
Directories of format specs and dictionaries, separated as \fBPATH\fR is, searched before \fB[formats] path\fR.
.SH FILES
\fICONFIG\fR is \fB$DATUI_CONFIG_DIR\fR when it is set, else \fB$XDG_CONFIG_HOME/datui\fR (\fB~/.config/datui\fR) on Linux, \fB~/Library/Application Support/datui\fR on macOS and \fB%APPDATA%\edatui\fR on Windows.
.TP
\fICONFIG\fR/config.toml
The config file: see datui-config(5). \fBdatui config path\fR prints the files read.
.TP
\fICONFIG\fR/catalog.toml
Your catalog, which Ctrl+D on the home screen adds to: see datui-catalog(1).
.TP
\fICONFIG\fR/catalogs/
More catalogs, one *.toml each, named by its file; examples.toml replaces the bundled one.
.TP
\fICONFIG\fR/views/
Saved views: see datui-views(1).
.TP
\fICONFIG\fR/formats/
Format specs and dictionaries, searched first: see datui-formats(7).
.SH EXAMPLES
List the format specs and dictionaries datui finds.
.PP
.RS 4
.EX
datui formats
.EE
.RE
.PP
Check a format spec of two one-byte fields against a file of two records, and print the rows it reads.
.PP
\fBpairs.toml\fR
.PP
.RS 4
.EX
name = "demo.pairs"
match = { glob = ["*.pairs"] }
[records]
fields = [{ name = "a", type = "u1" }, { name = "b", type = "u1" }]
.EE
.RE
.PP
\fBmake_pairs.py\fR
.PP
.RS 4
.EX
# Two records of two one\-byte fields: (1, 2) and (3, 4).
with open("t.pairs", "wb") as f:
f.write(bytes([1, 2, 3, 4]))
.EE
.RE
.PP
.RS 4
.EX
python3 make_pairs.py && datui formats check ./pairs.toml t.pairs
.EE
.RE
.SH "SEE ALSO"
\fBdatui\fR(1), \fBdatui\-formats\fR(7)
.PP
The datui documentation: <https:/\:/\:derekwisong.\:github.\:io/\:datui/\:>
.SH BUGS
Report bugs at <https:/\:/\:github.\:com/\:derekwisong/\:datui/\:issues>.
.SH AUTHORS
Derek Wisong and the datui contributors.
.SH COPYRIGHT
Copyright \(co 2026 Derek Wisong
.PP
datui is free software under the MIT License.