Go Template CLI (tpl)

Render json, yaml, & toml with go templates from the command line.

The templates are executed with the
text/template package. This means
they come with the additional risks and benefits of the text template
engine.

Synopsis

Usage: tpl [options] [templates]
  -f, --file stringArray     template file path. Can be specified multiple times
  -g, --glob stringArray     template file glob. Can be specified multiple times
  -n, --name string          if specified, execute the template with the given name
  -d, --decoder func         decoder to use for input data. Supported values: json, yaml, toml (default "json")
      --option stringArray   option to pass to the template engine. Can be specified multiple times
      --no-newline           do not print newline at the end of the output
      --version              show version information and exit

Input Data

The input data is read from stdin via pipe or redirection. It is
actually not required to provide any input data. If no input data is
provided, the template is executed with nil data.

# Redirection
tpl '{{ . }}' < path/to/input.json
# Pipe
curl localhost | tpl '{{ . }}'
# nil data
tpl '{{ . }}'

Templates

The default templates name is _gotpl_default and positional arguments
are parsed into this root template. That means while its possible to
specify multiple arguments, they will overwrite each other unless they
use the define keyword to define a named template that can be
referenced later when executing the template. If a named template is
parsed multiple times, the last one will override the previous ones.

Templates from the flags --file and --glob are parsed in the order
they are specified. So the override rules of the text/template package
apply. If a file with the same name is specified multiple times, the
last one wins. Even if they are in different directories.

The behavior of the cli tries to stay consistent with the actual
behavior of the go template engine.

If the default template exists it will be used unless the --name flag
is specified. If no default template exists because no positional
argument has been provided, the template with the given file name is
used, as long as only one file has been parsed. If multiple files have
been parsed, the --name flag is required to avoid ambiguity.

tpl '{{ . }}' --file foo.tpl --glob 'templates/*.tpl'         # default will be used
tpl --file foo.tpl                                            # foo.tpl will be used
tpl --file foo.tpl --glob 'templates/*.tpl' --name foo.tpl    # the --name flag is required to select a template by name

The ability to parse multiple templates makes sense when defining helper
snippets and other named templates to reference using the builtin
template keyword or the custom include function which can be used in
pipelines.

note globs need to quotes to avoid shell expansion.

Decoders

By default input data is decoded as json and passed to the template to
execute. It is possible to use an alternative decoder. The supported
decoders are:

• json
• yaml
• toml

While json could technically be decoded using the yaml decoder, this is
not done by default for performance reasons.

Options

The --options flag is passed to the template engine. Possible options
can be found in the documentation of the template
engine.
The only option currently known is missingkey. Since the input data is
decoded into interface{}, setting missingkey=zero will show <no value>, if the key does not exist, which is the same as the default.
However, missingkey=error has some actual use cases.

Functions

Next to the builtin functions, Sprig
functions and some custom
function are available.

Installation

Binary

Download the binary from the release
page. For
example

curl -fsSL https://github.com/bluebrown/go-template-cli/releases/latest/download/tpl-linux-amd64 >tpl
chmod 755 tpl

Go

If you have go installed, you can use the go install command to
install the binary.

go install github.com/bluebrown/go-template-cli/cmd/tpl@latest

Example

Review the
examples
directory, for more examples.

curl -s https://jsonplaceholder.typicode.com/users | tpl '<table>
  <caption>My Address Book</caption>
  <tr>
    <th>Name</th>
    <th>Email</th>
    <th>Phone</th>
    <th>Address</th>
  </tr>
  {{- range . }}
  <tr>
    <th>{{ .name }}</th>
    <td>{{ .email }}</td>
    <td>{{ .phone }}</td>
    <td>
      <ul>
        {{- range $key, $val := .address }} {{ if ne $key "geo" }}
        <li><strong>{{ $key }}:</strong> &nbsp; {{ $val }}</li>
        {{- end -}}
        {{ end }}
      </ul>
    </td>
  </tr>
  {{- end -}}
</table>'