multiSSH3 6.26__tar.gz → 6.29__tar.gz

{multissh3-6.26 → multissh3-6.29}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: multiSSH3
-Version: 6.26
+Version: 6.29
 Summary: Run commands on multiple hosts via SSH
 Home-page: https://github.com/yufei-pan/multiSSH3
 Author: Yufei Pan
@@ -13,8 +13,6 @@ Classifier: Operating System :: MacOS
 Classifier: Operating System :: Microsoft :: Windows
 Requires-Python: >=3.6
 Description-Content-Type: text/markdown
-Requires-Dist: argparse
-Requires-Dist: ipaddress
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
@@ -22,7 +20,6 @@ Dynamic: description
 Dynamic: description-content-type
 Dynamic: home-page
 Dynamic: license
-Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
 
@@ -168,13 +165,18 @@ to print the help message with current default values.
 Defaults are read from the following chain map stored as json files, top ones overwrite the bottom ones.:
 | `CONFIG_FILE_CHAIN`                        |
 | ------------------------------------------ |
-| `./multiSSH3.config.json`                  |
 | `~/multiSSH3.config.json`                  |
 | `~/.multiSSH3.config.json`                 |
 | `~/.config/multiSSH3/multiSSH3.config.json`|
 | `/etc/multiSSH3.d/multiSSH3.config.json`   |
 | `/etc/multiSSH3.config.json`               |
 
+> The current directory is not searched: a cloned repo or an unpacked archive could otherwise change any setting, including which `ssh` runs. Use `--config_file` to load a config file from there; mssh prints a note when `./multiSSH3.config.json` exists (read automatically up to 6.26).
+>
+> Config and env files found on these default paths are only loaded when they are owned by you or root and nobody else can write to them (group write is fine when the group is your own private group). Others are skipped with a warning that shows the `chmod` fix. Files you name with `--config_file`, `--env_file` or `--env_files` are always loaded.
+>
+> `--store_config_file` writes the file readable by you only (`0600`), as it can hold passwords. The `/etc` locations above are written `0644` so every user can read them. An existing file's permissions are only ever tightened, and a file whose permissions cannot be restricted is left untouched (the config is printed instead).
+
 ### Generating / Storing Config File
 To store / generate a config file with the current command line options, you can use
 ```bash
@@ -188,7 +190,7 @@ mssh --store_config_file [STORE_CONFIG_FILE_PATH]
 >
 >`--generate_config_file` will output to stdout if `--config_file` is not specified. 
 
-> Use `--store_config_file` without a path will store to `multiSSH3.config.json` in the current working directory.
+> Without a path, `--store_config_file` writes to the config file mssh loaded, or to `~/.multiSSH3.config.json` if none was loaded.
 
 You can modify the json file or use command line arguments to update values and store them as defaults.
 ```bash
@@ -200,7 +202,7 @@ will store
 "DEFAULT_CLI_TIMEOUT": "180"
 ...
 ```
-into `./multiSSH3.config.json`
+into `~/.multiSSH3.config.json` (or the config file mssh loaded)
 
 
 > If you want to store password, it will be a plain text password in this config file. This will be better to supply it everytime as a CLI argument but you should really consider setting up public-key authentication.
@@ -262,7 +264,8 @@ When hostname need to be resolved, mssh will check in the following order:
     - Redo the whole range -> hostname resolution logic with the resolved env variable value.
 - hostname is in map generated from env_file(s) specified by `--env_files ENV_FILES`
     - Redo the whole range -> hostname resolution logic with the resolved env variable value.
-- Lookup using `socket.gethostbyname()` to query dns server. ( Slow! )
+- Lookup using `socket.getaddrinfo()` to query dns server ( IPv4 preferred, IPv6 accepted ). Names are looked up in parallel.
+- If the ssh config (`ssh -G`) maps the name to another `HostName` or through a `ProxyJump` / `ProxyCommand`, it is valid ( `#IP#` uses the `HostName`'s address when it resolves ). A catch-all block such as `Host *` only counts when it gives the name a `HostName` that resolves (e.g. `HostName %h.corp.example`), so typos are still rejected.
 
 > TLDR:
 >
@@ -285,12 +288,11 @@ When hostname need to be resolved, mssh will check in the following order:
 | `~/.zshrc` |
 | `~/host.env` |
 | `~/hosts.env` |
-| `.env` |
-| `host.env` |
-| `hosts.env` |
 
 Later files take precedence over earlier files.
 
+> The current directory is not searched, as files there could redirect host aliases. Use `--env_files hosts.env` to add one. mssh points this out when a host name it cannot find is defined in `./.env`, `./host.env` or `./hosts.env` (read automatically up to 6.26).
+
 ### Example Env Hostname File
 
 An example hostname alias file will look like:
@@ -373,6 +375,60 @@ mssh will replace some magic strings in the command string with host specific va
 
 > Note: Resolved name is the IP / Hostname with user appended and ip prefix applied. This is what got used to connect to the host.
 
+## Autocomplete
+
+mssh completes hosts, options, option values and remote commands when you press TAB, in bash, zsh and fish.
+
+```bash
+mssh --completion install     # set it up for the shell you run this from
+mssh --completion uninstall   # remove it again
+mssh --completion bash        # or print the script (bash, zsh or fish)
+```
+
+- **Hosts:** host strings you typed before, env file aliases, `/etc/hosts`, ssh config `Host` entries, `known_hosts` and the ARP table. Large clusters are offered as ranges (`node[0001-2000]`) until what you typed narrows them down. Hosts mssh recently found unreachable come last.
+- **Options and values:** option names, and values you used before (`-u`, `-t`, ...). Paths complete as files. Passwords are never completed.
+- **Commands:** commands from your mssh history, the rest of a command from this machine's own completion (`mssh grp systemctl rest<TAB>`), and the magic strings (`#HOST#`, ...).
+
+Ranking uses the rest of the line on both sides of the cursor: after `mssh gpu[01-16] "` the commands you run on those hosts come first, and in the hosts of `mssh ▮ "systemctl restart slurmd"` the hosts you restarted slurmd on come first.
+
+Completion never removes what you typed, prints nothing, and falls back to the shell's normal completion when anything is slow or missing.
+
+It learns from an index of your history and hosts, kept in mssh's private cache directory (`$XDG_RUNTIME_DIR/multiSSH3` or `/tmp/multiSSH3-<uid>`) and rebuilt in the background when its sources change. `mssh-complete rebuild` rebuilds it now; `mssh-complete eval` replays your history and shows how much typing completion saves.
+
+### Grey suggestions
+
+While you type an mssh line, the most likely rest of it shows in grey after the cursor: the rest of the line when one past invocation clearly fits, only the rest of the current word when only that is clear, or the start every known value shares when none is (what TAB would insert), nothing when mssh is not sure. → (or End, Ctrl-F) takes all of it, Alt-→ / Ctrl-→ / Alt-F one word. Enter runs only what you typed.
+
+- **zsh:** built in; with [zsh-autosuggestions](https://github.com/zsh-users/zsh-autosuggestions) loaded, mssh becomes its first strategy on mssh lines.
+- **bash with [ble.sh](https://github.com/akinomyoga/ble.sh):** built in, as ble.sh's first suggestion source.
+- **plain bash (4.4 or later):** turn on the mssh line editor, which takes over after you type an mssh name and a space, and hands the line back to readline on any key it does not handle (↑, Ctrl-K, ...) or when you delete into `mssh `:
+
+  ```bash
+  mssh --completion install bash editor
+  ```
+
+  Installing again keeps it on; `mssh --completion uninstall bash`, then `mssh --completion install bash`, turns it off.
+
+- **fish:** fish's own suggestions already use mssh's completion.
+
+### Ctrl-R
+
+Ctrl-R on an mssh line opens a menu below the prompt with the candidates for the word under the cursor (hosts, commands for those hosts, option values), how often and how long ago you used them; Tab switches to whole past invocations. Type to filter, ↑/↓ to move, Enter to insert, Esc to leave the line as it was. On any other line Ctrl-R does what it did before (readline's search, fzf, atuin, ...).
+
+| Environment variable | Effect |
+| --- | --- |
+| `MSSH_COMPLETE_TIMEOUT` | Seconds the shell waits for an answer (default 0.3) |
+| `MSSH_COMPLETE_GHOST_TIMEOUT` | ble.sh only: milliseconds a grey suggestion may take (default 300) |
+| `MSSH_COMPLETE_SHELL_HISTORY` | Lines of shell history sent along (default 1000) |
+| `MSSH_COMPLETE_EDITOR` | `1` turns on the plain-bash mssh line editor (`install bash editor` sets it) |
+| `MSSH_COMPLETE_DEBUG` | `1` logs errors to `complete.log` in the cache directory |
+
+> Tested with bash 4.2 to 5.2, zsh 5.5 to 5.9 (with `compinit` loaded; zsh-autosuggestions 0.7.1), fish 3.3 to 4.0 and the 2026-09-08 ble.sh nightly. Since 6.28 mssh records hosts in its history as typed; older history lines hold them expanded.
+
+> After upgrading mssh, run `mssh --completion install` again to get the new shell glue. Glue from an older mssh keeps working, without the newer features.
+
+> The plain-bash editor binds the space key, so every space typed in bash runs a tiny shell function; Ctrl-R becomes a key macro (the binding it replaced is called for other lines). Uninstall restores both in new shells.
+
 ## Options
 
 Here details the options for multiSSH3 6.02 @ 2025-11-10
@@ -565,7 +621,7 @@ mssh -f ./data/ allServers /tmp/data/
 - Note: Timedout Hosts are considered unreachable.
 - By default mssh set this to true to speed up operations on large host lists with some unreachable hosts.
 - Unreachable hosts will be tried again when their timeout expires.
-- mssh stores the current run unreachable hosts in memory and if `skip_unreachable` is true, it will store them in a temperary file called __{username}_multiSSH3_UNAVAILABLE_HOSTS.csv in the system temp folder.
+- mssh stores the current run unreachable hosts in memory and if `skip_unreachable` is true, it will store them in `unavailable_hosts.csv` in `$XDG_RUNTIME_DIR/multiSSH3/`, or else in a private `multiSSH3-<uid>` folder in the system temp folder ( cleared at reboot ). If neither can be used, they are only kept for the current run.
 - To force mssh to not use unreachable hosts from previous runs, you can use `-a, -nsu, --no_skip_unreachable` to set `skip_unreachable` to false.
 
 ### `-a, -nsu, --no_skip_unreachable` | not _`DEFAULT_SKIP_UNREACHABLE`_
@@ -597,7 +653,7 @@ mssh -f ./data/ allServers /tmp/data/
 ### `--store_config_file [STORE_CONFIG_FILE]` | None
 - Store the current command line options to a config file.
 - Equivalent to `--generate_config_file --config_file [STORE_CONFIG_FILE]`
-- Outputs to `multiSSH3.config.json` in the current working directory if no path is specified.
+- Without a path, writes to the config file mssh loaded, or to `~/.multiSSH3.config.json` if none was loaded.
 
 ### `--debug` | False
 - Enable debug mode.
@@ -721,7 +777,7 @@ options:
   -ef, --env_file ENV_FILE
                         Replace the env file look up chain with this env_file. ( Still work with --no_env ) (default: None)
   -efs, --env_files ENV_FILES
-                        The files to load the mssh file based environment variables from. Can specify multiple. Load first to last. ( Still work with --no_env ) (default: ['/etc/profile.d/hosts.sh', '~/.bashrc', '~/.zshrc', '~/host.env', '~/hosts.env', '.env', 'host.env', 'hosts.env'])
+                        The files to load the mssh file based environment variables from. Can specify multiple. Load first to last. ( Still work with --no_env ) (default: ['/etc/profile.d/hosts.sh', '~/.bashrc', '~/.zshrc', '~/host.env', '~/hosts.env'])
   -m, --max_connections MAX_CONNECTIONS
                         Max number of connections to use (default: 4 * cpu_count)
   -j, --json            Output in json format. (default: False)
@@ -912,9 +968,6 @@ DEFAULT_ENV_FILES = ['/etc/profile.d/hosts.sh',
 					 '~/.zshrc',
 					 '~/host.env',
 					 '~/hosts.env',
-					 '.env',
-					 'host.env',
-					 'hosts.env',
 					 ]
 DEFAULT_NO_HISTORY = False
 DEFAULT_HISTORY_FILE = '~/.mssh_history'

{multissh3-6.26 → multissh3-6.29}/README.md

@@ -140,13 +140,18 @@ to print the help message with current default values.
 Defaults are read from the following chain map stored as json files, top ones overwrite the bottom ones.:
 | `CONFIG_FILE_CHAIN`                        |
 | ------------------------------------------ |
-| `./multiSSH3.config.json`                  |
 | `~/multiSSH3.config.json`                  |
 | `~/.multiSSH3.config.json`                 |
 | `~/.config/multiSSH3/multiSSH3.config.json`|
 | `/etc/multiSSH3.d/multiSSH3.config.json`   |
 | `/etc/multiSSH3.config.json`               |
 
+> The current directory is not searched: a cloned repo or an unpacked archive could otherwise change any setting, including which `ssh` runs. Use `--config_file` to load a config file from there; mssh prints a note when `./multiSSH3.config.json` exists (read automatically up to 6.26).
+>
+> Config and env files found on these default paths are only loaded when they are owned by you or root and nobody else can write to them (group write is fine when the group is your own private group). Others are skipped with a warning that shows the `chmod` fix. Files you name with `--config_file`, `--env_file` or `--env_files` are always loaded.
+>
+> `--store_config_file` writes the file readable by you only (`0600`), as it can hold passwords. The `/etc` locations above are written `0644` so every user can read them. An existing file's permissions are only ever tightened, and a file whose permissions cannot be restricted is left untouched (the config is printed instead).
+
 ### Generating / Storing Config File
 To store / generate a config file with the current command line options, you can use
 ```bash
@@ -160,7 +165,7 @@ mssh --store_config_file [STORE_CONFIG_FILE_PATH]
 >
 >`--generate_config_file` will output to stdout if `--config_file` is not specified. 
 
-> Use `--store_config_file` without a path will store to `multiSSH3.config.json` in the current working directory.
+> Without a path, `--store_config_file` writes to the config file mssh loaded, or to `~/.multiSSH3.config.json` if none was loaded.
 
 You can modify the json file or use command line arguments to update values and store them as defaults.
 ```bash
@@ -172,7 +177,7 @@ will store
 "DEFAULT_CLI_TIMEOUT": "180"
 ...
 ```
-into `./multiSSH3.config.json`
+into `~/.multiSSH3.config.json` (or the config file mssh loaded)
 
 
 > If you want to store password, it will be a plain text password in this config file. This will be better to supply it everytime as a CLI argument but you should really consider setting up public-key authentication.
@@ -234,7 +239,8 @@ When hostname need to be resolved, mssh will check in the following order:
     - Redo the whole range -> hostname resolution logic with the resolved env variable value.
 - hostname is in map generated from env_file(s) specified by `--env_files ENV_FILES`
     - Redo the whole range -> hostname resolution logic with the resolved env variable value.
-- Lookup using `socket.gethostbyname()` to query dns server. ( Slow! )
+- Lookup using `socket.getaddrinfo()` to query dns server ( IPv4 preferred, IPv6 accepted ). Names are looked up in parallel.
+- If the ssh config (`ssh -G`) maps the name to another `HostName` or through a `ProxyJump` / `ProxyCommand`, it is valid ( `#IP#` uses the `HostName`'s address when it resolves ). A catch-all block such as `Host *` only counts when it gives the name a `HostName` that resolves (e.g. `HostName %h.corp.example`), so typos are still rejected.
 
 > TLDR:
 >
@@ -257,12 +263,11 @@ When hostname need to be resolved, mssh will check in the following order:
 | `~/.zshrc` |
 | `~/host.env` |
 | `~/hosts.env` |
-| `.env` |
-| `host.env` |
-| `hosts.env` |
 
 Later files take precedence over earlier files.
 
+> The current directory is not searched, as files there could redirect host aliases. Use `--env_files hosts.env` to add one. mssh points this out when a host name it cannot find is defined in `./.env`, `./host.env` or `./hosts.env` (read automatically up to 6.26).
+
 ### Example Env Hostname File
 
 An example hostname alias file will look like:
@@ -345,6 +350,60 @@ mssh will replace some magic strings in the command string with host specific va
 
 > Note: Resolved name is the IP / Hostname with user appended and ip prefix applied. This is what got used to connect to the host.
 
+## Autocomplete
+
+mssh completes hosts, options, option values and remote commands when you press TAB, in bash, zsh and fish.
+
+```bash
+mssh --completion install     # set it up for the shell you run this from
+mssh --completion uninstall   # remove it again
+mssh --completion bash        # or print the script (bash, zsh or fish)
+```
+
+- **Hosts:** host strings you typed before, env file aliases, `/etc/hosts`, ssh config `Host` entries, `known_hosts` and the ARP table. Large clusters are offered as ranges (`node[0001-2000]`) until what you typed narrows them down. Hosts mssh recently found unreachable come last.
+- **Options and values:** option names, and values you used before (`-u`, `-t`, ...). Paths complete as files. Passwords are never completed.
+- **Commands:** commands from your mssh history, the rest of a command from this machine's own completion (`mssh grp systemctl rest<TAB>`), and the magic strings (`#HOST#`, ...).
+
+Ranking uses the rest of the line on both sides of the cursor: after `mssh gpu[01-16] "` the commands you run on those hosts come first, and in the hosts of `mssh ▮ "systemctl restart slurmd"` the hosts you restarted slurmd on come first.
+
+Completion never removes what you typed, prints nothing, and falls back to the shell's normal completion when anything is slow or missing.
+
+It learns from an index of your history and hosts, kept in mssh's private cache directory (`$XDG_RUNTIME_DIR/multiSSH3` or `/tmp/multiSSH3-<uid>`) and rebuilt in the background when its sources change. `mssh-complete rebuild` rebuilds it now; `mssh-complete eval` replays your history and shows how much typing completion saves.
+
+### Grey suggestions
+
+While you type an mssh line, the most likely rest of it shows in grey after the cursor: the rest of the line when one past invocation clearly fits, only the rest of the current word when only that is clear, or the start every known value shares when none is (what TAB would insert), nothing when mssh is not sure. → (or End, Ctrl-F) takes all of it, Alt-→ / Ctrl-→ / Alt-F one word. Enter runs only what you typed.
+
+- **zsh:** built in; with [zsh-autosuggestions](https://github.com/zsh-users/zsh-autosuggestions) loaded, mssh becomes its first strategy on mssh lines.
+- **bash with [ble.sh](https://github.com/akinomyoga/ble.sh):** built in, as ble.sh's first suggestion source.
+- **plain bash (4.4 or later):** turn on the mssh line editor, which takes over after you type an mssh name and a space, and hands the line back to readline on any key it does not handle (↑, Ctrl-K, ...) or when you delete into `mssh `:
+
+  ```bash
+  mssh --completion install bash editor
+  ```
+
+  Installing again keeps it on; `mssh --completion uninstall bash`, then `mssh --completion install bash`, turns it off.
+
+- **fish:** fish's own suggestions already use mssh's completion.
+
+### Ctrl-R
+
+Ctrl-R on an mssh line opens a menu below the prompt with the candidates for the word under the cursor (hosts, commands for those hosts, option values), how often and how long ago you used them; Tab switches to whole past invocations. Type to filter, ↑/↓ to move, Enter to insert, Esc to leave the line as it was. On any other line Ctrl-R does what it did before (readline's search, fzf, atuin, ...).
+
+| Environment variable | Effect |
+| --- | --- |
+| `MSSH_COMPLETE_TIMEOUT` | Seconds the shell waits for an answer (default 0.3) |
+| `MSSH_COMPLETE_GHOST_TIMEOUT` | ble.sh only: milliseconds a grey suggestion may take (default 300) |
+| `MSSH_COMPLETE_SHELL_HISTORY` | Lines of shell history sent along (default 1000) |
+| `MSSH_COMPLETE_EDITOR` | `1` turns on the plain-bash mssh line editor (`install bash editor` sets it) |
+| `MSSH_COMPLETE_DEBUG` | `1` logs errors to `complete.log` in the cache directory |
+
+> Tested with bash 4.2 to 5.2, zsh 5.5 to 5.9 (with `compinit` loaded; zsh-autosuggestions 0.7.1), fish 3.3 to 4.0 and the 2026-09-08 ble.sh nightly. Since 6.28 mssh records hosts in its history as typed; older history lines hold them expanded.
+
+> After upgrading mssh, run `mssh --completion install` again to get the new shell glue. Glue from an older mssh keeps working, without the newer features.
+
+> The plain-bash editor binds the space key, so every space typed in bash runs a tiny shell function; Ctrl-R becomes a key macro (the binding it replaced is called for other lines). Uninstall restores both in new shells.
+
 ## Options
 
 Here details the options for multiSSH3 6.02 @ 2025-11-10
@@ -537,7 +596,7 @@ mssh -f ./data/ allServers /tmp/data/
 - Note: Timedout Hosts are considered unreachable.
 - By default mssh set this to true to speed up operations on large host lists with some unreachable hosts.
 - Unreachable hosts will be tried again when their timeout expires.
-- mssh stores the current run unreachable hosts in memory and if `skip_unreachable` is true, it will store them in a temperary file called __{username}_multiSSH3_UNAVAILABLE_HOSTS.csv in the system temp folder.
+- mssh stores the current run unreachable hosts in memory and if `skip_unreachable` is true, it will store them in `unavailable_hosts.csv` in `$XDG_RUNTIME_DIR/multiSSH3/`, or else in a private `multiSSH3-<uid>` folder in the system temp folder ( cleared at reboot ). If neither can be used, they are only kept for the current run.
 - To force mssh to not use unreachable hosts from previous runs, you can use `-a, -nsu, --no_skip_unreachable` to set `skip_unreachable` to false.
 
 ### `-a, -nsu, --no_skip_unreachable` | not _`DEFAULT_SKIP_UNREACHABLE`_
@@ -569,7 +628,7 @@ mssh -f ./data/ allServers /tmp/data/
 ### `--store_config_file [STORE_CONFIG_FILE]` | None
 - Store the current command line options to a config file.
 - Equivalent to `--generate_config_file --config_file [STORE_CONFIG_FILE]`
-- Outputs to `multiSSH3.config.json` in the current working directory if no path is specified.
+- Without a path, writes to the config file mssh loaded, or to `~/.multiSSH3.config.json` if none was loaded.
 
 ### `--debug` | False
 - Enable debug mode.
@@ -693,7 +752,7 @@ options:
   -ef, --env_file ENV_FILE
                         Replace the env file look up chain with this env_file. ( Still work with --no_env ) (default: None)
   -efs, --env_files ENV_FILES
-                        The files to load the mssh file based environment variables from. Can specify multiple. Load first to last. ( Still work with --no_env ) (default: ['/etc/profile.d/hosts.sh', '~/.bashrc', '~/.zshrc', '~/host.env', '~/hosts.env', '.env', 'host.env', 'hosts.env'])
+                        The files to load the mssh file based environment variables from. Can specify multiple. Load first to last. ( Still work with --no_env ) (default: ['/etc/profile.d/hosts.sh', '~/.bashrc', '~/.zshrc', '~/host.env', '~/hosts.env'])
   -m, --max_connections MAX_CONNECTIONS
                         Max number of connections to use (default: 4 * cpu_count)
   -j, --json            Output in json format. (default: False)
@@ -884,9 +943,6 @@ DEFAULT_ENV_FILES = ['/etc/profile.d/hosts.sh',
 					 '~/.zshrc',
 					 '~/host.env',
 					 '~/hosts.env',
-					 '.env',
-					 'host.env',
-					 'hosts.env',
 					 ]
 DEFAULT_NO_HISTORY = False
 DEFAULT_HISTORY_FILE = '~/.mssh_history'