consortium

Imported from olivecasazza/consortium (skills/consortium/SKILL.md). Install upstream with npx skills add olivecasazza/consortium --skill consortium. Copyright stays with the author (LGPL-2.1-or-later).

consortium

consortium is a Rust rewrite of ClusterShell plus a NixOS fleet-deploy layer. One package, consortium-cli, ships six binaries. claw, molt, and pinch keep the frozen upstream ClusterShell short-flag sets (clush, clubak, and cluset/nodeset respectively), so an existing muscle-memory command usually transfers unchanged.

When to use which binary

claw flag surface

Node selection syntax

The -w, -x, and -X values use the ClusterShell nodeset language:

claw resolves its sources in a fixed order, and the order decides which subtraction wins:

1. -w nodeset.
2. -a and -g groups, then -X exclusions.
3. --hostfile entries.
4. -x exclusions.
5. --pick N trim.

The sources union together. -X is only consulted when -g or -a is also present, so claw -w 'node[1-8]' -X gpu removes nothing. Use -x for a plain subtraction. If the set ends up empty, claw exits with no target nodes specified (use -w, -a, -g, or --hostfile).

Output modes: -b, -L, and -q

| Mode | Behavior | | default | Streams each line as it completes, prefixed with its node label unless -N is set. A progress bar appears on stderr when stderr is a TTY and more than one node is targeted. | | -b, --dshbak | Buffers instead of streaming, then prints one header per group of nodes that produced identical output, largest group first, with a folded bracket header and a node count. | | -L, --line | Line mode, no output gathering. | | -q, --quiet | No stdout, no progress bar, no per-node return-code lines. The exit code is the only signal. |

Non-zero return codes and per-node timeouts are reported on stderr in every mode except -q, one folded node set per message.

How claw builds the remote command

For every target node, claw assembles one line and hands it to sh -c:

<remote> <options> -o ConnectTimeout=<t> [<user>@]%h '<shell-escaped command>'

%h is substituted with the node name before the shell sees the line, and the command is single-quoted unless it needs no quoting. With claw -w node1 uptime and no other flags that expands to ssh node1 uptime.

Two flags control the transport.

--remote swaps the transport binary

--remote replaces the ssh binary itself. The replacement still receives the same -o … [user@]%h 'cmd' arguments, so a short wrapper can add site policy without touching ssh configuration:

#!/bin/sh
exec /usr/bin/ssh -o ProxyCommand="ssh -W %h:%p jump-host.example.com" "$@"

claw -w 'node[1-8]' -f 16 -t 10 --remote /usr/local/bin/cluster-ssh uptime

Because the wrapper hides the %h from claw, ssh expands it itself. Either route lands on the same destination.

--options passes ssh options verbatim

--options is inserted into the command line exactly as given, so the value must carry the leading -o itself:

claw -w 'node[1-8]' -f 16 -t 10 --options='-o BatchMode=yes' uptime

The --options=-F… gotcha

A value that starts with a hyphen must be attached with =. Written space-separated, clap reads the next token as another set of short flags: claw --options -F/etc/ssh/cluster_config sets claw's own -F output format and never passes the config file. The same applies to any hyphen-leading value, including a ProxyCommand naming a flag-like path.

claw -w 'node[1-4]' --options=-F/etc/ssh/cluster_config hostname

Multi-hop with ProxyCommand and %h

Because %h is substituted with the node name before the shell runs, a %h inside a ProxyCommand value resolves to the node being targeted. Quote the inner value so the shell hands ssh one argument:

claw -w 'node[1-8]' -f 16 -t 10 \
  --options='-o ProxyCommand="ssh -W %h:%p jump-host.example.com"' \
  systemctl is-system-running

For node1 that assembles ssh -o ProxyCommand="ssh -W node1:22 jump-host.example.com" -o ConnectTimeout=10 node1 'systemctl is-system-running'.

The same pattern belongs in ~/.ssh/config when the jump host is permanent; see references/cli-surface.md for a two-block snippet and the ssh -G check that proves the hop does not recurse through itself.

Groups and groups.conf

-g, -X, -a, and every pinch group query read groups.conf, loaded from ~/.config/clustershell/groups.conf then /etc/clustershell/groups.conf. Both are read when both exist, and a section defined in both resolves from the one read last, the system file. Every section other than [Main] becomes a group source and needs a map or mapall upcall or the load fails. With neither file present, group-based selection fails with no groups.conf found (checked ~/.config/clustershell/ and /etc/clustershell/); pure -w and --hostfile runs need no config file at all.

Exit codes

Use -S in scripts that must distinguish, say, a missing binary (127) from a failed health check (1). Use the default in if claw …; then guards, where any non-zero is a failure. -q and -S compose cleanly for a status sweep that prints nothing and still reports the worst status.

Reference

references/cli-surface.md carries the per-binary argument reference and a copy-pasteable jump-host ssh_config snippet.