consul catalog services: List Registered Services
consul catalog services lists every service name registered in the catalog for the datacenter.
Where services register shows the write side, catalog services is the read side: a deploy smoke test can assert the expected service shows up after registration.
What it does
consul catalog services queries the cluster catalog and lists distinct service names. -tags adds the tags per service. Unlike consul members (gossip membership), this reflects the registered service catalog across all nodes.
Common usage
consul catalog services
consul catalog services -tags
# only services on a given node
consul catalog services -node=web-1
consul catalog services -node-meta=env=prodOptions
| Flag | What it does |
|---|---|
| -tags | Show the tags associated with each service |
| -node <node> | List services registered on a specific node |
| -node-meta <k>=<v> | Filter by node metadata |
| -datacenter <dc> | Query a specific datacenter |
In CI
After a deploy, grep this list for the service name as a quick smoke test that registration succeeded. For health (not just presence) use consul catalog nodes -service=<name> or the health API; the catalog lists registered services regardless of check status.
Common errors in CI
"Error listing services: Unexpected response code: 403 (Permission denied)" means the token lacks service:read. "No path to datacenter" means -datacenter names a datacenter not reachable over the WAN. An empty list right after registering usually means you registered with a different agent or datacenter than you are querying.