interpres/docs/CLI.md

Command line

The reference below is taken from the program itself. interpres-decode is the toml-test harness adapter, and it also validates documents. Install it with Go itself, no release assets involved:

go install sourcedock.dev/petrbalvin/interpres/cmd/interpres-decode@latest

Synopsis

interpres-decode [flags]
interpres-decode -validate [file ...]

Without -validate the program is the toml-test adapter: it takes no arguments, reads one TOML document from stdin, and writes the toml-test tagged-JSON form to stdout. Build it locally with just build, which compiles it into bin/interpres-decode, or run it straight from the module directory with just run.

With -validate the program parses each named file instead, or stdin when no file is named, and prints one line per invalid document to stderr. It is quiet on valid documents, which is the shape a CI step wants. The - name means stdin.

Flags

Flag	Effect
-validate	validate the documents instead of emitting tagged JSON
-h	print the usage

Exit codes

Code	Meaning
0	adapter: the document parsed and the tagged JSON was written; validate: every document parsed
1	adapter: parse error; validate: at least one document is invalid
2	a usage error, a read failure, or a value with no tagged representation

Wire format

Tables become JSON objects, arrays become JSON arrays, and every scalar is wrapped in an object with a type and a value:

{
  "title": {"type": "string", "value": "hello"},
  "port": {"type": "integer", "value": "9090"},
  "enabled": {"type": "bool", "value": "true"},
  "ratio": {"type": "float", "value": "3.14"}
}

TOML value	Tag	Rendering
string	string	the string verbatim
integer	integer	decimal
float	float	decimal, or inf, -inf, nan
boolean	bool	true or false
offset date-time	datetime	RFC 3339 with nanoseconds
local date-time	datetime-local	1979-05-27T07:32:00
local date	date-local	1979-05-27
local time	time-local	07:32:00.999999

Examples

Echo a small document through the adapter:

echo 'title = "hello"
[server]
host = "127.0.0.1"
port = 9090
' | ./bin/interpres-decode

The output is the equivalent value tree as one JSON object. Validate the TOML files of another repository in CI:

interpres-decode -validate config.toml deploy/example.toml

An invalid document reports the file and the library's line number:

$ interpres-decode -validate bad.toml
bad.toml: interpres: line 1: expected a value
$ echo $?
1

Run the official compliance suite against the adapter:

just toml-test

That recipe needs the toml-test binary on PATH, installed with go install github.com/toml-lang/toml-test/v2/cmd/toml-test@v2.2.0. The full reference for the library itself is API.md.