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:

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

## Synopsis

```sh
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`:

```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` |

## 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. 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
bad.toml: interpres: line 1: expected a value
$ echo $?
1
```

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`. The full
reference for the library itself is [API.md](API.md).