---
layout: docs
page_title: nomad var list reference
description: |-
  The `nomad var list` command displays data from Nomad's variables datastore at
  or beginning with the given prefix.
---

# `nomad var list` command reference

The `var list` command returns a list of [variable][] paths accessible to the
current user, optionally filtered to paths containing a provided prefix. Do not
encode sensitive information in variable paths. The variable's items are not
accessible via this command.

When using pagination, the next page token is provided as part of the output of
the command. When the output format is JSON, the returned variable list is
wrapped with additional metadata that contains the next page token. For non-JSON
output, the next page token is printed as a message to standard error and
standard output contains the variables from the specifically requested page.


## Usage

```plaintext
nomad var list [options] [<prefix>]
```

If ACLs are enabled, this command requires the `variables:list` capability for
the namespaces and paths containing the variables to list. See the [ACL policy][]
documentation for details.

## Options

- `-per-page` `(int: <unset>)`: How many results to show per page.

- `-page-token` `(string: "")`: Where to start pagination.

- `-filter` `(string: "")`: Specifies an expression used to filter query
  results. Queries using this option are less efficient than using the prefix
  parameter; therefore, the prefix parameter should be used whenever possible.

- `-out` `(enum: go-template | json | table | terse )`: Format to render the
  variable in. When using "go-template", you must provide the template content
  with the `-template` option. Defaults to "table" when stdout is a terminal and
  to "json" when stdout is redirected.

- `-template` `(string: "")` Template to render output with. Required when
  output is "go-template".

- `-ui`: Open the variable list page in the browser.

## Examples

List values under the key "nomad/jobs":

```shell-session
$ nomad var list nomad/jobs
Namespace  Path                           Last Updated
default    nomad/jobs/example             2022-08-23T10:35:47-04:00
default    nomad/jobs/variable            2022-08-23T10:24:45-04:00
default    nomad/jobs/variable/www        2022-08-23T10:24:45-04:00
default    nomad/jobs/variable/www/nginx  2022-08-23T10:24:46-04:00
```

List values under the key "nomad/jobs/variable/www" in JSON format:

```shell-session
$ nomad var list -out=json -namespace="*" nomad/jobs/variable/www
[
  {
    "Namespace": "default",
    "Path": "nomad/jobs/variable/www",
    "CreateIndex": 1457,
    "ModifyIndex": 1457,
    "CreateTime": 1662061225600373000,
    "ModifyTime": 1662061225600373000
  },
  {
    "Namespace": "default",
    "Path": "nomad/jobs/variable/www/nginx",
    "CreateIndex": 800,
    "ModifyIndex": 1000,
    "CreateTime": 1662061717905426000,
    "ModifyTime": 1662062162982630000
  }
]
```

Perform a paginated query:

```shell-session
$ nomad var list -per-page=3
Namespace  Path                           Last Updated
default    nomad/jobs/example             2022-08-23T10:35:47-04:00
default    nomad/jobs/variable            2022-08-23T10:24:45-04:00
default    nomad/jobs/variable/www        2022-08-23T10:24:45-04:00
Next page token: default.nomad/jobs/variable/www/nginx
```

To fetch the next page :

```shell-session
$ nomad var list -per-page=3 \
  -page-token=default.nomad/jobs/variable/www/nginx
Namespace  Path                 Last Updated
default    nomad/jobs/variable/www/nginx  2022-08-23T10:24:46-04:00
```

Perform a paginated query with JSON formatting:

```shell-session
$ nomad var list -out=json -namespace="*" -per-page=1 nomad/jobs/variable/www
{
    "Data": [
        {
           "Namespace": "default",
            "Path": "nomad/jobs/variable/www",
            "CreateIndex": 1457,
            "ModifyIndex": 1457,
            "CreateTime": 1662061225600373000,
            "ModifyTime": 1662061225600373000
        }
    ],
    "QueryMeta": {
        "KnownLeader": true,
        "LastContact": 0,
        "LastIndex": 43,
        "NextToken": "default.nomad/jobs/variable/www/nginx",
        "RequestTime": 875792
    }
}
```

As with the tabular version, provide the `QueryMeta.NextToken` value as the
`-page-token` value to fetch the next page.

## General options

@include 'general_options.mdx'

[variable]: /nomad/docs/concepts/variables
[ACL Policy]: /nomad/docs/other-specifications/acl-policy#variables