interpres/docs/CLI.md

# Command line

The reference below is taken from the program itself. `interpres-decode` is
the toml-test harness adapter in both directions, decoding TOML into tagged
JSON and encoding tagged JSON back into TOML, and it also validates documents.
The same reference ships as the manual page `man/interpres-decode.1`.
Install it with Go itself, no release assets involved:

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

## Synopsis

```sh
interpres-decode [flags]
interpres-decode --encode
interpres-decode --validate [file ...]
interpres-decode --validate [directory ...]
interpres-decode --json
interpres-decode --struct
interpres-decode --schema TYPE file.go
interpres-decode --version
```

Without `--validate`, `--encode`, `--json`, `--struct` or `--schema` the
program is the decoding half of 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 `--encode` the direction is reversed: the program reads a tagged-JSON
description from stdin and writes the TOML document it describes to stdout,
which is the shape toml-test expects of an encoder command. It takes no
arguments either, and the mode flags cannot be combined.

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. A named directory is walked for `.toml` files, every one of them
validated, and the walk closes with a summary on stderr naming how many
documents were checked and how many were invalid.

With `--json` the decoding half prints plain indented JSON instead of the
tagged form, the shape for people and diffs: the values keep their types as
JSON sees them, and the date-time wrappers print in their TOML form. The flag
shapes the decoding output only, so it is rejected together with the mode
flags.

With `--struct` the program reads a TOML document from stdin and prints a Go
struct definition shaped like it: one field per key in written order, nested
tables as nested struct types, and an array of tables as a slice. The
printed type compiles and decodes the document it came from.

With `--schema` the program reads a Go source file and writes a TOML template
for the named struct type: one key per exported field, the `comment=` tag
option printed as a comment above it, and the `default=` option as the value
where one is set. It is the inverse of `--struct`, for config-driven
applications that generate their example configuration from the type.

`--version` prints the binary's version and exits. The release pipeline builds
at the tag, so a released binary prints its own tag; a build from a working
tree prints `(devel)`.

## Flags

| Flag | Effect |
|---|---|
| `--validate` | validate the documents instead of emitting tagged JSON; directories are walked for `.toml` files |
| `--encode` | read tagged JSON from stdin and write TOML instead |
| `--json` | with the default mode, print plain indented JSON instead of tagged JSON |
| `--struct` | infer a Go struct definition from the document on stdin and print it |
| `--schema TYPE` | write a TOML template for the struct type TYPE from the Go source file named as the first argument |
| `--version` | print the version and exit |
| `--help` | print the usage |

## Exit codes

| Code | Meaning |
|---|---|
| `0` | adapter: the document parsed and the tagged JSON was written; encode: the TOML was written; validate: every document parsed; schema, struct, version: the output was written |
| `1` | adapter: parse error; validate: at least one document is invalid; struct: the document on stdin failed to parse |
| `2` | a usage error, a read or write failure, malformed tagged JSON, or a value with no TOML 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`:

```json
{
  "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` |

The `--encode` mode reads exactly this form back. Two properties of it are
worth knowing. A float whose value has no fraction and no exponent is written
as a bare integer string, `{"type": "float", "value": "1"}`, so there the tag
decides the type and not the literal. And the form cannot tell an array of
tables from a value array of inline tables, so the adapter writes the header
form, `[[a]]`, for an array whose every element is a JSON object; a mixed
array keeps the value form.

## Examples

Echo a small document through the adapter:

```sh
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. Turn a description
back into TOML with `--encode`:

```sh
echo '{"title": {"type": "string", "value": "hello"}}' | ./bin/interpres-decode --encode
```

```toml
title = "hello"
```

Validate the TOML files of another repository in CI:

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

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

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

Sweep a whole directory tree of configuration, with the summary the walk
closes on:

```sh
$ interpres-decode --validate configs/
interpres-decode: configs/old.toml: interpres: line 3: duplicate key "port"
checked 14 documents, 1 invalid
$ echo $?
1
```

See the document a `--struct` template would decode:

```sh
echo 'host = "db"
port = 5432
' | ./bin/interpres-decode --struct
```

```go
// Generated by interpres-decode --struct; decode with
// sourcedock.dev/petrbalvin/interpres/v2.
type inferred struct {
	Host string `toml:"host"`
	Port int64  `toml:"port"`
}
```

Write the template back from the type, comments and defaults included, where
the Go source declares fields tagged
`toml:"host,comment=The host to dial,default=example.org"`:

```sh
./bin/interpres-decode --schema Config config.go
```

```toml
# The host to dial
host = "example.org"
```

Print the binary's version:

```sh
$ ./bin/interpres-decode --version
interpres-decode v2.0.0
```

Run the official compliance suite against the adapter:

```sh
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`. It runs
the suite in both directions: the decoder against the valid and invalid
corpora, and the encoder against the tagged JSON of the valid one. The full
reference for the library itself is [API.md](API.md).