interpres/man/interpres-decode.1

.TH INTERPRES-DECODE 1 "2026-09-22" "interpres 2.0.0" "User Commands"
.SH NAME
interpres-decode \- TOML validator and toml-test harness adapter
.SH SYNOPSIS
.B interpres-decode
[\fIFLAGS\fR]
.br
.B interpres-decode
.B \-\-encode
.br
.B interpres-decode
.B \-\-validate
[\fIFILE\fR...]
.br
.B interpres-decode
.B \-\-validate
[\fIDIRECTORY\fR...]
.br
.B interpres-decode
.B \-\-json
.br
.B interpres-decode
.B \-\-struct
.br
.B interpres-decode
.B \-\-schema
\fITYPE\fR
\fIFILE.go\fR
.br
.B interpres-decode
.B \-\-version
.SH DESCRIPTION
.B interpres-decode
is the toml-test harness adapter in both directions and a TOML validator.
Without a mode flag it reads one TOML document from standard input and writes
the toml-test tagged-JSON representation to standard output.
.B \-\-encode
reads a tagged-JSON description from standard input and writes the TOML
document it describes.
.B \-\-validate
parses each named file, or standard input when none are named, and prints one
line per invalid document to standard error; a named directory is walked for
.B .toml
files, every one validated, and the walk closes with a summary on standard
error naming the counts. The name
.B \-
means standard input.
.B \-\-json
prints plain indented JSON instead of the tagged form; it shapes the decoding
output only, so it is rejected together with the mode flags.
.B \-\-struct
prints a Go struct definition inferred from the document on standard input.
.B \-\-schema
writes a TOML template for the struct type
\fITYPE\fR
declared in the Go source file
\fIFILE.go\fR,
taking the key names, comments and defaults from the fields' tags.
.B \-\-version
prints the binary's version and exits.
.PP
The mode flags
.BR \-\-validate ,
.BR \-\-encode ,
.B \-\-struct
and
.B \-\-schema
cannot be combined.
.SH OPTIONS
.TP
.B \-\-validate
Validate the documents instead of emitting tagged JSON.
.TP
.B \-\-encode
Read tagged JSON from standard input and write TOML instead.
.TP
.B \-\-json
With the default mode, print plain indented JSON instead of tagged JSON.
.TP
.B \-\-struct
Infer a Go struct definition from the document on standard input and print it.
.TP
.BI \-\-schema " TYPE"
Write a TOML template for the struct type \fITYPE\fR; the Go source file
follows as the first argument.
.TP
.B \-\-version
Print the version and exit.
.TP
.B \-\-help
Print the usage.
.SH EXIT STATUS
.TP
.B 0
The document parsed and the output was written; in validate mode, every
document parsed.
.TP
.B 1
Adapter: a parse error. Validate: at least one document is invalid. Struct:
the document on standard input failed to parse.
.TP
.B 2
A usage error, a read or write failure, malformed tagged JSON, or a value
with no TOML representation.
.SH EXAMPLES
Decode a document into tagged JSON:
.PP
.nf
.RS
echo 'title = "hello"' | interpres-decode
.RE
.fi
.PP
Validate a directory of configuration, with the summary:
.PP
.nf
.RS
interpres-decode \-\-validate configs/
.RE
.fi
.PP
Infer a Go type from a document:
.PP
.nf
.RS
interpres-decode \-\-struct < config.toml > config.go
.RE
.fi
.PP
Write the template back from the type:
.PP
.nf
.RS
interpres-decode \-\-schema Config config.go
.RE
.fi
.SH SEE ALSO
The repository's
.B docs/CLI.md
carries the full reference, including the tagged-JSON wire format.