clustershell · thiell · Jun 27, 2026 · Jun 25, 2026
diff --git a/bash_completion.d/cluset b/bash_completion.d/cluset
@@ -40,7 +40,7 @@ _cluset()
 	done
 
 	case "$prev" in
-	-c|--count|-e|--expand|-f|--fold|\
+	-c|--count|-e|--expand|-f|--fold|--index|\
 	-x|--exclude|-i|--intersection|-X|--xor)
 		case "$cur" in
 		*:*)

diff --git a/doc/man/man1/cluset.1 b/doc/man/man1/cluset.1
@@ -88,6 +88,9 @@ list node groups from all group sources (\fB\-LL\fP shows nodes and \fB\-LLL\fP
 .B  \-r\fP,\fB  \-\-regroup
 fold nodes using node groups (see \-s \fIGROUPSOURCE\fP)
 .TP
+.BI \-\-index\fB= NODE
+output the index of NODE in the nodeset (reverse of \-I/\-\-slice)
+.TP
 .B  \-\-groupsources
 list all active group sources (see \fBgroups.conf\fP(5))
 .UNINDENT

diff --git a/doc/man/man1/nodeset.1 b/doc/man/man1/nodeset.1
@@ -88,6 +88,9 @@ list node groups from all group sources (\fB\-LL\fP shows nodes and \fB\-LLL\fP
 .B  \-r\fP,\fB  \-\-regroup
 fold nodes using node groups (see \-s \fIGROUPSOURCE\fP)
 .TP
+.BI \-\-index\fB= NODE
+output the index of NODE in the nodeset (reverse of \-I/\-\-slice)
+.TP
 .B  \-\-groupsources
 list all active group sources (see \fBgroups.conf\fP(5))
 .UNINDENT

diff --git a/doc/sphinx/tools/cluset.rst b/doc/sphinx/tools/cluset.rst
@@ -601,6 +601,66 @@ the resulting node set (or from the resulting range set with ``-R``)::
     node[11,13]
 
 
+.. _cluset-index:
+
+Finding the index of a node
+"""""""""""""""""""""""""""
+
+The ``--index`` command is the reverse of :ref:`slicing <cluset-slice>`:
+instead of selecting a node by its position, it outputs the zero-based index
+of a node within the resulting (ordered) node set. It is the command-line
+equivalent of the :meth:`.NodeSet.index` method::
+
+    $ cluset --index node5 node[0-9]
+    5
+
+If the node is not part of the set, an error is printed and a non-zero exit
+status is returned, so ``--index`` can also be used to test set membership::
+
+    $ cluset --index node42 node[0-9]
+    ERROR: 'node42' is not in nodeset
+
+It also works in range set mode with ``-R``::
+
+    $ cluset -R --index 18 1,5,18-31
+    2
+
+The position follows the same ordering as ``-e/--expand``. Two aspects of that
+ordering are worth knowing, as both can be surprising. First, when a node set
+spans several distinct patterns (different name templates), the patterns are
+sorted alphabetically by name, not by the order they were written or by the
+numbers they contain::
+
+    $ cluset -e node[1-4],bmc[10-20]
+    bmc10 bmc11 bmc12 bmc13 bmc14 bmc15 bmc16 bmc17 bmc18 bmc19 bmc20 node1 node2 node3 node4
+    $ cluset --index bmc10 node[1-4],bmc[10-20]
+    0
+    $ cluset --index node1 node[1-4],bmc[10-20]
+    11
+
+Second, for multidimensional node sets, the set is traversed as a cartesian
+product in which the last dimension varies fastest::
+
+    $ cluset -e rack[1-2]node[1-3]
+    rack1node1 rack1node2 rack1node3 rack2node1 rack2node2 rack2node3
+    $ cluset --index rack2node1 rack[1-2]node[1-3]
+    3
+
+For a one-dimensional node set (for example ``node[01-04]``) the index is just
+the node's ascending numeric position. A multidimensional node set has no
+single obvious order, so ClusterShell flattens it using its own convention,
+which is not guaranteed across versions; do not rely on a given index over
+time. Within a version it is always deterministic and depends only on the
+set's contents.
+
+.. note::
+
+   ``--index`` reflects ClusterShell's own ordering, so for a multidimensional
+   node list it is not guaranteed to match the node rank a resource manager
+   assigns (such as Slurm's ``$SLURM_NODEID``); use the value the resource
+   manager provides instead.
+
+
 .. _cluset-groups:
 
 Node groups
@@ -1015,7 +1075,7 @@ Arithmetic and special operations
 """""""""""""""""""""""""""""""""
 
 All arithmetic operations, as seen for node sets (cf.
-:ref:`cluset-arithmetic`:), are available for range sets, for example::
+:ref:`cluset-arithmetic`), are available for range sets, for example::
 
     $ cluset -fR 1-14 -x 10-20
     1-9
@@ -1035,8 +1095,8 @@ sets (cf. :ref:`cluset-extended-patterns`). However, as the union operator
 
 
 Besides arithmetic operations, special operations may be very convenient for
-range sets also (cf. :ref:`cluset-special`:).
-Below is an example with ``-I / --slice`` (cf. :ref:`cluset-slice`:)::
+range sets also (cf. :ref:`cluset-special`).
+Below is an example with ``-I / --slice`` (cf. :ref:`cluset-slice`)::
 
     $ cluset -fR -I 0 100-131
     100

diff --git a/doc/sphinx/tools/nodeset.rst b/doc/sphinx/tools/nodeset.rst
@@ -441,6 +441,8 @@ on a predefined node count, splitting non-contiguous subsets, choosing fold
 axis (for multidimensional node sets) and picking N nodes randomly. They are
 all explained below.
 
+.. _nodeset-slice:
+
 Slicing
 """""""
 
@@ -598,6 +600,66 @@ the resulting node set (or from the resulting range set with ``-R``)::
     node[11,13]
 
 
+.. _nodeset-index:
+
+Finding the index of a node
+"""""""""""""""""""""""""""
+
+The ``--index`` command is the reverse of :ref:`slicing <nodeset-slice>`:
+instead of selecting a node by its position, it outputs the zero-based index
+of a node within the resulting (ordered) node set. It is the command-line
+equivalent of the :meth:`.NodeSet.index` method::
+
+    $ nodeset --index node5 node[0-9]
+    5
+
+If the node is not part of the set, an error is printed and a non-zero exit
+status is returned, so ``--index`` can also be used to test set membership::
+
+    $ nodeset --index node42 node[0-9]
+    ERROR: 'node42' is not in nodeset
+
+It also works in range set mode with ``-R``::
+
+    $ nodeset -R --index 18 1,5,18-31
+    2
+
+The position follows the same ordering as ``-e/--expand``. Two aspects of that
+ordering are worth knowing, as both can be surprising. First, when a node set
+spans several distinct patterns (different name templates), the patterns are
+sorted alphabetically by name, not by the order they were written or by the
+numbers they contain::
+
+    $ nodeset -e node[1-4],bmc[10-20]
+    bmc10 bmc11 bmc12 bmc13 bmc14 bmc15 bmc16 bmc17 bmc18 bmc19 bmc20 node1 node2 node3 node4
+    $ nodeset --index bmc10 node[1-4],bmc[10-20]
+    0
+    $ nodeset --index node1 node[1-4],bmc[10-20]
+    11
+
+Second, for multidimensional node sets, the set is traversed as a cartesian
+product in which the last dimension varies fastest::
+
+    $ nodeset -e rack[1-2]node[1-3]
+    rack1node1 rack1node2 rack1node3 rack2node1 rack2node2 rack2node3
+    $ nodeset --index rack2node1 rack[1-2]node[1-3]
+    3
+
+For a one-dimensional node set (for example ``node[01-04]``) the index is just
+the node's ascending numeric position. A multidimensional node set has no
+single obvious order, so ClusterShell flattens it using its own convention,
+which is not guaranteed across versions; do not rely on a given index over
+time. Within a version it is always deterministic and depends only on the
+set's contents.
+
+.. note::
+
+   ``--index`` reflects ClusterShell's own ordering, so for a multidimensional
+   node list it is not guaranteed to match the node rank a resource manager
+   assigns (such as Slurm's ``$SLURM_NODEID``); use the value the resource
+   manager provides instead.
+
+
 .. _nodeset-groups:
 
 Node groups
@@ -1031,7 +1093,7 @@ sets (cf. :ref:`nodeset-extended-patterns`). However, as the union operator
 
 Besides arithmetic operations, special operations may be very convenient for
 range sets also. Below is an example with ``-I / --slice`` (cf.
-nodeset-slice)::
+:ref:`nodeset-slice`)::
 
     $ nodeset -fR -I 0 100-131
     100

diff --git a/doc/txt/cluset.txt b/doc/txt/cluset.txt
@@ -50,6 +50,7 @@ OPTIONS
     -l, --list          list node groups, list node groups and nodes (``-ll``) or list node groups, nodes and node count (``-lll``). When no argument is specified at all, this command will list all node group names found in selected group source (see also -s *GROUPSOURCE*). If any nodesets are specified as argument, this command will find node groups these nodes belongs to (individually). Optionally for each group, the fraction of these nodes being member of the group may be displayed (with ``-ll``), and also member count/total group node count (with ``-lll``). If a single hyphen-minus (-) is given as a nodeset, it will be read from standard input.
     -L, --list-all      list node groups from all group sources (``-LL`` shows nodes and ``-LLL`` adds node count). Like ``-l``, if any nodesets are specified as argument, this command will find node groups these nodes belongs to (individually).
     -r, --regroup       fold nodes using node groups (see -s *GROUPSOURCE*)
+    --index=NODE        output the index of NODE in the nodeset (reverse of -I/--slice)
     --groupsources      list all active group sources (see ``groups.conf``\(5))
 
   Operations:

diff --git a/doc/txt/nodeset.txt b/doc/txt/nodeset.txt
@@ -50,6 +50,7 @@ OPTIONS
     -l, --list          list node groups, list node groups and nodes (``-ll``) or list node groups, nodes and node count (``-lll``). When no argument is specified at all, this command will list all node group names found in selected group source (see also -s *GROUPSOURCE*). If any nodesets are specified as argument, this command will find node groups these nodes belongs to (individually). Optionally for each group, the fraction of these nodes being member of the group may be displayed (with ``-ll``), and also member count/total group node count (with ``-lll``). If a single hyphen-minus (-) is given as a nodeset, it will be read from standard input.
     -L, --list-all      list node groups from all group sources (``-LL`` shows nodes and ``-LLL`` adds node count). Like ``-l``, if any nodesets are specified as argument, this command will find node groups these nodes belongs to (individually).
     -r, --regroup       fold nodes using node groups (see -s *GROUPSOURCE*)
+    --index=NODE        output the index of NODE in the nodeset (reverse of -I/--slice)
     --groupsources      list all active group sources (see ``groups.conf``\(5))
 
   Operations:

diff --git a/lib/ClusterShell/CLI/Nodeset.py b/lib/ClusterShell/CLI/Nodeset.py
@@ -176,7 +176,8 @@ def nodeset():
     cmdcount = int(options.count) + int(options.expand) + \
                int(options.fold) + int(bool(options.list)) + \
                int(bool(options.listall)) + int(options.regroup) + \
-               int(options.groupsources) + int(options.completion)
+               int(options.groupsources) + int(options.completion) + \
+               int(options.index is not None)
     if not cmdcount:
         parser.error("No command specified.")
     elif cmdcount > 1:
@@ -198,6 +199,9 @@ def nodeset():
     if options.axis and (not options.fold or options.rangeset):
         parser.error("--axis option is only supported when folding nodeset")
 
+    if options.index is not None and options.pick:
+        parser.error("--index cannot be combined with --pick")
+
     if options.groupsource and not options.quiet and class_set == RangeSet:
         print("WARNING: option group source \"%s\" ignored"
               % options.groupsource, file=sys.stderr)
@@ -312,6 +316,11 @@ def nodeset():
 
     fmt = options.output_format # default to '%s'
 
+    # --index outputs the position of a node in the set (reverse of -I/--slice)
+    if options.index is not None:
+        print(fmt % xset.index(options.index))
+        return
+
     # Display result according to command choice
     if options.expand:
         xsubres = lambda x: separator.join((fmt % s for s in x.striter()))

diff --git a/lib/ClusterShell/CLI/OptionParser.py b/lib/ClusterShell/CLI/OptionParser.py
@@ -279,6 +279,9 @@ def install_nodeset_commands(self):
                           dest="regroup", default=False,
                           help="fold nodes using node groups (see -s "
                                "GROUPSOURCE)")
+        optgrp.add_option("--index", action="store", dest="index",
+                          metavar="NODE", type="string",
+                          help="output the index of NODE in the nodeset")
         optgrp.add_option("--list-sources", "--groupsources",
                           action="store_true", dest="groupsources",
                           default=False,

diff --git a/tests/CLINodesetTest.py b/tests/CLINodesetTest.py
@@ -573,6 +573,106 @@ def test_025_pick(self):
             self._nodeset_t(["--count", "--pick", str(num), "-R", "1-100"],
                             None, str(num).encode() + b'\n')
 
+    def test_026_index(self):
+        """test nodeset --index"""
+        self._nodeset_t(["--index", "node0", "node[0-9]"], None, b"0\n")
+        self._nodeset_t(["--index", "node5", "node[0-9]"], None, b"5\n")
+        self._nodeset_t(["--index", "node9", "node[0-9]"], None, b"9\n")
+        # --index is the reverse of -I/--slice
+        self._nodeset_t(["--index", "bar34", "bar[34-68,89-90]"], None, b"0\n")
+        self._nodeset_t(["--index", "bar42", "bar[34-68,89-90]"], None, b"8\n")
+        self._nodeset_t(["--index", "bar89", "bar[34-68,89-90]"], None, b"35\n")
+        self._nodeset_t(["--index", "bar90", "bar[34-68,89-90]"], None, b"36\n")
+        # several patterns: sorted alphabetically by name, not input order
+        self._nodeset_t(["--index", "bmc10", "node[1-4],bmc[10-20]"], None,
+                        b"0\n")
+        self._nodeset_t(["--index", "node1", "node[1-4],bmc[10-20]"], None,
+                        b"11\n")
+        # nD nodeset
+        self._nodeset_t(["--index", "da34p1", "da[30,34-51]p[1-2]"], None,
+                        b"2\n")
+        # zero-padding is significant
+        self._nodeset_t(["--index", "prune003", "prune[003-034]"], None, b"0\n")
+        self._nodeset_t(["--index", "prune034", "prune[003-034]"], None,
+                        b"31\n")
+        self._nodeset_t(["--index", "prune3", "prune[003-034]"], None, b"", 1,
+                        b"ERROR: 'prune3' is not in nodeset\n")
+        # read the set from stdin
+        self._nodeset_t(["--index", "node5"], "node[0-9]\n", b"5\n")
+        # honor -O output format
+        self._nodeset_t(["--index", "node5", "-O", "idx=%s", "node[0-9]"],
+                        None, b"idx=5\n")
+        # set operations are applied before the lookup
+        self._nodeset_t(["--index", "node5", "node[0-9]", "-x", "node0"], None,
+                        b"4\n")
+        # -I/--slice is a transform like any other: --index sees the sliced set
+        self._nodeset_t(["--index", "node3", "-I", "0-4", "node[0-9]"], None,
+                        b"3\n")
+        self._nodeset_t(["--index", "node7", "-I", "0-4", "node[0-9]"], None,
+                        b"", 1, b"ERROR: 'node7' is not in nodeset\n")
+        # missing node: ValueError -> exit 1 (like list.index())
+        self._nodeset_t(["--index", "node42", "node[0-9]"], None, b"", 1,
+                        b"ERROR: 'node42' is not in nodeset\n")
+        # a single node is required
+        self._nodeset_t(["--index", "node[1-2]", "node[0-9]"], None, b"", 1,
+                        b"ERROR: index() argument must be a single node\n")
+        # --index is a command: incompatible with other commands and --pick
+        self._nodeset_t(["--index", "node5", "-c", "node[0-9]"], None, None, 2,
+                        b"Multiple commands not allowed.\n")
+        self._nodeset_t(["--index", "node5", "--pick", "2", "node[0-9]"], None,
+                        None, 2, b"--index cannot be combined with --pick\n")
+
+    def test_027_index_rangeset(self):
+        """test nodeset --index (rangeset mode)"""
+        self._nodeset_t(["-R", "--index", "5", "0-9"], None, b"5\n")
+        self._nodeset_t(["-R", "--index", "200", "0-100,200"], None, b"101\n")
+        self._nodeset_t(["-R", "--index", "18", "1,5,18-31"], None, b"2\n")
+        # zero-padding is significant
+        self._nodeset_t(["-R", "--index", "09", "08-10"], None, b"1\n")
+        # read the set from stdin
+        self._nodeset_t(["-R", "--index", "5"], "0-9\n", b"5\n")
+        # missing element: ValueError -> exit 1
+        self._nodeset_t(["-R", "--index", "50", "0-9"], None, b"", 1,
+                        b"ERROR: 50 is not in RangeSet\n")
+
+    def test_028_index_nd(self):
+        """test nodeset --index (multidimensional ordering)"""
+        # nD flattening is a cartesian product where the LAST dimension
+        # varies fastest; --index round-trips with -e/expand for every node.
+        # 2-D: da[1-2]p[1-3] expands da1p1 da1p2 da1p3 da2p1 da2p2 da2p3
+        nd2 = "da[1-2]p[1-3]"
+        for idx, node in enumerate(["da1p1", "da1p2", "da1p3",
+                                    "da2p1", "da2p2", "da2p3"]):
+            self._nodeset_t(["--index", node, nd2], None,
+                            ("%d\n" % idx).encode())
+        # 3-D: a[1-2]b[1-2]c[1-2] expands a1b1c1 a1b1c2 a1b2c1 a1b2c2
+        #      a2b1c1 a2b1c2 a2b2c1 a2b2c2 (c least significant, a most)
+        nd3 = "a[1-2]b[1-2]c[1-2]"
+        for idx, node in enumerate(["a1b1c1", "a1b1c2", "a1b2c1", "a1b2c2",
+                                    "a2b1c1", "a2b1c2", "a2b2c1", "a2b2c2"]):
+            self._nodeset_t(["--index", node, nd3], None,
+                            ("%d\n" % idx).encode())
+        # rightmost axis varies fastest: p cycles fully before da increments
+        self._nodeset_t(["--index", "da1p1", nd2], None, b"0\n")
+        self._nodeset_t(["--index", "da1p3", nd2], None, b"2\n")
+        self._nodeset_t(["--index", "da2p1", nd2], None, b"3\n")
+        self._nodeset_t(["--index", "da2p3", nd2], None, b"5\n")
+        # last axis is least significant (a1b1c1=0 .. a2b2c2=7)
+        self._nodeset_t(["--index", "a1b1c2", nd3], None, b"1\n")
+        self._nodeset_t(["--index", "a1b2c1", nd3], None, b"2\n")
+        self._nodeset_t(["--index", "a2b1c1", nd3], None, b"4\n")
+        self._nodeset_t(["--index", "a2b2c2", nd3], None, b"7\n")
+        # several vectors in one pattern: larger vector emitted first.
+        # da[1-2]p[1-3] (6 elts) precedes da[5-6]p[1-2] (4 elts)
+        nd2v = "da[1-2]p[1-3],da[5-6]p[1-2]"
+        for idx, node in enumerate(["da1p1", "da1p2", "da1p3",
+                                    "da2p1", "da2p2", "da2p3",
+                                    "da5p1", "da5p2", "da6p1", "da6p2"]):
+            self._nodeset_t(["--index", node, nd2v], None,
+                            ("%d\n" % idx).encode())
+        self._nodeset_t(["--index", "da5p1", nd2v], None, b"6\n")
+        self._nodeset_t(["--index", "da6p2", nd2v], None, b"9\n")
+
 
 class CLINodesetGroupResolverTest1(CLINodesetTestBase):
     """Unit test class for testing CLI/Nodeset.py with custom Group Resolver"""