This feature introduces a new CLI command called list-nodes, designed to help Jenkins users and administrators retrieve information about Jenkins nodes (both controller and agents) directly from the command line.

Why This Command Is Useful

In Jenkins environments with many nodes or dynamic infrastructure, it's important to quickly understand the state of your agents. Currently, this often requires custom scripts or using the web UI. The list-nodes command solves this by providing:

• Quick summaries of online/offline status
• Flexible filters for labels, executors, and other node properties
• Support for JSON and plain-text output, useful for scripts and automation
• Verbose output to help with troubleshooting, including OS, Java version, and more

Key Command Options

• -status <ONLINE|OFFLINE|ALL>: Filter by node status (default is ALL)
• -labels <label1,label2,...>: Filter by comma-separated labels
• -labels-mode <ANY | ALL>: Match nodes with any or all of the specified labels
• -min-executors <N>: Only include nodes with at least N executors
• -exclude-controller: Skip the controller (master) node
• -limit <N>: Limit the number of nodes in the result
• -format <PLAIN | JSON>: Choose plain-text (default) or JSON output
• -verbose: Show detailed info like OS, architecture, Java version (requires Extended Read permission)
• -name-only: Output only node names
• -count-only: Output only the number of matching nodes

Permissions

• Jenkins.READ is required to use the command
• Computer.EXTENDED_READ is required for verbose node details
  If not granted, those fields will show “Permission Denied”

Example Use Cases

• list-nodes -status OFFLINE: Find nodes that are offline
• list-nodes -labels docker,gpu -labels-mode ANY: Find nodes with either docker or gpu
• list-nodes -count-only -exclude-controller: Count agent nodes only
• list-nodes -verbose -labels linux: See detailed info for Linux nodes

Testing and Validation

This feature includes a dedicated test class ListNodesCommandTest that covers:

• All supported options and combinations
• Edge cases (invalid input, no results)
• JSON output format validation
• Permission-based access control for verbose data

The goal is to provide a robust, well-tested command that simplifies node management via CLI and can help with scripting, monitoring, and automation workflows.