From c58b26ecf8edab2f396f4b4cf6e02f408e432980 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebastian=20Untersch=C3=BCtz?= Date: Mon, 16 Nov 2026 20:59:35 +0100 Subject: [PATCH] feat(multi): keep hotkeys visible and add README cheat sheet --- README.md | 115 +++++++++++++++++++++++---- internal/multiplex/multiplex_test.go | 38 ++++++++- internal/multiplex/tmux.go | 27 ++++++- 3 files changed, 159 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index d503e8f..218f8bf 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,7 @@ The same lookup drives `netssh sftp`, `netssh scp`, and `netssh tunnel`, the int - [Quick start](#quick-start) - [Configuration](#configuration) — [wizard](#interactive-wizard), [manual config](#manual-config), [reference](#configuration-reference), [environment variables](#environment-variables), [files](#files-and-directories), [multiple instances](#multiple-netbox-instances) - [Usage](#usage) — [command overview](#command-overview), [SSH options](#ssh-options), [SFTP & SCP](#sftp-and-scp), [port forwarding](#port-forwarding), [static hosts](#static-hosts), [multiple servers](#multiple-servers-in-one-window), [shortcuts](#host-shortcuts), [TUI](#interactive-tui), [notes](#server-notes), [cache](#cache-management) +- [Hotkey cheat sheet](#hotkey-cheat-sheet) — search, editors, tmux and zellij - [Recipes](#recipes) - [IP Resolution Strategies](#ip-resolution-strategies) - [Shell Completion](#shell-completion) and [Shell Hook](#shell-hook) @@ -597,7 +598,9 @@ multi: | Exclude one pane | `Ctrl+b e` (again: include) or `netssh sync --pane` | not possible — zellij syncs whole tabs | | Shown in the border | `[SYNC]` receives broadcast, `[SOLO]` excluded | `(SYNC)` in the tab name | -**Keys in tmux.** `S` and `e` are free in a default tmux (`E` would be "spread panes evenly"). netssh binds them after your prefix when it opens panes, but only if your own `tmux.conf` does not already use them — then it keeps your binding and says so. They act only in windows opened by `netssh multi`; elsewhere they just show a message. Change or turn them off with `multi.sync_key` / `multi.solo_key` (`none`), e.g. `sync_key: C-s` for `prefix Ctrl+s`. +**Keys in tmux.** The active pane border keeps the available broadcast/solo keys visible after attaching. See the [hotkey cheat sheet](#hotkey-cheat-sheet) for navigation and editor keys. + +`S` and `e` are free in a default tmux (`E` would be "spread panes evenly"). netssh binds them after your prefix when it opens panes, but only if your own `tmux.conf` does not already use them — then it keeps your binding and says so. They act only in windows opened by `netssh multi`; elsewhere they just show a message. Change or turn them off with `multi.sync_key` / `multi.solo_key` (`none`), e.g. `sync_key: C-s` for `prefix Ctrl+s`. **In the TUI**, mark hosts with `Space` (or all listed hosts with `Ctrl+A`) and press `Enter` to open them together. @@ -714,21 +717,7 @@ netssh The TUI opens with your 10 most-recently-connected hosts. Start typing to search all cached hosts or query NetBox live. -| Key | Action | -|-----|--------| -| type | filter hosts (300 ms debounce → NetBox query) | -| `Tab` | autocomplete top result into the search field | -| `↑` / `↓` | navigate results | -| `Enter` | connect to selected host | -| `Space` | mark/unmark the host; with marks, `Enter` opens them side by side (`netssh multi`) | -| `Ctrl+A` | mark all listed hosts (again: unmark all) | -| `Ctrl+O` | open an SFTP session to the selected host | -| `Ctrl+T` | start a tunnel: enter forward names or specs (`web, 8080:localhost:80`) | -| `Ctrl+E` | open inline editor to override user/port before connecting | -| `Ctrl+N` | edit local notes for the selected server | -| `Ctrl+B` | edit NetBox comments for the selected server | -| `Ctrl+F` | open/close tag and kind filter (`tag:prod kind:vm`) | -| `Esc` / `Ctrl+C` | quit (or close filter/edit if open) | +See the [hotkey cheat sheet](#hotkey-cheat-sheet) for all search and editor keys. **Tag and kind filter** — press `Ctrl+F` to open a second input line: @@ -817,6 +806,100 @@ The hook is a no-op when the cache is fresh — it adds no measurable delay to y netssh search app- # prints matching hostnames, one per line ``` +## Hotkey cheat sheet + +Keys depend on the current screen: for example, `Ctrl+B` opens NetBox comments +in the search, while tmux uses `Ctrl+b` as its default prefix. +“Then” means release the first combination before pressing the next key; +`S` is uppercase (`Shift+s`). + +### Search and host selection + +| Key | Action | +|-----|--------| +| type | filter hosts (300 ms debounce → NetBox query) | +| `Tab` | autocomplete top result into the search field | +| `↑` / `↓` | navigate results | +| `PageUp` / `PageDown` | previous/next results page | +| `Home` / `End` | first/last result (also moves the search cursor) | +| `Enter` | connect to selected host | +| `Space` | mark/unmark the host; with marks, `Enter` opens them side by side (`netssh multi`) | +| `Ctrl+A` | mark all listed hosts (again: unmark all) | +| `Ctrl+O` | open an SFTP session to the selected host | +| `Ctrl+T` | start a tunnel: enter forward names or specs (`web, 8080:localhost:80`) | +| `Ctrl+E` | open inline editor to override user/port before connecting | +| `Ctrl+N` | edit local notes for the selected server | +| `Ctrl+B` | edit NetBox comments for the selected server | +| `Ctrl+F` | open/close tag and kind filter (`tag:prod kind:vm`) | +| `Esc` | quit search | +| `Ctrl+C` | quit from any TUI mode, including editors | + +### Filters, connection/tunnel editors and notes + +| Screen | Key | Action | +|---|---|---| +| Filter (`Ctrl+F`) | `Enter` | apply filter and return to results | +| Filter | `Esc` / `Ctrl+F` | close and clear the filter | +| User/port editor (`Ctrl+E`) | `Enter` | connect using the edited user/port | +| Tunnel editor (`Ctrl+T`) | `Enter` | start the requested forwards | +| User/port or tunnel editor | `Esc` | cancel and return to results | +| Local notes / NetBox comments | `Enter` | insert a new line | +| Local notes / NetBox comments | `Ctrl+S` | save | +| Local notes / NetBox comments | `Esc` | cancel and discard unsaved edits (when not loading/saving) | +| Any TUI screen | `Ctrl+C` | quit, discarding unsaved edits | + +Text fields also support their standard cursor movement and editing keys. + +### Multi-mode: tmux + +The active pane's top border shows the configured broadcast/solo shortcuts +throughout the session. A narrow pane may clip the legend; zoom it with +`Ctrl+b` then `z` to make more room. `[SYNC]` means the pane receives broadcast; +`[SOLO]` means it is excluded. + +The following uses tmux's default prefix `Ctrl+b`. Use your own prefix if +changed in `tmux.conf`; netssh's legend reads the configured prefix. +Navigation keys below are tmux defaults and can be remapped by your configuration. + +| Key | Action | +|---|---| +| `Ctrl+b` then `S` | toggle broadcast for the current window (netssh default) | +| `Ctrl+b` then `e` | exclude/include the active pane in broadcast (netssh default) | +| `Ctrl+b` then arrow key | focus the pane in that direction | +| `Ctrl+b` then `o` | focus the next pane | +| `Ctrl+b` then `z` | zoom/unzoom the active pane | +| `Ctrl+b` then `n` / `p` | next/previous window | +| `Ctrl+b` then `w` | choose a window | +| `Ctrl+b` then `d` | detach; sessions keep running | +| `Ctrl+b` then `?` | show all current tmux bindings | +| `Enter` after a failed connection | close the pane displaying the error | + +Change broadcast/solo keys with `multi.sync_key` and `multi.solo_key`; +`none` disables a binding. Existing user bindings take precedence and are +reported in the legend. Command alternatives are `netssh sync` and +`netssh sync --pane` (run locally inside the multiplexer). +Solo excludes a pane from broadcast; it does not toggle zoom. + +### Multi-mode: zellij + +Zellij's bottom status bar shows the keys for the current mode. These are +standard bindings; custom presets may differ. + +| Key | Action | +|---|---| +| `Ctrl+t` then `s` | toggle broadcast for the entire tab | +| `Ctrl+p` then arrow key | move pane focus in pane mode | +| `Ctrl+p` then `f` | toggle fullscreen for the focused pane | +| `Ctrl+t` then left/right arrow | switch tabs in tab mode | +| `Enter` / `Esc` in a control mode | return to normal mode | +| `Ctrl+o` then `d` | detach; session keeps running | +| `Ctrl+g` | toggle locked mode to pass control keys to the remote application | + +Zellij cannot exclude individual panes from broadcast. `netssh sync` toggles +the whole tab. When starting a new zellij session, enable broadcast manually +with `Ctrl+t` then `s`; `--sync` is applied automatically only inside an +existing zellij session. + ## Recipes **Everything through a bastion, except the bastion itself** diff --git a/internal/multiplex/multiplex_test.go b/internal/multiplex/multiplex_test.go index 81fa298..4e08a0f 100644 --- a/internal/multiplex/multiplex_test.go +++ b/internal/multiplex/multiplex_test.go @@ -18,6 +18,7 @@ type fake struct { syncState string keys map[string]string // existing prefix bindings by key solo string + prefix string n int } @@ -33,6 +34,8 @@ func (f *fake) Output(argv ...string) (string, error) { f.calls = append(f.calls, strings.Join(argv, " ")) f.n++ switch argv[1] { + case "show-options": + return f.prefix, nil case "new-window", "new-session": return fmt.Sprintf("@%d %%%d", f.n, f.n), nil case "split-window": @@ -121,6 +124,8 @@ func TestTmuxInside(t *testing.T) { "tmux list-keys -T prefix S", "tmux list-keys -T prefix e", "tmux source-file /tmp/l/netssh-multi.tmux.conf", + "tmux set-window-option -t @1 @netssh_keys keys: Ctrl+b then S: sync on/off | Ctrl+b then e: solo on/off", + "tmux set-window-option -t @1 pane-border-format #{@netssh_host}#{?pane_synchronized, [SYNC],#{?@netssh_solo, [SOLO],}} #{?pane_active, | #{@netssh_keys},} ", "tmux select-window -t @1", } if strings.Join(f.calls, "\n") != strings.Join(want, "\n") { @@ -234,7 +239,7 @@ func TestTmuxKeyBindings(t *testing.T) { t.Errorf("conf lacks %q:\n%s", want, conf) } } - if hint != "keys: C-b S broadcast to all panes, C-b e exclude/include this pane" { + if hint != "keys: Ctrl+b then S: sync on/off | Ctrl+b then e: solo on/off" { t.Errorf("hint %q", hint) } @@ -279,3 +284,34 @@ func TestToggleSyncPane(t *testing.T) { t.Fatalf("zellij: %v", err) } } + +func TestTmuxPersistentHints(t *testing.T) { + for _, tc := range []struct { + name string + keys map[string]string + want string + }{ + {"custom prefix", nil, "keys: Ctrl+a then Ctrl+s: sync on/off | Ctrl+a then e: solo on/off"}, + {"occupied key", map[string]string{"C-s": "bind-key -T prefix C-s display-time"}, "keys: Ctrl+a then e: solo on/off; C-a C-s kept your own binding (use netssh sync)"}, + } { + t.Run(tc.name, func(t *testing.T) { + f := newFake(nil, "tmux") + f.prefix, f.keys = "C-a", tc.keys + if err := Open(Tmux, panes("a", "b"), Options{PerWindow: 1, SyncKey: "C-s", SoloKey: "e"}, f); err != nil { + t.Fatal(err) + } + n := 0 + for _, call := range f.calls { + if strings.Contains(call, " @netssh_keys ") { + n++ + if !strings.HasSuffix(call, " @netssh_keys "+tc.want) { + t.Fatalf("wrong persistent hint: %s", call) + } + } + } + if n != 2 { + t.Fatalf("hints installed in %d windows, want 2", n) + } + }) + } +} diff --git a/internal/multiplex/tmux.go b/internal/multiplex/tmux.go index c22c27f..4e6a30c 100644 --- a/internal/multiplex/tmux.go +++ b/internal/multiplex/tmux.go @@ -27,6 +27,7 @@ func openTmux(panes []Pane, opts Options, r Runner) error { } groups := chunks(panes, opts.PerWindow) first := "" + var windows []string for i, group := range groups { name := windowLabel(opts.Label, i, len(groups)) format := []string{"-P", "-F", "#{window_id} #{pane_id}", "-n", name} @@ -52,6 +53,7 @@ func openTmux(panes []Pane, opts Options, r Runner) error { } } window, pane, _ := strings.Cut(out, " ") + windows = append(windows, window) if first == "" { first = window } @@ -91,6 +93,17 @@ func openTmux(panes []Pane, opts Options, r Runner) error { } if keys != "" { opts.Hint(keys) + // Window-local hints remain visible after attaching, including in an + // existing session. Keep other windows and the user's status bar intact. + for _, window := range windows { + if _, err := r.Output("tmux", "set-window-option", "-t", window, "@netssh_keys", keys); err != nil { + return err + } + if _, err := r.Output("tmux", "set-window-option", "-t", window, "pane-border-format", + " #{@netssh_host}#{?pane_synchronized, [SYNC],#{?@netssh_solo, [SOLO],}} #{?pane_active, | #{@netssh_keys},} "); err != nil { + return err + } + } } if inside { _, err := r.Output("tmux", "select-window", "-t", first) @@ -149,8 +162,8 @@ func bindKeys(r Runner, opts Options) (string, error) { var conf strings.Builder var hints, taken []string for _, key := range []struct{ key, binding, what string }{ - {opts.SyncKey, syncBinding, "broadcast to all panes"}, - {opts.SoloKey, soloBinding, "exclude/include this pane"}, + {opts.SyncKey, syncBinding, "sync on/off"}, + {opts.SoloKey, soloBinding, "solo on/off"}, } { if key.key == "" { continue @@ -161,7 +174,7 @@ func bindKeys(r Runner, opts Options) (string, error) { continue } fmt.Fprintf(&conf, key.binding, key.key) - hints = append(hints, prefix+" "+key.key+" "+key.what) + hints = append(hints, displayKey(prefix)+" then "+displayKey(key.key)+": "+key.what) } if conf.Len() > 0 { path := filepath.Join(opts.LayoutDir, "netssh-multi.tmux.conf") @@ -172,7 +185,7 @@ func bindKeys(r Runner, opts Options) (string, error) { return "", err } } - hint := "keys: " + strings.Join(hints, ", ") + hint := "keys: " + strings.Join(hints, " | ") if len(hints) == 0 { hint = "toggle broadcast with: netssh sync, netssh sync --pane" } @@ -192,3 +205,9 @@ func freeSession(r Runner, name string) string { candidate = name + "-" + strconv.Itoa(n) } } + +// displayKey expands tmux's modifier notation for the on-screen legend. +func displayKey(key string) string { + key = strings.ReplaceAll(key, "C-", "Ctrl+") + return strings.ReplaceAll(key, "M-", "Alt+") +}