---
layout: commands
page_title: 'Commands: Catalog List Nodes'
description: >-
  The `consul catalog nodes` command returns all known nodes and metadata about them. It can also query nodes that host a particular service or contain specific metadata.
---

# Consul Catalog List Nodes

Command: `consul catalog nodes`

Corresponding HTTP API Endpoint: [\[GET\] /v1/catalog/nodes](/consul/api-docs/catalog#list-nodes)

The `catalog nodes` command prints all known nodes and metadata about them.
It can also query for nodes that match a particular metadata or provide a
particular service.

The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of
[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching)
are not supported from commands, but may be from the corresponding HTTP endpoint.

| ACL Required |
| ------------ |
| `node:read`  |

## Examples

List all nodes:

```shell-session
$ consul catalog nodes
Node       ID        Address    DC
worker-01  1b662d97  10.4.5.31  dc1
```

Print detailed node information such as tagged addresses and node metadata:

```shell-session
$ consul catalog nodes -detailed
Node       ID                                    Address    DC   TaggedAddresses               Meta
worker-01  1b662d97-8b5c-3cc2-0ac0-96f55ad423b5  10.4.5.31  dc1  lan=10.4.5.31, wan=10.4.5.31
```

List nodes which provide the service name "web":

```shell-session
$ consul catalog nodes -service=web
Node       ID                                    Address    DC   TaggedAddresses               Meta
worker-01  1b662d97-8b5c-3cc2-0ac0-96f55ad423b5  10.4.5.31  dc1  lan=10.4.5.31, wan=10.4.5.31
```

Sort the resulting node list by estimated round trip time to worker-05:

```shell-session
$ consul catalog nodes -near=web-05
Node       ID                                    Address     DC   TaggedAddresses                Meta
worker-01  1b662d97-8b5c-3cc2-0ac0-96f55ad423b5  10.4.5.31   dc1  lan=10.4.5.31, wan=10.4.5.31
worker-02  d407a592-e93c-4d8e-8a6d-aba853d1e067  10.4.4.158  dc1  lan=10.4.4.158, wan=10.4.4.158
```

## Usage

Usage: `consul catalog nodes [options]`

#### Command Options

- `-detailed` - Output detailed information about the nodes including their
  addresses and metadata.

- `-near=<string>`- Node name to sort the node list in ascending order based on
  estimated round-trip time from that node. Passing `"_agent"` will use this
  agent's node for sorting.

- `-node-meta=<key=value>` - Metadata to filter nodes with the given key=value
  pairs. This flag may be specified multiple times to filter on multiple sources
  of metadata.

- `-service=<id or name>` - Service id or name to filter nodes. Only nodes
  which are providing the given service will be returned.

- `-filter=<filter>` - Expression to use for filtering the results. Can be passed
  via stdin by using `-` for the value or from a file by passing `@<file path>`.
  See the [`/catalog/nodes` API documentation](/consul/api-docs/catalog#filtering) for a
  description of what is filterable.

#### Enterprise Options

@include 'cli-http-api-partition-options.mdx'

#### API Options

@include 'http_api_options_client.mdx'

@include 'http_api_options_server.mdx'