go-template-cli

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]
Options:
  -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 string       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
  -h, --help                 show the help text
      --usage                show the short usage text
  -v, --version              show the version

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 treasure-map functions 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>'