--- layout: commands page_title: 'Commands: Catalog List Nodes' --- # Consul Catalog List Nodes Command: `consul catalog nodes` Corresponding HTTP API Endpoint: [\[GET\] /v1/catalog/nodes](/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](/api#authentication). Configuration of [blocking queries](/api/features/blocking) and [agent caching](/api/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]` #### API Options @include 'http_api_options_client.mdx' @include 'http_api_options_server.mdx' #### Catalog List Nodes Options - `-detailed` - Output detailed information about the nodes including their addresses and metadata. - `-near=`- 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=` - 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=` - Service id or name to filter nodes. Only nodes which are providing the given service will be returned. - `-filter=` - Expression to use for filtering the results. Can be passed via stdin by using `-` for the value or from a file by passing `@`. See the [`/catalog/nodes` API documentation](/api/catalog#filtering) for a description of what is filterable. #### Enterprise Options @include 'http_api_partition_options.mdx'