nomad/website/content/docs/manage/format-cli-output.mdx

---
layout: docs
page_title: Format CLI output with templates
description: |-
  Customize the output of Nomad CLI commands with Go template syntax. Practice
  interacting with unfamiliar template contexts.
---

# Format CLI output with templates

When using Nomad at an intermediate to advanced level, you'll need to interface with other systems or customize output generated by Nomad. The `-t` flag is a powerful way to pass a template in Go's text/template format to
several of the Nomad commands that generate output based on the API. This allows
you to filter and customize the output to meet your specific needs.

The commands that allow for the -t flag are:

- `nomad acl policy list`
- `nomad acl token list`
- `nomad alloc status`
- `nomad deployment list`
- `nomad deployment status`
- `nomad eval status`
- `nomad job deployments`
- `nomad job history`
- `nomad job inspect`
- `nomad namespace list`
- `nomad node status`
- `nomad plugin status`
- `nomad quota list`
- `nomad volume status`

This guide will teach you how to explore the objects that are returned to
the template engine and how to use template syntax to format the output into
a custom form.

## Prerequisites

This guide assumes the following:

- Familiarity with Go's text/template syntax. You can learn more about it in the
  [Go template syntax][go-template-syntax] reference.

- That you are running these commands against a Nomad cluster with an active
  workload. You can create a minimal environment using a dev agent, started with
  `sudo nomad agent -dev`, then running at least one Nomad job. You can use
  `nomad init -short` to create a sample Docker job or provide your own Nomad
  job.

## Note the shell-specific syntax

When using the -t flag, you need to correctly handle string literals based on
your shell environment. In a POSIX shell, you can run the following with a
single quote:

```shell-session
$ nomad node status  -t '{{printf "%#+v" .}}'
```

In a Windows shell (for example, PowerShell), use single
quotes but escape the double quotes inside the parameter as follows:

```powershell
PS> nomad node status  -t '{{printf \"%#+v\" .}}'
```

In this guide, you can select examples with the proper escaping using the
tabs above the snippets.

## Start discovering objects

The `printf` function and the `"%#+v"` format string are critical tools for you
in exploring an unfamiliar template context.

Run the following command to output the context being passed to the template
in Go object format.

<Tabs><Tab heading="Posix Shells" group="posix">


```shell-session
$ nomad node status -t '{{printf "%#+v" .}}'
```

</Tab><Tab heading="PowerShell" group="ps">


```powershell
PS> nomad node status -t '{{printf \"%#+v\" .}}'
```

</Tab></Tabs>


```plaintext
[]*api.NodeListStub{(*api.NodeListStub)(0xc0003fa160), (*api.NodeListStub)(0xc0003fa0b0), (*api.NodeListStub)(0xc0003fa000)}
```

The output indicates that the context consists of a list (`[]`) of pointers
(`*`) to `api.NodeListStub` objects. The list will also show one NodeListStub
object per client node in your cluster's server state.

You can explore these api.NodeListStub object by using the `range` control over
the list.

<Tabs><Tab heading="Posix Shells" group="posix">


```shell-session
$ nomad node status -t '{{range .}}{{printf "%#+v" .}}{{end}}'
```

</Tab><Tab heading="PowerShell" group="ps">


```powershell
PS> nomad node status -t '{{range .}}{{printf \"%#+v\" .}}{{end}}'
```

</Tab></Tabs>


```plaintext
&api.NodeListStub{Address:"10.0.2.52", ID:"4f60bc83-71a2-7790-b120-4e55d0e6ed34", Datacenter:"dc1", Name:"nomad-client-2.node.consul", NodeClass:"", Version:"0.12.0", Drain:false, SchedulingEligibility:"eligible", Status:"ready", ...
```

If you have a lot of client nodes in your cluster state, this output will be
unwieldy. In that case, you can use `with` and the index function to get the
first list item.

<Tabs><Tab heading="Posix Shells" group="posix">


```shell-session
$ nomad node status -t '{{with index . 0}}{{printf "%#+v" .}}{{end}}'
```

</Tab><Tab heading="PowerShell" group="ps">


```powershell
PS> nomad node status -t '{{with index . 0}}{{printf \"%#+v\" .}}{{end}}'
&api.NodeListStub{Address:"10.0.2.52", ID:"4f60bc83-71a2-7790-b120-4e55d0e6ed34", Datacenter:"dc1", Name:"nomad-client-2.node.consul", NodeClass:"", Version:"0.12.0", Drain:false, SchedulingEligibility:"eligible", Status:"ready", ...
```

</Tab></Tabs>


```plaintext
&api.NodeListStub{Address:"10.0.2.52", ID:"4f60bc83-71a2-7790-b120-4e55d0e6ed34", Datacenter:"dc1", Name:"nomad-client-2.node.consul", NodeClass:"", Version:"0.12.0", Drain:false, SchedulingEligibility:"eligible", Status:"ready", ...
```

Finally, output `Name` and `Version` for each client in the cluster.

<Tabs><Tab heading="Posix Shells" group="posix">


```shell-session
$ nomad node status -t '{{range .}}{{printf "%s: %s\n" .Name .Version}}{{end}}'
```

</Tab><Tab heading="PowerShell" group="ps">


```powershell
PS> nomad node status -t '{{range .}}{{printf \"%s: %s\n\" .Name .Version}}{{end}}'
```

</Tab></Tabs>


```plaintext
nomad-client-2.node.consul: 0.12.0
nomad-client-3.node.consul: 0.12.0
nomad-client-1.node.consul: 0.12.0
```

## Make quiet output

Suppose you want to create a reduced version of the `nomad job status` output
to show just the running job IDs in your cluster and nothing else.

<Tabs><Tab heading="Posix Shells" group="posix">


```shell-session
$ nomad job inspect -t '{{range .}}{{if eq .Status "running"}}{{ println .Name}}{{end}}{{end}}'
```

</Tab><Tab heading="PowerShell" group="ps">


```powershell
PS> nomad job inspect -t '{{range .}}{{if eq .Status \"running\"}}{{ println .Name}}{{end}}{{end}}'
```

</Tab></Tabs>


Nomad will output the job IDs for every running job in your cluster. For example:

```plaintext
fabio
sockshop-carts
sockshop-catalogue
sockshop-frontend
sockshop-infra
sockshop-orders
sockshop-payment
sockshop-shipping
sockshop-user
```

### Challenge yourself

Allocations have a slightly different shape. How might you create similar output
from the `nomad alloc status` command? Make sure that your Nomad cluster has at
least one allocation running and then use the printf technique from earlier to
explore the values sent into the template.

<Accordion heading="View Solution" collapse="true">


Print the context that you are passed from the command using the printf command.

<Tabs><Tab heading="Posix Shells" group="posix">


```shell-session
$ nomad alloc status -t '{{printf "%#+v" . }}'
```

</Tab><Tab heading="PowerShell" group="ps">


```powershell
PS> nomad alloc status -t '{{printf \"%#+v\" . }}'
```

</Tab></Tabs>


```plaintext
[]*api.AllocationListStub ...
```

Note that the first thing that you receive is a list (`[]`) of pointers (`*`) to
`AllocationListStub` objects.

Use `range` to traverse each item in the list.

<Tabs><Tab heading="Posix Shells" group="posix">


```shell-session
$ nomad alloc status -t '{{range .}}{{printf "%#+v" . }}{{end}}'
```

</Tab><Tab heading="PowerShell" group="ps">


```powershell
PS> nomad alloc status -t '{{range .}}{{printf \"%#+v\" . }}{{end}}'
```

</Tab></Tabs>


```plaintext
&api.AllocationListStub{ID:"30663b68-4d8a-aada-4ad2-011b1acae3a1", EvalID:"c5eda90b-f675-048e-b2f7-9ced30e4916b", Name:"sockshop-user.userdb[0]", Namespace:"default", NodeID:"3be35c12-70aa-8816-195e-a4630a457727", NodeName:"nomad-client-3.node.consul", JobID:"sockshop-user", JobType:"service", JobVersion:0x0, ...
```

If you have a lot of allocations running, this could get unwieldy. In that case,
you can use `with` and the index function to get the first list item.

<Tabs><Tab heading="Posix Shells" group="posix">


```shell-session
$ nomad alloc status -t '{{with index . 0}}{{printf "%#+v" . }}{{end}}'
```

</Tab><Tab heading="PowerShell" group="ps">


```powershell
PS> nomad alloc status -t '{{with index . 0}}{{printf \"%#+v\" . }}{{end}}'
```

</Tab></Tabs>


```plaintext
&api.AllocationListStub{ID:"30663b68-4d8a-aada-4ad2-011b1acae3a1", EvalID:"c5eda90b-f675-048e-b2f7-9ced30e4916b", Name:"sockshop-user.userdb[0]", Namespace:"default", NodeID:"3be35c12-70aa-8816-195e-a4630a457727", NodeName:"nomad-client-3.node.consul", JobID:"sockshop-user", JobType:"service", JobVersion:0x0, ...
```

The fields on the AllocationListStub object that give insight into the running
state of an allocation are `DesiredStatus` and `ClientStatus`.

-> **Did you know?** The definition of an [AllocationListStub][] object and
valid values for the DesiredStatus and ClientStatus are located in Nomad's
[api package][]. Take a moment to look at it and see what other information you
might be interested in displaying with templates.

Update your template to show items with a DesiredStatus of "run" and a client
status of "running" or "pending."

<Tabs><Tab heading="Posix Shells" group="posix">


```shell-session
$ nomad alloc status -t '{{range .}}{{if and (eq .DesiredStatus "run") (or (eq .ClientStatus "running") (eq .ClientStatus "pending"))}}{{println .ID}}{{end}}{{end}}'
```

</Tab><Tab heading="PowerShell" group="ps">


```powershell
PS> nomad alloc status -t '{{range .}}{{if and (eq .DesiredStatus \"run\") (or (eq .ClientStatus \"running\") (eq .ClientStatus \"pending\"))}}{{println .ID}}{{end}}{{end}}'
```

</Tab></Tabs>


```plaintext
30663b68-4d8a-aada-4ad2-011b1acae3a1
11b916da-d679-1718-26f3-f6cd499bfdb8
68bcb157-359f-9293-d091-5a8ef71475ad
...
```

You now have a list of the IDs for all of the allocations running in your Nomad
cluster.

</Accordion>


## Retrieve a template from file

Using the command line to write templates becomes challenging
as the template becomes more complex.

By writing a template in its own file, you can use comments, span multiple lines, and indent conditionals in order to make them more readable to you and to other operators.

Consider using some of these techniques
to include the template data into the command.

<Tabs>
<Tab heading="Posix Shells" group="posix">


Create a file named running_jobs.tmpl with the following content.

```plaintext
{{- /*
  Get Running Jobs
  Run with `nomad job inspect -t "$(cat running_jobs.tmpl)"`
*/ -}}
{{- range . -}}
  {{- if eq .Status "running" -}}
    {{- println .Name -}}
  {{- end -}}
{{- end -}}
```

Now, use a subshell to read the file into a variable

```shell-session
$ nomad job inspect -t "$(cat running_jobs.tmpl)"
```

</Tab>
<Tab heading="PowerShell" group="ps">


Create a file named running_jobs.tmpl with the following content.

```plaintext
{{- /*
  Get Running Jobs
  Run with:
    $content=Get-Content running_jobs.tmpl -Raw; nomad job inspect -t $content
*/ -}}
{{- range . -}}
  {{- if eq .Status \"running\" -}}
    {{- println .Name -}}
  {{- end -}}
{{- end -}}
```

Now, use a subshell to read the file into a variable

```powershell
PS> $content=Get-Content running_jobs.tmpl -Raw; nomad job inspect -t $content
```

</Tab>
</Tabs>


## Learn more

In this guide, you learned how to:

- Customize the output of several Nomad commands using Go's text/template
  syntax.

- Use the `printf` function to discover what is available in the template's
  context.

- Use a template definition contained in a file as part of the command.


[go-template-syntax]: /nomad/docs/reference/go-template-syntax
[allocationliststub]: https://godoc.org/github.com/hashicorp/nomad/api#AllocationListStub
[api package]: https://godoc.org/github.com/hashicorp/nomad/api