fix(completion): offer unique hostnames without instance prefix

bash (and zsh without a matcher) only accept candidates that start with
the typed text, so "fsn1-bx1<Tab>" found nothing when every candidate
was qualified as "prod/…". Hostnames that exist in only one instance
are now offered bare; names present in several instances stay
qualified. Connecting to a bare name still checks every instance for
ambiguity, so the connection behavior is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.gitea/workflows/release.yml

@@ -8,9 +8,14 @@ on:
 jobs:
   release:
     runs-on: ubuntu-latest
+    env:
+      GITEA_PUBLIC_URL: https://git.zb-server.de
+      GITEA_REPOSITORY: ${{ github.repository }}
 
     steps:
       - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
 
       - uses: actions/setup-go@v7
         with:
@@ -29,19 +34,28 @@ jobs:
             out="dist/netssh_${GOOS}_${GOARCH}"
             echo "→ $out"
             CGO_ENABLED=0 GOOS=$GOOS GOARCH=$GOARCH \
-              go build -trimpath -ldflags="-s -w" \
+              go build -trimpath -ldflags="-s -w -X main.version=${GITHUB_REF_NAME}" \
               -o "$out" ./cmd/netssh
           done
 
+      - name: Package installer
+        run: install -m 755 install.sh dist/install.sh
+
       - name: Generate checksums
         working-directory: dist
-        run: sha256sum netssh_* > checksums.txt
+        run: sha256sum netssh_* install.sh > checksums.txt
+
+      - name: Generate release notes
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: bash scripts/release-notes.sh "$RELEASE_TAG" "$GITEA_PUBLIC_URL/$GITEA_REPOSITORY" > dist/release-notes.md
 
       - name: Create release
         id: create_release
+        env:
+          TAG: ${{ github.ref_name }}
         run: |
-          TAG="${{ github.ref_name }}"
-          API="${{ github.server_url }}/api/v1/repos/${{ github.repository }}"
+          API="$GITEA_PUBLIC_URL/api/v1/repos/$GITEA_REPOSITORY"
           AUTH="Authorization: token ${{ secrets.GITEA_TOKEN }}"
 
           # Delete existing release for this tag if present
@@ -51,17 +65,28 @@ jobs:
             curl -sf -X DELETE -H "$AUTH" "$API/releases/$EXISTING"
           fi
 
+          # Serialize Markdown as JSON without hand-escaping quotes or newlines.
+          python3 - <<'PY_RELEASE' > dist/release.json
+          import json
+          import os
+          import sys
+          from pathlib import Path
+
+          tag = os.environ["TAG"]
+          json.dump({
+              "tag_name": tag,
+              "name": tag,
+              "body": Path("dist/release-notes.md").read_text(),
+              "draft": False,
+              "prerelease": False,
+          }, sys.stdout)
+          PY_RELEASE
+
           RELEASE=$(curl -sf -X POST \
             -H "$AUTH" \
             -H "Content-Type: application/json" \
             "$API/releases" \
-            -d "{
-              \"tag_name\": \"$TAG\",
-              \"name\": \"$TAG\",
-              \"body\": \"## Installation\n\n\`\`\`sh\ncurl -fsSL https://git.zb-server.de/Sebi/ssh-netbox-wrapper/raw/branch/main/install.sh | bash\n\`\`\`\",
-              \"draft\": false,
-              \"prerelease\": false
-            }")
+            --data-binary @dist/release.json)
 
           RELEASE_ID=$(echo "$RELEASE" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
           echo "release_id=$RELEASE_ID" >> "$GITHUB_OUTPUT"
@@ -69,12 +94,12 @@ jobs:
       - name: Upload assets
         run: |
           RELEASE_ID="${{ steps.create_release.outputs.release_id }}"
-          for file in dist/netssh_* dist/checksums.txt; do
+          for file in dist/netssh_* dist/install.sh dist/checksums.txt; do
             name=$(basename "$file")
             echo "↑ $name"
             curl -sf -X POST \
               -H "Authorization: token ${{ secrets.GITEA_TOKEN }}" \
               -H "Content-Type: application/octet-stream" \
-              "${{ github.server_url }}/api/v1/repos/${{ github.repository }}/releases/${RELEASE_ID}/assets?name=${name}" \
+              "$GITEA_PUBLIC_URL/api/v1/repos/$GITEA_REPOSITORY/releases/${RELEASE_ID}/assets?name=${name}" \
               --data-binary "@$file"
           done

CHANGELOG.md

@@ -0,0 +1,103 @@
+# Changelog
+
+## v0.0.22
+
+- Fix shell completion with multiple NetBox instances: typing a hostname without an instance prefix (`fsn1-bx1<Tab>`) found nothing in bash and zsh, because only `prod/…` was offered. Hostnames that are unique across all instances are now offered without the prefix; connecting to them still checks every instance for ambiguous names.
+- zsh also accepts instance-qualified matches for the typed hostname, so names that exist in several instances are offered as `prod/…` and `stg/…`.
+
+## v0.0.21
+
+- Ship a zsh completion script built for large caches: 5000 hosts complete in under 0.1 s instead of hanging for seconds with Cobra's generated script.
+- Add `completion.max_results` to limit the number of hostnames offered per completion.
+- Register zsh completion in the managed `.zshrc` block (`fpath` and `compdef`), also when `compinit` already ran, e.g. with oh-my-zsh. The installer reports which completions it set up.
+- Add `netssh uninstall [--keep-config] [--dry-run] [--yes]` to remove the binary, profile entries of all versions, completions, cache, and config (with a private backup).
+- Write marked `# >>> netssh >>>` blocks from `netssh hook install` and the wizard, replacing unmarked entries of older versions instead of appending.
+- Add jump host support: `ssh.proxy_jump` globally, per NetBox instance, and per rule, plus `--jump HOST` and `--no-jump`.
+- Add `ssh.host_key_checking` (`strict`, `accept-new`, `off`) for netssh connections only.
+- Add `ssh.target: name|hostname` so `~/.ssh/config` host patterns apply and known_hosts entries belong to the device, and `ssh.address_family`.
+- Add `ssh.options` and `ssh.extra_args`, and `ssh.rules` that match by tag, instance, kind, or name pattern.
+- Add `netssh --version` / `netssh version` and `netssh --dry-run` to print the final ssh command.
+
+## v0.0.20
+
+- Configure multiple named NetBox instances and search them together in parallel.
+- Add, edit, and remove instances in the interactive setup wizard while retaining legacy single-instance configuration support.
+- Display instance-qualified hostnames and support `instance/hostname` for SSH, completion, aliases, and notes.
+- Keep credentials, IP resolution, comments, cache entries, and local notes tied to the correct instance.
+- Preserve partial interactive search results with an outage warning; reject incomplete full refreshes and ambiguous direct connections.
+- Add `cache refresh --instance NAME` and isolate caches when configured endpoints change.
+- Add regression tests covering duplicate names and IDs across instances, outages, SSH routing, notes, aliases, and configuration round trips.
+
+## v0.0.19
+
+- Update Ultraviolet to commit `a45b7c8`.
+
+## v0.0.18
+
+- Require Go 1.27.3 and migrate Bubbles, Bubble Tea, Huh, and Lip Gloss to their v2 modules under `charm.land`.
+- Update TUI rendering and keyboard events for Bubble Tea v2 while preserving alternate-screen behavior.
+- Route paste events to the focused editor, size input fields explicitly, and keep host lists within the terminal height.
+- Reject ambiguous cached shortcuts and skip duplicate hostnames during cache refresh.
+- Use paginated, unambiguous host lookups for SSH connections.
+- Accept shortcut domains with or without a leading dot during cold lookups.
+- Parse combined SSH options and preserve explicit users and ports supplied through `-o`.
+- Merge cache changes under a file lock to preserve updates from concurrent processes.
+- Honor configured resolver strategies during refresh and remove entries that no longer resolve safely.
+- Check the host kind before reusing a cached IP for a TUI selection.
+
+## v0.0.17
+
+- Update Go module dependencies to the latest versions within their existing module paths, including used transitive test dependencies.
+- Remove obsolete indirect requirements and refresh module checksums with `go mod tidy`.
+
+## v0.0.16
+
+- Enable Bash, Zsh, and Fish completion for the configured command alias, such as `j`.
+- Update or remove generated alias completion files when the command alias changes.
+
+## v0.0.15
+
+- Use `https://git.zb-server.de` for release download links and API requests instead of the runner's internal Gitea service URL.
+
+## v0.0.14
+
+- Enable Renovate updates for indirect Go modules as well as direct dependencies and CI actions.
+- Enable Go version updates and keep Go module metadata tidy after dependency updates.
+- Correct direct and indirect dependency declarations in `go.mod`.
+- Include `install.sh` as a downloadable release asset.
+- Include the installer in `checksums.txt` alongside the platform binaries.
+- Link the installation command in release notes directly to the release's installer asset.
+- Generate a change list from commits since the previous version tag for every release.
+
+## v0.0.13
+
+- Translate the remaining German setup message and test example into English.
+- Correct the connection editor comment to reference `Ctrl+E`.
+
+## v0.0.12
+
+- Support updating an existing installation by running the installer again.
+- Remove the installer's Python dependency.
+- Require valid SHA-256 checksums before replacing the binary.
+- Check required programs before downloading and list missing dependencies.
+- Check for `sudo` before downloading when the installation directory requires elevated permissions.
+- Consolidate legacy shell hooks and aliases in Bash, Zsh, and Fish profiles.
+- Back up changed profiles and preserve symlinks and file permissions.
+- Regenerate aliases and completions during installation and updates.
+- Add a configurable command alias, such as `j`, to the setup wizard.
+- Refresh or remove the generated command alias when its configuration changes.
+
+## v0.0.11
+
+- Add multiline local server notes and optional NetBox comments in the TUI.
+- Add CLI commands to show, replace, and append server notes.
+- Keep local notes separate from the host cache, with private permissions and atomic writes.
+- Use NetBox ETags for comment conflict protection when supported by the server.
+- Correct authentication for NetBox v2 tokens.
+- Fix environment variable overrides for configuration keys.
+- Preserve usage history when refreshing cached hosts.
+- Discard stale TUI search results and use `Ctrl+E` for connection editing.
+- Validate port overrides and preserve an explicit port 22.
+- Resolve stale and live TUI selections through the configured resolver chain.
+- Reject incomplete full cache refreshes and avoid marking filtered refreshes as full refreshes.
+- Stop interpreting remote command flags as SSH options when applying defaults.

README.md

@@ -32,6 +32,9 @@ netssh -p 2222 admin@app-server-03 uptime
 - **Host shortcuts** — type `web01` instead of `web01.example.com`; configurable domain strip and hyphen folding
 - **Shell aliases** — `netssh alias` generates shell aliases for all cached hosts
 - **Automatic 24h cache refresh** — the cache is refreshed in the background every 24 hours
+- **Jump hosts and SSH options** — `proxy_jump`, host key checking, connection target, and free `-o` options per netssh, per NetBox instance, or per tag/name rule — without touching `~/.ssh/config`
+- **Dry run** — `netssh --dry-run host` prints the final `ssh` command instead of connecting
+- **Clean uninstall** — `netssh uninstall` removes the binary, profile entries of all versions, completions, cache, and config
 
 ## Installation
 
@@ -46,9 +49,44 @@ The script detects your OS and architecture, downloads the matching binary from
 To install to a custom directory:
 
 ```sh
-INSTALL_DIR=~/.local/bin curl -fsSL https://git.zb-server.de/Sebi/ssh-netbox-wrapper/raw/branch/main/install.sh | bash
+curl -fsSL https://git.zb-server.de/Sebi/ssh-netbox-wrapper/raw/branch/main/install.sh | INSTALL_DIR="$HOME/.local/bin" bash
 ```
 
+### Updating an existing installation
+
+Run the same one-liner again to update to the latest release. The installer uses
+an existing `netssh` found in `PATH`, or `/usr/local/bin/netssh` for a new installation.
+`INSTALL_DIR` explicitly overrides the destination. The replacement is atomic,
+so an installed binary can be updated while it is running.
+
+The installer checks all required programs before downloading or modifying files:
+`curl`, `uname`, `sed`, `awk`, `mktemp`, `rm`, `dirname`, `readlink`, `mkdir`, `cat`,
+`install`, `mv`, `cp`, `chmod`, `cmp`, and either `sha256sum` (Linux) or `shasum`
+(macOS). Bash runs the installer; `sudo` is checked beforehand only if the target
+directory requires elevated permissions. Missing programs are listed together;
+install them with your package manager and retry. **Python is not required. SHA-256 verification is mandatory:** missing,
+duplicate or mismatched checksums abort the update before replacing anything.
+
+It also consolidates netssh integration in existing Bash, Zsh and Fish profiles
+and creates the current shell's rc file when needed. Old standalone netssh hooks,
+inline host aliases and `eval "$(netssh alias)"` entries are replaced by a single
+managed block per rc file. Legacy entries in login profiles are removed as well.
+Other shell settings, NetBox configuration, cache and local notes are preserved.
+Every changed existing profile gets a `.netssh-backup.XXXXXX` backup; symlinks
+and permissions are preserved. `XDG_CONFIG_HOME`, `XDG_CACHE_HOME` and `ZDOTDIR`
+are respected. Alias files and installed shell completions are regenerated.
+Open a **new terminal** after updating to load the new aliases and hooks.
+
+### Release downloads and change history
+
+Each new release includes `install.sh`, binaries for Linux and macOS (amd64 and
+arm64), and `checksums.txt` covering all of these files. The release notes include
+an installation command pointing directly to that release's `install.sh` asset
+and a list of changes since the previous version tag.
+
+See [CHANGELOG.md](CHANGELOG.md) for the change history. The installer attached to
+a release installs or updates to the latest published binary release.
+
 ### Build from source
 
 ```sh
@@ -68,7 +106,7 @@ Re-run it at any time to change settings without editing the file manually:
 netssh configure
 ```
 
-The wizard walks through NetBox connection, SSH defaults, resolver strategies, and cache TTL,
+The wizard lets you add, edit, and remove named NetBox instances, then walks through SSH defaults, resolver strategies, cache TTL, and an optional command alias,
 then saves to `~/.config/netssh.yaml`.
 
 ### Manual config
@@ -100,6 +138,11 @@ cache:
 ssh:
   default_user: admin  # used when no user is specified on the command line
   default_port: 2222   # optional; injected as -p if not specified on the command line
+  # See "SSH options" below for proxy_jump, host_key_checking, target,
+  # address_family, extra_args, options, and rules.
+
+completion:
+  max_results: 0       # hostnames offered per <Tab>; 0 = unlimited
 
 shortcuts:
   domains:             # strip these suffixes to create short aliases
@@ -107,7 +150,77 @@ shortcuts:
   strip_hyphens: false # if true, fsn1-web01 → fsn1web01 (cache-only resolution)
 ```
 
-Any value can be overridden with environment variables (`NETSSH_NETBOX_URL`, `NETSSH_NETBOX_TOKEN`, etc.).
+Single-instance and shared settings can be overridden with environment variables (`NETSSH_NETBOX_URL`, `NETSSH_NETBOX_TOKEN`, etc.).
+
+### Multiple NetBox instances
+
+Use `netssh configure` to manage instances, or replace the `netbox:` section with a `netboxes:` list:
+
+```yaml
+netboxes:
+  - name: office
+    url: https://netbox.office.example
+    token: nbt_office-token
+  - name: lab
+    url: https://netbox.lab.example
+    token: nbt_lab-token
+```
+
+Names must be unique and contain only letters, digits, underscores, or hyphens. Names are normalized to lowercase. Each instance has its own token and optional `token_version`; SSH, resolver, and shortcut settings apply to all instances. Configure either `netbox:` or `netboxes:`. Existing single-instance files continue to work; the wizard migrates them to a named `default` instance when saved.
+
+The legacy `NETSSH_NETBOX_URL` and `NETSSH_NETBOX_TOKEN` variables apply to single-instance configuration. They are ignored when the file contains only a named `netboxes:` list.
+
+Each NetBox keeps its own inventory of devices and virtual machines; either inventory may be empty. The interactive search queries all instances in parallel, including when one already has cached matches. Results show the instance as part of the hostname, for example `office/web01`. If an instance is unavailable, available results and cached hosts remain visible with a warning.
+
+```sh
+netssh                              # search all instances interactively
+netssh office/web01                 # choose an instance explicitly
+netssh admin@lab/web01 uptime
+netssh web01                        # accepted only if the live lookup is unambiguous
+netssh cache refresh                 # refresh all instances
+netssh cache refresh --instance lab  # refresh just one instance
+netssh notes set office/web01 "Office maintenance"
+netssh notes show lab/web01 --netbox --kind device
+```
+
+For direct connections without an instance prefix, every instance must be reachable to verify uniqueness. A qualified target queries only its own instance and can use a fresh cached IP while other instances are offline. Qualified shortcuts such as `office/web01` also support configured domain suffixes and hyphen folding.
+
+Cache entries and generated aliases retain the instance name (`office_web01` and `lab_web01`). Named-instance caches live in a configuration-specific subdirectory beneath the configured cache path, so changing an endpoint cannot reuse another server's cached IPs. Run `netssh cache refresh` after adding or changing instances. A failed full refresh leaves the cache and its refresh timestamp unchanged; a per-instance refresh preserves the other instances and does not mark the whole cache as refreshed.
+
+Local notes remain keyed by the NetBox URL, host kind, and canonical hostname. Migrating a single instance or renaming it preserves its notes. Use `instance/hostname` and `--kind` for uncached local notes; these operations work offline. NetBox comments and interface/IP lookups always use the selected instance's credentials.
+
+### Short command alias
+
+In `netssh configure`, set **Command alias** to `j` to use `j` anywhere you would
+use `netssh`:
+
+```sh
+j                    # interactive server search
+j server01           # connect to a server
+j notes show server01
+```
+
+The setting is saved as:
+
+```yaml
+shell:
+  alias: j
+```
+
+The wizard regenerates shell aliases and installs the current shell's hook when
+an alias is set. Open a new terminal (or follow the displayed reload command).
+Changing the setting replaces the old generated alias; leaving it empty disables
+it for new shells. The command alias takes priority over a host alias with the
+same name and works even when no servers are cached. Environment override:
+`NETSSH_SHELL_ALIAS=j`.
+
+The command alias also supports shell completion: `j ser<Tab>` suggests cached
+server names, just like `netssh ser<Tab>`. The wizard, shell hook, installer, and
+`netssh completion install` maintain the alias completion files automatically.
+Changing or disabling the alias removes its old generated completion files.
+Bash requires bash-completion to load user completion files; for Zsh, include
+`~/.zfunc` in `fpath` before running `compinit` as described below. Fish loads
+completion files automatically. Open a new terminal after changing the alias.
 
 ### API tokens
 
@@ -135,6 +248,74 @@ netssh -i ~/.ssh/id_rsa -o StrictHostKeyChecking=no db-primary
 
 The process is replaced by `ssh` with the resolved IP — your `~/.ssh/config`, agent, and keys all work as normal.
 
+### Dry run and version
+
+```sh
+netssh --dry-run web01      # print the final ssh command instead of connecting
+netssh --version            # or: netssh version
+```
+
+Long options (`--dry-run`, `--jump`, `--no-jump`) are netssh's own; OpenSSH has
+no long options. They must come before the hostname — everything after the
+hostname is the remote command.
+
+### SSH options
+
+All settings below go under `ssh:`. The same keys (except `rules`) can be set
+per NetBox instance under `netboxes[].ssh` (or `netbox.ssh`), and per rule.
+More specific settings win: global → instance → matching rules (in order) →
+command-line flags. Options you pass on the command line always take precedence
+over the config.
+
+```yaml
+ssh:
+  proxy_jump: "jumphost.example.com"  # passed as -J; "none" disables an inherited jump host
+  host_key_checking: accept-new       # strict | accept-new | off; unset = ssh's own setting
+  target: ip                          # ip (default) | name | hostname
+  address_family: inet                # any | inet (-4) | inet6 (-6)
+  extra_args: ["-A"]                  # inserted before your own arguments
+  options:                            # passed as -o Key=Value
+    ServerAliveInterval: 60
+    ServerAliveCountMax: 5
+  rules:                              # every set match field must match
+    - match: {tag: dmz}               # tag name or slug
+      proxy_jump: "dmz-jump.example.com"
+    - match: {instance: lab, name: "*.lab.example.com", kind: vm}
+      host_key_checking: off
+
+netboxes:
+  - name: prod
+    url: "https://netbox.example.com"
+    token: "nbt_…"
+    ssh:
+      proxy_jump: "jumphost.example.com"
+  - name: staging
+    url: "https://netbox-staging.example.com"
+    token: "nbt_…"
+    ssh:
+      host_key_checking: off
+```
+
+**Jump hosts.** Override the configured jump host for a single call with
+`--jump other.example.com` (or ssh's own `-J`), or disable all jump hosts —
+including `ProxyJump` from `~/.ssh/config` — with `--no-jump`.
+
+**Host key checking.** `strict` sets `StrictHostKeyChecking=yes`, `accept-new`
+accepts keys of new hosts but rejects changed ones. `off` sets
+`StrictHostKeyChecking=no`, `UserKnownHostsFile=/dev/null`, and `LogLevel=ERROR`
+for netssh connections only and prints a short notice. Use it only for hosts
+that are reinstalled often, such as staging; it disables protection against
+man-in-the-middle attacks.
+
+**Connection target.** By default netssh calls `ssh <ip>`. With `target: name`,
+it calls `ssh -o HostName=<ip> -o HostKeyAlias=<name> <name>`: the resolved IP
+is still used, but `Host *.example.com` rules in `~/.ssh/config` apply, and
+known_hosts entries belong to the device instead of an IP that may be reused.
+With `target: hostname`, ssh resolves the NetBox name itself (DNS or
+`~/.ssh/config`). Names that are not valid hostnames fall back to the IP.
+Switching to `name` stores new known_hosts entries under the device name, so
+ssh asks once to confirm each host key.
+
 ### Default username
 
 Set `ssh.default_user` in the config to avoid typing a username every time:
@@ -182,6 +363,8 @@ Resolution order:
 2. **Domain expansion** — if the input contains no dot, each configured domain is appended and tried (`web01` → `web01.example.com`). If no cache hit, NetBox is queried with the expanded name.
 3. **Hyphen folding** (`strip_hyphens: true`) — hyphens are inserted back before looking up in the cache (`fsn1web01` → `fsn1-web01.example.com`). This only works when the host is already cached; run `netssh cache refresh` first.
 
+Domains may be configured with or without a leading dot. If several cached hosts normalize to the same shortcut, the connection is rejected; use the full hostname. Live host lookups check every result page and reject duplicate exact names.
+
 | Input | Config | Resolved as |
 |-------|--------|-------------|
 | `web01` | `domains: [.example.com]` | `web01.example.com` |
@@ -315,7 +498,7 @@ netssh hook install --shell zsh
 netssh hook install --shell fish
 ```
 
-This appends a single line (`netssh shell-init`) to your shell profile. To remove it:
+This adds a marked block (`# >>> netssh >>>` … `# <<< netssh <<<`) to your shell profile. To remove it:
 
 ```sh
 netssh hook uninstall
@@ -333,6 +516,8 @@ netssh search app-           # prints matching hostnames, one per line
 
 Strategies are tried in the configured order; the first to succeed wins.
 
+Cache refresh uses the same strategies as a direct connection. To allow the primary IP as a fallback, include `primary_ip` in the strategy list. Hosts that cannot be resolved, or have ambiguous names in the refresh results, are removed from the cache and reported as warnings.
+
 | Name | Description |
 |------|-------------|
 | `primary_ip` | Returns the `primary_ip4` (or `primary_ip6`) set in NetBox. No extra API call. |
@@ -356,14 +541,24 @@ netssh completion install --shell fish
 | zsh  | `~/.zfunc/_netssh` |
 | fish | `~/.config/fish/completions/netssh.fish` |
 
-For zsh, make sure `~/.zfunc` is in your `fpath` (add to `~/.zshrc`):
+For zsh, the netssh block in `~/.zshrc` (written by the installer and by
+`netssh hook install --shell zsh`) adds `~/.zfunc` to `fpath` and registers the
+completion with `compdef`, also when `compinit` already ran earlier — for
+example via oh-my-zsh. Without the block, add `fpath=(~/.zfunc $fpath)` before
+`compinit`. If `<Tab>` still completes files, clear the completion cache:
 
 ```zsh
-fpath=(~/.zfunc $fpath)
-autoload -Uz compinit && compinit
+rm -f ~/.zcompdump* && exec zsh
 ```
 
 Completions are served from the local cache — no network request on every `<Tab>`.
+With several NetBox instances, a hostname that exists in only one instance is
+completed without the instance prefix (`web01`); names that exist in several
+instances are offered as `prod/web01`, `staging/web01`. In bash, type the
+instance prefix for those; zsh and fish offer them for the hostname alone.
+The zsh script that `netssh completion zsh` prints is built for large caches:
+5000 hosts complete in well under a second. To limit the number of hostnames
+offered, set `completion.max_results`.
 
 ## Shell Hook
 
@@ -393,15 +588,25 @@ Reload with: source /home/user/.bashrc
 
 What gets written to the profile:
 
-**bash / zsh** (`~/.bashrc` or `~/.zshrc`):
+**bash** (`~/.bashrc`):
 ```bash
-netssh shell-init  # netssh cache auto-refresh
-source ~/.cache/netssh/aliases.sh 2>/dev/null  # netssh aliases
+# >>> netssh >>>
+netssh shell-init
+[ ! -f '/home/user/.cache/netssh/aliases.sh' ] || . '/home/user/.cache/netssh/aliases.sh'
+# <<< netssh <<<
+```
+
+**zsh** (`~/.zshrc`) additionally registers the completion:
+```zsh
+fpath=('/home/user/.zfunc' $fpath)
+if (( $+functions[compdef] )); then autoload -Uz _netssh && compdef _netssh netssh; fi
 ```
 
 **fish** (`~/.config/fish/config.fish`):
 ```fish
-netssh shell-init  # netssh cache auto-refresh
+# >>> netssh >>>
+netssh shell-init
+# <<< netssh <<<
 ```
 
 Fish alias file (`~/.config/fish/conf.d/netssh.fish`) is written automatically and sourced by fish on every shell start without any profile changes.
@@ -412,7 +617,7 @@ Fish alias file (`~/.config/fish/conf.d/netssh.fish`) is written automatically a
 | zsh   | `~/.zshrc`  | `~/.cache/netssh/aliases.sh` |
 | fish  | `~/.config/fish/config.fish` | `~/.config/fish/conf.d/netssh.fish` |
 
-The install is idempotent — running it again changes nothing if the lines are already present.
+The install is idempotent — running it again changes nothing if the block is already present. Unmarked lines written by older versions are replaced by the block.
 
 Reload your profile after installation to activate immediately:
 
@@ -441,7 +646,7 @@ netssh hook uninstall             # auto-detects $SHELL
 netssh hook uninstall --shell zsh
 ```
 
-Removes both the `netssh shell-init` line and the `source aliases.sh` line from the profile. The alias files (`aliases.sh`, `netssh.fish`) are left on disk — delete them manually if desired.
+Removes the netssh block and unmarked entries of older versions from the profile. The alias files (`aliases.sh`, `netssh.fish`) are left on disk. To remove netssh completely, use `netssh uninstall`.
 
 ### Relation to the connect-time auto-refresh
 
@@ -454,10 +659,32 @@ The shell hook and the connect-time trigger (which fires on each `netssh` invoca
 
 Both are non-blocking — the refresh runs as a background process and never delays your prompt or SSH connection. They share `~/.cache/netssh/last_refresh`, so only one background refresh runs per 24-hour window regardless of how many shells or connections are opened.
 
-## Development
+## Uninstall
 
 ```sh
-go test ./...        # run all tests
+netssh uninstall --dry-run       # show what would be removed
+netssh uninstall                 # asks for confirmation
+netssh uninstall --keep-config   # keep config and notes for a reinstall
+```
+
+`netssh uninstall` removes:
+
+- netssh blocks and unmarked entries of older versions from `~/.bashrc`, `~/.bash_profile`, `~/.bash_login`, `~/.profile`, `~/.zshrc`, `~/.zprofile`, `~/.zshenv`, and `config.fish`
+- completion files for bash, zsh (also the oh-my-zsh cache), fish, and the command alias
+- the cache directory `~/.cache/netssh/` including per-instance caches and aliases
+- `~/.config/netssh.yaml` (a private backup `netssh.yaml.backup-<timestamp>` is kept, because it contains API tokens) and local notes
+- the netssh binary; if it is in a protected directory, netssh prints the `sudo rm` command to run
+
+Afterwards open a new terminal; for zsh also run `rm -f ~/.zcompdump*`.
+
+## Development
+
+Renovate monitors the release workflow's actions, the Go version in `go.mod`, and
+all direct and indirect Go module dependencies. Go dependency updates also run
+`go mod tidy` to keep `go.mod` and `go.sum` consistent.
+
+```sh
+go test ./...        # includes offline installer/update tests
 go build ./...       # build all packages
 ```
 
@@ -469,9 +696,9 @@ This is a **vibe-coded** project: the entire codebase — architecture, implemen
 
 ## How it works
 
-1. `netssh` checks whether the first argument is a known subcommand (`configure`, `search`, `cache`, `completion`). If not, it enters SSH wrapper mode.
+1. `netssh` checks whether the first argument is a known subcommand (`configure`, `search`, `cache`, `completion`, `version`, `uninstall`, …). If not, it enters SSH wrapper mode.
 2. On first run or when `netbox.url` is empty, the interactive setup wizard starts automatically.
 3. It parses the SSH arguments to extract the destination hostname, handling all flags that consume an extra argument (`-p`, `-i`, `-J`, …).
 4. It resolves the destination: first an exact cache lookup, then shortcut expansion (domain append, hyphen folding) against the cache, and finally a fresh NetBox query with the expanded name. If the cache entry is within the TTL, no network request is made.
 5. Otherwise it queries NetBox (`/api/dcim/devices/` and `/api/virtualization/virtual-machines/` in parallel), runs the result through the resolver chain, and caches the IP.
-6. It calls `syscall.Exec` to replace itself with `ssh`, substituting the hostname with the resolved IP.
+6. It adds the configured SSH options for the host (jump host, host key checking, `-o` options) before the destination and calls `syscall.Exec` to replace itself with `ssh`, substituting the hostname with the resolved IP (or the name, with `ssh.target: name`).

cmd/netssh/connection_test.go

@@ -0,0 +1,197 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/cache"
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/netbox"
+)
+
+type connectionTestHost struct {
+	ID         int    `json:"id"`
+	Name       string `json:"name"`
+	PrimaryIP4 *struct {
+		Address string `json:"address"`
+	} `json:"primary_ip4,omitempty"`
+}
+
+func connectionTestServer(t *testing.T, devices, vms []connectionTestHost) *httptest.Server {
+	t.Helper()
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		var hosts []connectionTestHost
+		switch r.URL.Path {
+		case "/api/dcim/devices/":
+			hosts = devices
+		case "/api/virtualization/virtual-machines/":
+			hosts = vms
+		case "/api/ipam/ip-addresses/":
+			fmt.Fprint(w, `{"count":0,"results":[]}`)
+			return
+		default:
+			http.NotFound(w, r)
+			return
+		}
+		query := strings.ToLower(r.URL.Query().Get("name__ic"))
+		matched := make([]connectionTestHost, 0)
+		for _, host := range hosts {
+			if strings.Contains(strings.ToLower(host.Name), query) {
+				matched = append(matched, host)
+			}
+		}
+		offset, _ := strconv.Atoi(r.URL.Query().Get("offset"))
+		limit, _ := strconv.Atoi(r.URL.Query().Get("limit"))
+		if limit <= 0 {
+			limit = 50
+		}
+		start, end := min(offset, len(matched)), min(offset+limit, len(matched))
+		json.NewEncoder(w).Encode(map[string]any{"count": len(matched), "results": matched[start:end]})
+	}))
+	t.Cleanup(srv.Close)
+	return srv
+}
+
+func TestFindSSHHostBeyondFirstPage(t *testing.T) {
+	var devices []connectionTestHost
+	for i := range 50 {
+		devices = append(devices, connectionTestHost{ID: i + 1, Name: fmt.Sprintf("web-extra-%02d", i)})
+	}
+	devices = append(devices, connectionTestHost{ID: 51, Name: "web"})
+	srv := connectionTestServer(t, devices, nil)
+	host, err := findSSHHost(context.Background(), netbox.NewClient(srv.URL, "token", 0), "web", nil)
+	if err != nil || host.ID != 51 {
+		t.Fatalf("host beyond first page not resolved: %+v, %v", host, err)
+	}
+}
+
+func TestFindSSHHostDomainExpansion(t *testing.T) {
+	for _, domain := range []string{"example.com", ".example.com", " .example.com "} {
+		t.Run(domain, func(t *testing.T) {
+			srv := connectionTestServer(t, []connectionTestHost{{ID: 1, Name: "web.example.com"}}, nil)
+			host, err := findSSHHost(context.Background(), netbox.NewClient(srv.URL, "token", 0), "web", []string{domain})
+			if err != nil || host.Name != "web.example.com" {
+				t.Fatalf("domain expansion failed: %+v, %v", host, err)
+			}
+		})
+	}
+}
+
+func TestFindSSHHostRejectsAmbiguity(t *testing.T) {
+	srv := connectionTestServer(t, []connectionTestHost{{ID: 1, Name: "web"}, {ID: 2, Name: "web.example.com"}}, []connectionTestHost{{ID: 3, Name: "web"}})
+	_, err := findSSHHost(context.Background(), netbox.NewClient(srv.URL, "token", 0), "web", []string{"example.com"})
+	if err == nil || errors.Is(err, netbox.ErrHostNotFound) || !strings.Contains(err.Error(), "2 exact matches") {
+		t.Fatalf("ambiguous name accepted or expanded: %v", err)
+	}
+}
+
+func TestFindSSHHostDoesNotHideAPIErrors(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.Error(w, "unavailable", http.StatusServiceUnavailable)
+	}))
+	defer srv.Close()
+	_, err := findSSHHost(context.Background(), netbox.NewClient(srv.URL, "token", 0), "web", []string{"example.com"})
+	if err == nil || errors.Is(err, netbox.ErrHostNotFound) {
+		t.Fatalf("API failure hidden as missing host: %v", err)
+	}
+}
+
+func TestFindSSHHostNotFound(t *testing.T) {
+	srv := connectionTestServer(t, nil, nil)
+	_, err := findSSHHost(context.Background(), netbox.NewClient(srv.URL, "token", 0), "missing", []string{"example.com"})
+	if !errors.Is(err, netbox.ErrHostNotFound) {
+		t.Fatalf("want missing-host error, got %v", err)
+	}
+}
+
+func TestCacheRefreshHonorsResolverAndRemovesUnsafeEntries(t *testing.T) {
+	for _, tc := range []struct {
+		name, strategies string
+		wantCached       bool
+	}{
+		{"management only", "[management_subnet]", false},
+		{"explicit primary fallback", "[management_subnet, primary_ip]", true},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			host := connectionTestHost{ID: 1, Name: "web", PrimaryIP4: &struct {
+				Address string `json:"address"`
+			}{Address: "192.0.2.1/24"}}
+			srv := connectionTestServer(t, []connectionTestHost{host}, nil)
+			path := prepareRefreshTest(t, srv.URL, tc.strategies)
+			c := cache.New(path, 3600)
+			c.Upsert(cache.Entry{Name: "web", IP: "192.0.2.99", Kind: "device"})
+			if err := c.Save(); err != nil {
+				t.Fatal(err)
+			}
+			cmd := rootCmd()
+			cmd.SetArgs([]string{"cache", "refresh"})
+			if err := cmd.Execute(); err != nil {
+				t.Fatal(err)
+			}
+			if err := c.Load(); err != nil {
+				t.Fatal(err)
+			}
+			got, fresh := c.Get("web")
+			if tc.wantCached {
+				if !fresh || got.IP != "192.0.2.1" {
+					t.Fatalf("explicit fallback failed: %+v", got)
+				}
+			} else if got.Name != "" {
+				t.Fatalf("unsafe primary IP retained: %+v", got)
+			}
+		})
+	}
+}
+
+func TestCacheRefreshSkipsAmbiguousNames(t *testing.T) {
+	host := connectionTestHost{ID: 1, Name: "web", PrimaryIP4: &struct {
+		Address string `json:"address"`
+	}{Address: "192.0.2.1/24"}}
+	vm := host
+	vm.ID = 2
+	srv := connectionTestServer(t, []connectionTestHost{host}, []connectionTestHost{vm})
+	path := prepareRefreshTest(t, srv.URL, "[primary_ip]")
+	c := cache.New(path, 3600)
+	c.Upsert(cache.Entry{Name: "web", IP: "192.0.2.99", Kind: "device"})
+	if err := c.Save(); err != nil {
+		t.Fatal(err)
+	}
+	cmd := rootCmd()
+	cmd.SetArgs([]string{"cache", "refresh"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if err := c.Load(); err != nil {
+		t.Fatal(err)
+	}
+	if len(c.All()) != 0 {
+		t.Fatalf("ambiguous host cached: %+v", c.All())
+	}
+}
+
+func prepareRefreshTest(t *testing.T, baseURL, strategies string) string {
+	t.Helper()
+	configDir := t.TempDir()
+	t.Setenv("HOME", t.TempDir())
+	t.Setenv("XDG_CONFIG_HOME", configDir)
+	t.Setenv("XDG_CACHE_HOME", t.TempDir())
+	path := filepath.Join(t.TempDir(), "hosts.json")
+	t.Setenv("NETSSH_CACHE_PATH", path)
+	t.Setenv("NETSSH_NETBOX_URL", baseURL)
+	t.Setenv("NETSSH_NETBOX_TOKEN", "token")
+	t.Setenv("NETSSH_SHELL_ALIAS", "")
+	data := fmt.Sprintf("resolver:\n  strategies: %s\n  management_subnets: [10.0.0.0/8]\n", strategies)
+	if err := os.WriteFile(filepath.Join(configDir, "netssh.yaml"), []byte(data), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	return path
+}

cmd/netssh/instances.go

@@ -0,0 +1,69 @@
+package main
+
+import (
+	"sort"
+	"strings"
+
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/cache"
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/config"
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/netbox"
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/shortcuts"
+)
+
+func newNetBoxClient(cfg *config.Config) *netbox.Client {
+	if len(cfg.NetBoxes) > 0 {
+		sources := make([]netbox.Source, 0, len(cfg.NetBoxes))
+		for _, source := range cfg.NetBoxes {
+			sources = append(sources, netbox.Source{Name: source.Name, URL: source.URL, Token: source.Token, TokenVersion: source.TokenVersion})
+		}
+		return netbox.NewMultiClient(sources)
+	}
+	if cfg.NetBox.URL == "" {
+		return nil
+	}
+	return netbox.NewClient(cfg.NetBox.URL, cfg.NetBox.Token, cfg.NetBox.TokenVersion)
+}
+
+func normalizeTarget(cfg config.ShortcutsConfig, qualified bool) func(string) string {
+	return func(target string) string {
+		source, name := netbox.SplitTarget(target)
+		name = shortcuts.Normalize(name, cfg)
+		if qualified && source != "" {
+			return source + "/" + name
+		}
+		return name
+	}
+}
+
+// hostCompletions returns the cached hosts matching toComplete in a form that
+// starts with the typed text, because bash and fish only accept such
+// candidates. Without an instance prefix, a hostname that is unique across
+// all instances is offered bare ("web01"), so it completes like with a single
+// NetBox; connecting to it still checks every instance for ambiguity.
+// Names present in several instances stay qualified ("prod/web01").
+func hostCompletions(entries []cache.Entry, toComplete string) []string {
+	prefix := strings.ToLower(toComplete)
+	qualifiedInput := strings.Contains(prefix, "/")
+	instances := make(map[string]int)
+	for _, e := range entries {
+		_, name := netbox.SplitTarget(e.Name)
+		instances[strings.ToLower(name)]++
+	}
+	var out []string
+	for _, e := range entries {
+		source, name := netbox.SplitTarget(e.Name)
+		target := strings.ToLower(e.Name)
+		switch {
+		case source != "" && !qualifiedInput && strings.HasPrefix(strings.ToLower(name), prefix):
+			if instances[strings.ToLower(name)] == 1 {
+				out = append(out, name)
+			} else {
+				out = append(out, e.Name)
+			}
+		case strings.HasPrefix(target, prefix):
+			out = append(out, e.Name)
+		}
+	}
+	sort.Strings(out)
+	return out
+}

cmd/netssh/instances_test.go

@@ -0,0 +1,239 @@
+package main
+
+import (
+	"bytes"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/cache"
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/config"
+)
+
+func prepareInstancesTest(t *testing.T, officeURL, labURL string) *config.Config {
+	t.Helper()
+	dir := t.TempDir()
+	t.Setenv("HOME", t.TempDir())
+	t.Setenv("XDG_CONFIG_HOME", dir)
+	t.Setenv("XDG_CACHE_HOME", t.TempDir())
+	t.Setenv("NETSSH_NETBOX_URL", "")
+	t.Setenv("NETSSH_NETBOX_TOKEN", "")
+	t.Setenv("NETSSH_CACHE_PATH", filepath.Join(t.TempDir(), "hosts.json"))
+	t.Setenv("NETSSH_SHELL_ALIAS", "")
+	data := fmt.Sprintf("netboxes:\n  - name: office\n    url: %q\n    token: office-token\n  - name: lab\n    url: %q\n    token: lab-token\nresolver:\n  strategies: [primary_ip]\n", officeURL, labURL)
+	if err := os.WriteFile(filepath.Join(dir, "netssh.yaml"), []byte(data), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	cfg, err := config.Load()
+	if err != nil {
+		t.Fatal(err)
+	}
+	return cfg
+}
+
+func multiHost(name, ip string) connectionTestHost {
+	return connectionTestHost{ID: 1, Name: name, PrimaryIP4: &struct {
+		Address string `json:"address"`
+	}{Address: ip + "/24"}}
+}
+
+func TestRefreshStoresSameHostnameFromBothInstances(t *testing.T) {
+	office := connectionTestServer(t, []connectionTestHost{multiHost("web", "10.0.0.1")}, nil)
+	lab := connectionTestServer(t, []connectionTestHost{multiHost("web", "10.0.0.2")}, nil)
+	cfg := prepareInstancesTest(t, office.URL, lab.URL)
+	cmd := rootCmd()
+	cmd.SetArgs([]string{"cache", "refresh"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	c := cache.New(cfg.CachePath(), cfg.Cache.TTL)
+	if err := c.Load(); err != nil {
+		t.Fatal(err)
+	}
+	for name, ip := range map[string]string{"office/web": "10.0.0.1", "lab/web": "10.0.0.2"} {
+		got, fresh := c.Get(name)
+		if !fresh || got.IP != ip {
+			t.Fatalf("cache source collision: %+v, fresh=%v", got, fresh)
+		}
+	}
+	if len(c.All()) != 2 || c.NeedsRefresh(time.Hour) {
+		t.Fatal("full refresh is incomplete")
+	}
+}
+
+func TestRefreshFailureAndPerInstanceRefresh(t *testing.T) {
+	office := connectionTestServer(t, []connectionTestHost{multiHost("web", "10.0.0.1")}, nil)
+	failed := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { http.Error(w, "offline", 503) }))
+	defer failed.Close()
+	cfg := prepareInstancesTest(t, office.URL, failed.URL)
+	c := cache.New(cfg.CachePath(), cfg.Cache.TTL)
+	c.Upsert(cache.Entry{Name: "lab/old", Kind: "device", IP: "10.0.0.2"})
+	if err := c.Save(); err != nil {
+		t.Fatal(err)
+	}
+	cmd := rootCmd()
+	cmd.SetArgs([]string{"cache", "refresh"})
+	if err := cmd.Execute(); err == nil {
+		t.Fatal("failed instance marked as full refresh")
+	}
+	if err := c.Load(); err != nil {
+		t.Fatal(err)
+	}
+	if len(c.All()) != 1 || !c.NeedsRefresh(time.Hour) {
+		t.Fatal("partial refresh changed cache or full-refresh stamp")
+	}
+	cmd = rootCmd()
+	cmd.SetArgs([]string{"cache", "refresh", "--instance", "office"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if err := c.Load(); err != nil {
+		t.Fatal(err)
+	}
+	if len(c.All()) != 2 || !c.NeedsRefresh(time.Hour) {
+		t.Fatal("per-instance refresh lost other source or updated full stamp")
+	}
+}
+
+func TestLocalNotesCLIKeepsInstancesSeparate(t *testing.T) {
+	cfg := prepareInstancesTest(t, "https://office.example", "https://lab.example")
+	c := cache.New(cfg.CachePath(), cfg.Cache.TTL)
+	for _, name := range []string{"office/web", "lab/web"} {
+		c.Upsert(cache.Entry{Name: name, Kind: "device", IP: "10.0.0.1"})
+	}
+	if err := c.Save(); err != nil {
+		t.Fatal(err)
+	}
+	run := func(args ...string) (string, error) {
+		var out bytes.Buffer
+		cmd := rootCmd()
+		cmd.SetArgs(append([]string{"notes"}, args...))
+		cmd.SetOut(&out)
+		cmd.SetErr(&out)
+		err := cmd.Execute()
+		return out.String(), err
+	}
+	for _, source := range []string{"office", "lab"} {
+		if _, err := run("set", source+"/web", source+" note"); err != nil {
+			t.Fatal(err)
+		}
+	}
+	for _, source := range []string{"office", "lab"} {
+		got, err := run("show", source+"/web")
+		if err != nil || got != source+" note" {
+			t.Fatalf("CLI notes crossed sources: %q, %v", got, err)
+		}
+	}
+	if _, err := run("set", "web", "wrong note"); err == nil {
+		t.Fatal("ambiguous note target accepted")
+	}
+}
+
+func TestMultiInstanceWrapperHelper(t *testing.T) {
+	if target := os.Getenv("NETSSH_TEST_MULTI_TARGET"); target != "" {
+		runSSHWrapper([]string{target})
+		return
+	}
+}
+
+func TestWrapperRoutesQualifiedTargetsAndRejectsAmbiguity(t *testing.T) {
+	office := connectionTestServer(t, []connectionTestHost{multiHost("web", "10.0.0.1")}, nil)
+	lab := connectionTestServer(t, []connectionTestHost{multiHost("web", "10.0.0.2")}, nil)
+	cfg := prepareInstancesTest(t, office.URL, lab.URL)
+	c := cache.New(cfg.CachePath(), 3600)
+	if err := c.SetRefreshed(); err != nil {
+		t.Fatal(err)
+	}
+	bin := t.TempDir()
+	if err := os.WriteFile(filepath.Join(bin, "ssh"), []byte("#!/bin/sh\nprintf '%s\\n' \"$@\"\n"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	for target, want := range map[string]string{"office/web": "10.0.0.1", "lab/web": "10.0.0.2", "web": "ambiguous"} {
+		cmd := exec.Command(os.Args[0], "-test.run=^TestMultiInstanceWrapperHelper$")
+		cmd.Env = append(os.Environ(), "NETSSH_TEST_MULTI_TARGET="+target, "PATH="+bin+":"+os.Getenv("PATH"))
+		out, err := cmd.CombinedOutput()
+		if want == "ambiguous" {
+			if err == nil || !strings.Contains(string(out), "2 exact matches") {
+				t.Fatalf("ambiguous connection accepted: %s, %v", out, err)
+			}
+		} else if err != nil || !strings.Contains(string(out), want+"\n") {
+			t.Fatalf("wrong SSH destination for %s: %s, %v", target, out, err)
+		}
+	}
+}
+
+func TestQualifiedShortcutDoesNotMatchOtherInstance(t *testing.T) {
+	cfg := config.ShortcutsConfig{Domains: []string{".example.com"}, StripHyphens: true}
+	normalize := normalizeTarget(cfg, true)
+	if normalize("office/web-01.example.com") != normalize("office/web01") {
+		t.Fatal("qualified shortcut does not normalize")
+	}
+	if normalize("office/web01") == normalize("lab/web01") {
+		t.Fatal("qualified shortcut lost instance")
+	}
+}
+
+func TestRefreshCachesIndependentDevicesAndVMs(t *testing.T) {
+	office := connectionTestServer(t, []connectionTestHost{multiHost("router", "10.1.0.1")}, []connectionTestHost{multiHost("app", "10.1.0.2")})
+	lab := connectionTestServer(t, []connectionTestHost{multiHost("switch", "10.2.0.1")}, []connectionTestHost{multiHost("test-vm", "10.2.0.2")})
+	cfg := prepareInstancesTest(t, office.URL, lab.URL)
+	cmd := rootCmd()
+	cmd.SetArgs([]string{"cache", "refresh"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	c := cache.New(cfg.CachePath(), cfg.Cache.TTL)
+	if err := c.Load(); err != nil {
+		t.Fatal(err)
+	}
+	want := map[string]struct{ kind, ip string }{
+		"office/router": {"device", "10.1.0.1"}, "office/app": {"vm", "10.1.0.2"},
+		"lab/switch": {"device", "10.2.0.1"}, "lab/test-vm": {"vm", "10.2.0.2"},
+	}
+	if len(c.All()) != len(want) {
+		t.Fatalf("missing inventory entries: %+v", c.All())
+	}
+	for name, entry := range want {
+		got, fresh := c.Get(name)
+		if !fresh || got.Kind != entry.kind || got.IP != entry.ip {
+			t.Fatalf("wrong cached host %s: %+v", name, got)
+		}
+	}
+}
+
+func TestHostCompletionsMatchTypedText(t *testing.T) {
+	entries := []cache.Entry{
+		{Name: "prod/fsn1-bx1.example.com"},
+		{Name: "prod/fsn1-bx2.example.com"},
+		{Name: "stg/fsn1-bx2.example.com"},
+		{Name: "stg/hel1-tb1.example.com"},
+		{Name: "prod/HEL1-TB2"},
+	}
+	for _, tc := range []struct {
+		input string
+		want  []string
+	}{
+		// Unique names are bare; names in both instances stay qualified.
+		{"fsn1", []string{"fsn1-bx1.example.com", "prod/fsn1-bx2.example.com", "stg/fsn1-bx2.example.com"}},
+		{"hel1", []string{"HEL1-TB2", "hel1-tb1.example.com"}},
+		{"prod/", []string{"prod/HEL1-TB2", "prod/fsn1-bx1.example.com", "prod/fsn1-bx2.example.com"}},
+		{"stg/fsn", []string{"stg/fsn1-bx2.example.com"}},
+		// An instance name typed without the slash completes qualified targets.
+		{"st", []string{"stg/fsn1-bx2.example.com", "stg/hel1-tb1.example.com"}},
+	} {
+		if got := hostCompletions(entries, tc.input); !reflect.DeepEqual(got, tc.want) {
+			t.Errorf("%q: got %v, want %v", tc.input, got, tc.want)
+		}
+	}
+	// Single-instance caches are unchanged.
+	if got := hostCompletions([]cache.Entry{{Name: "web01"}, {Name: "db01"}}, "w"); !reflect.DeepEqual(got, []string{"web01"}) {
+		t.Errorf("single instance: %v", got)
+	}
+}

cmd/netssh/main.go

@@ -2,7 +2,9 @@ package main
 
 import (
 	"context"
+	"errors"
 	"fmt"
+	"io"
 	"os"
 	"os/exec"
 	"path/filepath"
@@ -12,7 +14,7 @@ import (
 	"text/tabwriter"
 	"time"
 
-	tea "github.com/charmbracelet/bubbletea"
+	tea "charm.land/bubbletea/v2"
 	"github.com/spf13/cobra"
 
 	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/cache"
@@ -22,7 +24,6 @@ import (
 	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/notes"
 	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/resolver"
 	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/setup"
-	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/shortcuts"
 	internalssh "git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/ssh"
 	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/tui"
 )
@@ -39,6 +40,8 @@ var managedSubcommands = map[string]bool{
 	"completion": true,
 	"__complete": true,
 	"help":       true,
+	"version":    true,
+	"uninstall":  true,
 }
 
 func main() {
@@ -48,6 +51,10 @@ func main() {
 		runTUI()
 		return
 	}
+	if args[0] == "--version" {
+		fmt.Printf("netssh %s\n", buildVersion())
+		return
+	}
 
 	if managedSubcommands[args[0]] {
 		if err := rootCmd().Execute(); err != nil {
@@ -65,7 +72,7 @@ func loadConfigOrSetup() *config.Config {
 	if err != nil {
 		fatalf("config: %v", err)
 	}
-	if cfg.NetBox.URL == "" {
+	if !cfg.HasNetBox() {
 		fmt.Fprintln(os.Stderr, "No configuration found. Starting setup…")
 		if err := setup.RunWizard(cfg); err != nil {
 			fatalf("setup: %v", err)
@@ -80,16 +87,21 @@ func loadConfigOrSetup() *config.Config {
 
 // runSSHWrapper resolves the target hostname via NetBox and execs the native ssh binary.
 func runSSHWrapper(args []string) {
+	flags, args, err := internalssh.ExtractWrapperFlags(args)
+	if err != nil {
+		fatalf("%v", err)
+	}
 	cfg := loadConfigOrSetup()
 
 	parsed := internalssh.Parse(args)
 	if parsed == nil {
 		// No destination found — pass arguments straight through to ssh.
-		if err := internalssh.Exec(args); err != nil {
-			fatalf("%v", err)
-		}
+		execSSH(internalssh.Result{Args: args}, flags)
 		return
 	}
+	connect := func(name, kind, ip string, tags []string) {
+		connectHost(cfg, flags, name, kind, ip, tags, parsed.DestIdx, args)
+	}
 
 	// Inject the configured default user if none was given on the command line.
 	if cfg.SSH.DefaultUser != "" && parsed.User == "" && !internalssh.HasUserFlag(args) {
@@ -102,15 +114,18 @@ func runSSHWrapper(args []string) {
 		parsed.DestIdx += 2
 	}
 
-	c := cache.New(cfg.Cache.Path, cfg.Cache.TTL)
+	c := cache.New(cfg.CachePath(), cfg.Cache.TTL)
 	_ = c.Load()
 	maybeBackgroundRefresh(cfg, c)
 
+	source, _ := netbox.SplitTarget(parsed.Host)
+	useCache := len(cfg.NetBoxes) == 0 || source != ""
+
 	// Cache hit with a fresh TTL — connect directly without querying NetBox.
-	if entry, fresh := c.Get(parsed.Host); fresh {
+	if entry, fresh := c.Get(parsed.Host); fresh && useCache {
 		c.MarkUsed(parsed.Host)
 		_ = c.Save()
-		connect(entry.IP, parsed, args)
+		connect(entry.Name, entry.Kind, entry.IP, entry.Tags)
 		return
 	}
 
@@ -118,13 +133,17 @@ func runSSHWrapper(args []string) {
 	// If a stale match is found, use the canonical name for the NetBox re-fetch below.
 	lookupHost := parsed.Host
 	shortcutsEnabled := len(cfg.Shortcuts.Domains) > 0 || cfg.Shortcuts.StripHyphens
-	if shortcutsEnabled {
-		normalize := shortcuts.MakeNormalizer(cfg.Shortcuts)
-		if entry, found, fresh := c.GetByShortcut(lookupHost, normalize); found {
+	if cached, _ := c.Get(lookupHost); shortcutsEnabled && cached.Name == "" && useCache {
+		normalize := normalizeTarget(cfg.Shortcuts, source != "")
+		entry, found, fresh, err := c.GetByShortcut(lookupHost, normalize)
+		if err != nil {
+			fatalf("%v", err)
+		}
+		if found {
 			if fresh {
 				c.MarkUsed(entry.Name)
 				_ = c.Save()
-				connect(entry.IP, parsed, args)
+				connect(entry.Name, entry.Kind, entry.IP, entry.Tags)
 				return
 			}
 			// Stale shortcut match — use canonical name for NetBox re-fetch.
@@ -132,50 +151,33 @@ func runSSHWrapper(args []string) {
 		}
 	}
 
-	if cfg.NetBox.URL == "" {
+	if !cfg.HasNetBox() {
 		fatalf("netbox.url is not configured (~/.config/netssh.yaml)")
 	}
-	nbClient := netbox.NewClient(cfg.NetBox.URL, cfg.NetBox.Token, cfg.NetBox.TokenVersion)
+	nbClient := newNetBoxClient(cfg)
 
 	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
 	defer cancel()
 
-	entries, err := nbClient.Search(ctx, lookupHost, netbox.SearchOptions{})
+	target, err := findSSHHost(ctx, nbClient, lookupHost, cfg.Shortcuts.Domains)
+	if errors.Is(err, netbox.ErrHostNotFound) && !useCache && shortcutsEnabled {
+		entry, found, _, cacheErr := c.GetByShortcut(parsed.Host, normalizeTarget(cfg.Shortcuts, false))
+		if cacheErr != nil {
+			fatalf("%v", cacheErr)
+		}
+		if found {
+			target, err = findSSHHost(ctx, nbClient, entry.Name, cfg.Shortcuts.Domains)
+		}
+	}
 	if err != nil {
-		fatalf("NetBox search failed: %v", err)
+		fatalf("NetBox: %v", err)
 	}
 
-	var target *netbox.HostEntry
-	for i, e := range entries {
-		if strings.EqualFold(e.Name, lookupHost) {
-			target = &entries[i]
-			break
-		}
-	}
-
-	// Domain expansion: if still no match and the input has no dots, try appending
-	// each configured domain suffix and re-querying NetBox.
-	if target == nil && !strings.Contains(parsed.Host, ".") && len(cfg.Shortcuts.Domains) > 0 {
-		for _, domain := range cfg.Shortcuts.Domains {
-			expanded := parsed.Host + domain
-			expandedEntries, searchErr := nbClient.Search(ctx, expanded, netbox.SearchOptions{})
-			if searchErr != nil {
-				continue
-			}
-			for i, e := range expandedEntries {
-				if strings.EqualFold(e.Name, expanded) {
-					target = &expandedEntries[i]
-					break
-				}
-			}
-			if target != nil {
-				break
-			}
-		}
-	}
-
-	if target == nil {
-		fatalf("host %q not found in NetBox", parsed.Host)
+	if cached, fresh := c.Get(target.Target()); fresh && cached.Kind == target.Kind {
+		c.MarkUsed(target.Target())
+		_ = c.Save()
+		connect(cached.Name, cached.Kind, cached.IP, cached.Tags)
+		return
 	}
 
 	chain, err := resolver.New(cfg.Resolver)
@@ -183,21 +185,56 @@ func runSSHWrapper(args []string) {
 		fatalf("resolver: %v", err)
 	}
 
-	ip, err := chain.Resolve(ctx, target, nbClient)
+	ip, err := chain.Resolve(ctx, &target, nbClient)
 	if err != nil {
 		fatalf("IP resolution for %q: %v", parsed.Host, err)
 	}
 
-	c.Upsert(cache.Entry{Name: target.Name, IP: ip, Kind: target.Kind, Tags: target.Tags})
-	c.MarkUsed(target.Name)
+	c.Upsert(cache.Entry{Name: target.Target(), IP: ip, Kind: target.Kind, Tags: target.Tags})
+	c.MarkUsed(target.Target())
 	_ = c.Save()
 
-	connect(ip, parsed, args)
+	connect(target.Target(), target.Kind, ip, target.Tags)
 }
 
-func connect(ip string, parsed *internalssh.ParsedArgs, originalArgs []string) {
-	newArgs := internalssh.ReplaceHost(originalArgs, parsed.DestIdx, ip)
-	if err := internalssh.Exec(newArgs); err != nil {
+// findSSHHost uses the paginated, ambiguity-checking lookup for connection
+// targets. Only a genuine missing host permits trying configured suffixes.
+func findSSHHost(ctx context.Context, client *netbox.Client, name string, domains []string) (netbox.HostEntry, error) {
+	target, err := client.FindHost(ctx, name, "")
+	if !errors.Is(err, netbox.ErrHostNotFound) || strings.Contains(name, ".") {
+		return target, err
+	}
+	for _, domain := range domains {
+		domain = strings.TrimPrefix(strings.TrimSpace(domain), ".")
+		if domain == "" {
+			continue
+		}
+		target, err = client.FindHost(ctx, name+"."+domain, "")
+		if !errors.Is(err, netbox.ErrHostNotFound) {
+			return target, err
+		}
+	}
+	return netbox.HostEntry{}, fmt.Errorf("%w: %q", netbox.ErrHostNotFound, name)
+}
+
+// connectHost applies the SSH options configured for the host and execs ssh.
+// target is the cache/selector name, which may carry an instance prefix.
+func connectHost(cfg *config.Config, flags internalssh.WrapperFlags, target, kind, ip string, tags []string, destIdx int, args []string) {
+	instance, name := netbox.SplitTarget(target)
+	opts := cfg.SSHOptionsFor(config.SSHHost{Instance: instance, Name: name, Kind: kind, Tags: tags})
+	execSSH(internalssh.Apply(args, destIdx, internalssh.Host{Name: name, IP: ip}, opts, flags), flags)
+}
+
+// execSSH replaces the process with ssh, or prints the command for --dry-run.
+func execSSH(result internalssh.Result, flags internalssh.WrapperFlags) {
+	if flags.DryRun {
+		fmt.Println(internalssh.Quote(append([]string{"ssh"}, result.Args...)))
+		return
+	}
+	if result.Notice != "" {
+		fmt.Fprintf(os.Stderr, "netssh: %s\n", result.Notice)
+	}
+	if err := internalssh.Exec(result.Args); err != nil {
 		fatalf("%v", err)
 	}
 }
@@ -206,18 +243,18 @@ func connect(ip string, parsed *internalssh.ParsedArgs, originalArgs []string) {
 func runTUI() {
 	cfg := loadConfigOrSetup()
 
-	c := cache.New(cfg.Cache.Path, cfg.Cache.TTL)
+	c := cache.New(cfg.CachePath(), cfg.Cache.TTL)
 	_ = c.Load()
 	maybeBackgroundRefresh(cfg, c)
 
 	var nbClient *netbox.Client
-	if cfg.NetBox.URL != "" {
-		nbClient = netbox.NewClient(cfg.NetBox.URL, cfg.NetBox.Token, cfg.NetBox.TokenVersion)
+	if cfg.HasNetBox() {
+		nbClient = newNetBoxClient(cfg)
 	}
 
 	m := tui.New(nbClient, c, cfg.SSH.DefaultUser, cfg.SSH.DefaultPort)
 	m.SetNotes(notes.New(cfg.NetBox.URL, nbClient))
-	p := tea.NewProgram(m, tea.WithAltScreen())
+	p := tea.NewProgram(m)
 	final, err := p.Run()
 	if err != nil {
 		fatalf("TUI: %v", err)
@@ -233,8 +270,10 @@ func runTUI() {
 	}
 
 	// Revalidate stale or live TUI results through the configured resolver chain.
-	if cached, fresh := c.Get(host.Name); fresh {
+	var tags []string
+	if cached, fresh := c.Get(host.Name); fresh && cached.Kind == host.Kind {
 		host.IP = cached.IP
+		tags = cached.Tags
 	} else {
 		if nbClient == nil {
 			fatalf("cannot resolve %q: NetBox is not configured", host.Name)
@@ -253,7 +292,8 @@ func runTUI() {
 		if err != nil {
 			fatalf("IP resolution: %v", err)
 		}
-		c.Upsert(cache.Entry{Name: target.Name, IP: host.IP, Kind: target.Kind, Tags: target.Tags})
+		c.Upsert(cache.Entry{Name: target.Target(), IP: host.IP, Kind: target.Kind, Tags: target.Tags})
+		tags = target.Tags
 	}
 	fmt.Fprintf(os.Stderr, "Connecting to %s (%s)…\n", host.Name, host.IP)
 
@@ -281,9 +321,7 @@ func runTUI() {
 	c.MarkUsed(host.Name)
 	_ = c.Save()
 
-	if err := internalssh.Exec(sshArgs); err != nil {
-		fatalf("%v", err)
-	}
+	connectHost(cfg, internalssh.WrapperFlags{}, host.Name, host.Kind, host.IP, tags, len(sshArgs)-1, sshArgs)
 }
 
 // --- cobra root + subcommands ---
@@ -298,12 +336,16 @@ func rootCmd() *cobra.Command {
 			if err != nil {
 				return nil, cobra.ShellCompDirectiveError
 			}
-			c := cache.New(cfg.Cache.Path, cfg.Cache.TTL)
+			c := cache.New(cfg.CachePath(), cfg.Cache.TTL)
 			_ = c.Load()
 
-			var completions []cobra.Completion
-			for _, e := range c.Search(toComplete) {
-				completions = append(completions, cobra.Completion(e.Name))
+			hosts := hostCompletions(c.All(), toComplete)
+			if limit := cfg.Completion.MaxResults; limit > 0 && len(hosts) > limit {
+				hosts = hosts[:limit]
+			}
+			completions := make([]cobra.Completion, 0, len(hosts))
+			for _, host := range hosts {
+				completions = append(completions, cobra.Completion(host))
 			}
 			// Subcommands at the end, after all hostnames.
 			for _, sub := range cmd.Commands() {
@@ -315,13 +357,24 @@ func rootCmd() *cobra.Command {
 		},
 	}
 
-	root.AddCommand(notesCmd(), configureCmd(), searchCmd(), cacheCmd(), aliasCmd(), hookCmd(), shellInitCmd())
+	root.AddCommand(notesCmd(), configureCmd(), searchCmd(), cacheCmd(), aliasCmd(), hookCmd(), shellInitCmd(), versionCmd(), uninstallCmd())
 
 	// cobra builds the "completion" command lazily; force init so we can extend it.
 	root.InitDefaultCompletionCmd()
 	for _, cmd := range root.Commands() {
 		if cmd.Name() == "completion" {
 			cmd.AddCommand(completionInstallCmd(root))
+			// Cobra's zsh script spawns a subshell per line and sends every host
+			// through _describe, which hangs with thousands of cached hosts.
+			for _, sub := range cmd.Commands() {
+				if sub.Name() == "zsh" {
+					sub.RunE = func(cmd *cobra.Command, args []string) error {
+						_, err := io.WriteString(cmd.OutOrStdout(), hook.ZshCompletionScript)
+						return err
+					}
+					sub.Run = nil
+				}
+			}
 			break
 		}
 	}
@@ -359,15 +412,10 @@ func completionInstallCmd(root *cobra.Command) *cobra.Command {
 			case "zsh":
 				dir = filepath.Join(os.Getenv("HOME"), ".zfunc")
 				file = filepath.Join(dir, "_netssh")
-				gen = func() ([]byte, error) {
-					var buf strings.Builder
-					err := root.GenZshCompletion(&buf)
-					return []byte(buf.String()), err
-				}
-				note = "Make sure ~/.zfunc is in your fpath:\n  fpath=(~/.zfunc $fpath)\n  autoload -Uz compinit && compinit"
+				gen = func() ([]byte, error) { return []byte(hook.ZshCompletionScript), nil }
+				note = hook.ZshCompletionNote(dir)
 			case "fish":
-				configDir, _ := os.UserConfigDir()
-				dir = filepath.Join(configDir, "fish", "completions")
+				dir = filepath.Join(hook.FishConfigDir(), "completions")
 				file = filepath.Join(dir, "netssh.fish")
 				gen = func() ([]byte, error) {
 					var buf strings.Builder
@@ -389,7 +437,17 @@ func completionInstallCmd(root *cobra.Command) *cobra.Command {
 			if err := os.WriteFile(file, script, 0o644); err != nil {
 				return fmt.Errorf("writing %s: %w", file, err)
 			}
+			cfg, err := config.Load()
+			if err != nil {
+				return err
+			}
+			if err := hook.SyncCommandCompletion(cfg.Shell.Alias); err != nil {
+				return err
+			}
 			fmt.Printf("Completion installed → %s\n%s\n", file, note)
+			if cfg.Shell.Alias != "" {
+				fmt.Printf("Completion also enabled for alias %q.\n", cfg.Shell.Alias)
+			}
 			return nil
 		},
 	}
@@ -402,9 +460,9 @@ func configureCmd() *cobra.Command {
 		Use:   "configure",
 		Short: "Interactively configure netssh",
 		RunE: func(cmd *cobra.Command, args []string) error {
-			cfg, _ := config.Load()
-			if cfg == nil {
-				cfg = &config.Config{}
+			cfg, err := config.Load()
+			if err != nil {
+				return err
 			}
 			return setup.RunWizard(cfg)
 		},
@@ -421,7 +479,7 @@ func searchCmd() *cobra.Command {
 			if err != nil {
 				return err
 			}
-			c := cache.New(cfg.Cache.Path, cfg.Cache.TTL)
+			c := cache.New(cfg.CachePath(), cfg.Cache.TTL)
 			if err := c.Load(); err != nil {
 				return err
 			}
@@ -455,7 +513,7 @@ func cacheListCmd() *cobra.Command {
 			if err != nil {
 				return err
 			}
-			c := cache.New(cfg.Cache.Path, cfg.Cache.TTL)
+			c := cache.New(cfg.CachePath(), cfg.Cache.TTL)
 			if err := c.Load(); err != nil {
 				return err
 			}
@@ -481,7 +539,7 @@ func cacheClearCmd() *cobra.Command {
 			if err != nil {
 				return err
 			}
-			c := cache.New(cfg.Cache.Path, cfg.Cache.TTL)
+			c := cache.New(cfg.CachePath(), cfg.Cache.TTL)
 			c.Clear()
 			if err := c.Save(); err != nil {
 				return err
@@ -493,7 +551,7 @@ func cacheClearCmd() *cobra.Command {
 }
 
 func cacheRefreshCmd() *cobra.Command {
-	var filterTag, filterKind string
+	var filterTag, filterKind, filterInstance string
 	cmd := &cobra.Command{
 		Use:   "refresh",
 		Short: "Re-fetch all known hosts from NetBox",
@@ -502,21 +560,28 @@ func cacheRefreshCmd() *cobra.Command {
 			if err != nil {
 				return err
 			}
-			if cfg.NetBox.URL == "" {
+			if !cfg.HasNetBox() {
 				return fmt.Errorf("netbox.url is not configured")
 			}
 
-			nbClient := netbox.NewClient(cfg.NetBox.URL, cfg.NetBox.Token, cfg.NetBox.TokenVersion)
+			nbClient := newNetBoxClient(cfg)
 			ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
 			defer cancel()
 
 			opts := netbox.SearchOptions{Tag: filterTag, Kind: filterKind}
-			entries, err := nbClient.SearchAll(ctx, "", opts)
+			query := ""
+			if filterInstance != "" {
+				if !nbClient.MultipleSources() {
+					return fmt.Errorf("--instance requires named netboxes configuration")
+				}
+				query = filterInstance + "/"
+			}
+			entries, err := nbClient.SearchAll(ctx, query, opts)
 			if err != nil {
 				return fmt.Errorf("NetBox: %w", err)
 			}
 
-			c := cache.New(cfg.Cache.Path, cfg.Cache.TTL)
+			c := cache.New(cfg.CachePath(), cfg.Cache.TTL)
 			_ = c.Load()
 
 			chain, err := resolver.New(cfg.Resolver)
@@ -524,32 +589,37 @@ func cacheRefreshCmd() *cobra.Command {
 				return fmt.Errorf("resolver: %w", err)
 			}
 			written := 0
+			nameCounts := make(map[string]int)
+			for _, e := range entries {
+				nameCounts[strings.ToLower(e.Target())]++
+			}
 			for i := range entries {
 				e := &entries[i]
+				if nameCounts[strings.ToLower(e.Target())] > 1 {
+					c.Delete(e.Target())
+					fmt.Fprintf(os.Stderr, "warning: skipping ambiguous hostname %q\n", e.Name)
+					continue
+				}
 
-				var ip string
-				if chain != nil {
-					if resolved, err := chain.Resolve(ctx, e, nbClient); err == nil {
-						ip = resolved
+				ip, err := chain.Resolve(ctx, e, nbClient)
+				if err != nil {
+					// Do not turn a failed configured strategy into a fresh
+					// primary-IP cache hit that bypasses the resolver.
+					if ctx.Err() != nil {
+						return ctx.Err()
 					}
+					c.Delete(e.Target())
+					fmt.Fprintf(os.Stderr, "warning: skipping %s: %v\n", e.Name, err)
+					continue
 				}
-				if ip == "" {
-					ip = e.PrimaryIP4
-				}
-				if ip == "" {
-					ip = e.PrimaryIP6
-				}
-
-				if ip != "" {
-					c.Upsert(cache.Entry{Name: e.Name, IP: ip, Kind: e.Kind, Tags: e.Tags})
-					written++
-				}
+				c.Upsert(cache.Entry{Name: e.Target(), IP: ip, Kind: e.Kind, Tags: e.Tags})
+				written++
 			}
 
 			if err := c.Save(); err != nil {
 				return err
 			}
-			if filterTag == "" && filterKind == "" {
+			if filterTag == "" && filterKind == "" && filterInstance == "" {
 				if err := c.SetRefreshed(); err != nil {
 					fmt.Fprintf(os.Stderr, "warning: could not update refresh timestamp: %v\n", err)
 				}
@@ -565,28 +635,13 @@ func cacheRefreshCmd() *cobra.Command {
 	}
 	cmd.Flags().StringVar(&filterTag, "tag", "", "Filter by NetBox tag slug (e.g. prod)")
 	cmd.Flags().StringVar(&filterKind, "kind", "", "Filter by kind: device or vm")
+	cmd.Flags().StringVar(&filterInstance, "instance", "", "Refresh only this named NetBox instance")
 	return cmd
 }
 
 // buildAliasEntries computes the sorted, deduplicated alias list from the cache.
 func buildAliasEntries(c *cache.Cache, cfg config.Config) []hook.AliasEntry {
-	all := c.All()
-	sort.Slice(all, func(i, j int) bool { return all[i].Name < all[j].Name })
-
-	seen := make(map[string]string)
-	var out []hook.AliasEntry
-	for _, e := range all {
-		name := shortcuts.AliasName(e.Name, cfg.Shortcuts)
-		if name == "" {
-			continue
-		}
-		if _, dup := seen[name]; dup {
-			continue
-		}
-		seen[name] = e.Name
-		out = append(out, hook.AliasEntry{Name: name, Host: e.Name})
-	}
-	return out
+	return hook.BuildAliasEntries(c.All(), cfg)
 }
 
 func aliasCmd() *cobra.Command {
@@ -609,7 +664,7 @@ Or use in a script:
 			if err != nil {
 				return err
 			}
-			c := cache.New(cfg.Cache.Path, cfg.Cache.TTL)
+			c := cache.New(cfg.CachePath(), cfg.Cache.TTL)
 			if err := c.Load(); err != nil {
 				return err
 			}
@@ -627,12 +682,12 @@ Or use in a script:
 			case "fish":
 				fmt.Printf("# netssh aliases (%d hosts) — source with: netssh alias --shell fish | source\n", len(entries))
 				for _, e := range entries {
-					fmt.Printf("alias %s 'netssh %s'\n", e.Name, e.Host)
+					fmt.Println(e.Definition("fish"))
 				}
 			default:
 				fmt.Printf("# netssh aliases (%d hosts) — source with: eval \"$(netssh alias)\"\n", len(entries))
 				for _, e := range entries {
-					fmt.Printf("alias %s='netssh %s'\n", e.Name, e.Host)
+					fmt.Println(e.Definition("bash"))
 				}
 			}
 			return nil
@@ -651,17 +706,15 @@ func shellInitCmd() *cobra.Command {
 		Hidden: true,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			cfg, err := config.Load()
-			if err != nil || cfg.NetBox.URL == "" {
+			if err != nil {
 				return nil
 			}
-			c := cache.New(cfg.Cache.Path, cfg.Cache.TTL)
+			c := cache.New(cfg.CachePath(), cfg.Cache.TTL)
 			_ = c.Load()
 
 			// Regenerate alias files from the current cache every shell start
 			// so aliases are always up-to-date even before a refresh completes.
-			if entries := buildAliasEntries(c, *cfg); len(entries) > 0 {
-				_ = hook.WriteAliasFiles(entries)
-			}
+			_ = hook.WriteAliasFiles(buildAliasEntries(c, *cfg))
 
 			maybeBackgroundRefresh(cfg, c)
 			return nil
@@ -683,9 +736,11 @@ func hookInstallCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "install",
 		Short: "Add netssh shell-init to your shell profile",
-		Long: `Appends a single line to your shell profile that runs 'netssh shell-init'
-on every new shell session. shell-init checks whether the cache is older
-than 24 hours and, if so, starts a background refresh — no delay to your prompt.
+		Long: `Adds a marked block (# >>> netssh >>> … # <<< netssh <<<) to your shell
+profile that runs 'netssh shell-init' on every new shell session and, for zsh,
+registers the completion. Unmarked entries from older versions are replaced.
+shell-init checks whether the cache is older than 24 hours and, if so, starts
+a background refresh — no delay to your prompt.
 
 After installation, reload your profile or open a new shell.`,
 		RunE: func(cmd *cobra.Command, args []string) error {
@@ -697,17 +752,12 @@ After installation, reload your profile or open a new shell.`,
 				return err
 			}
 
-			installed, err := hook.Install(profile)
+			// The managed block also sources the aliases (bash/zsh) and registers
+			// zsh completion; fish uses conf.d auto-sourcing instead.
+			installed, err := hook.Install(profile, shell)
 			if err != nil {
 				return err
 			}
-			// For bash/zsh: also add the source line so aliases are loaded on startup.
-			// Fish uses conf.d auto-sourcing — no explicit source line needed.
-			if shell != "fish" {
-				if _, err := hook.InstallAliasesSource(profile); err != nil {
-					return err
-				}
-			}
 
 			if !installed {
 				fmt.Printf("Hook already installed in %s\n", profile)
@@ -717,8 +767,8 @@ After installation, reload your profile or open a new shell.`,
 
 			// Generate the aliases file immediately so it is ready on the next shell start.
 			cfg, cfgErr := config.Load()
-			if cfgErr == nil && cfg.NetBox.URL != "" {
-				c := cache.New(cfg.Cache.Path, cfg.Cache.TTL)
+			if cfgErr == nil && cfg.HasNetBox() {
+				c := cache.New(cfg.CachePath(), cfg.Cache.TTL)
 				if _ = c.Load(); true {
 					if entries := buildAliasEntries(c, *cfg); len(entries) > 0 {
 						if err := hook.WriteAliasFiles(entries); err != nil {
@@ -770,7 +820,7 @@ func hookUninstallCmd() *cobra.Command {
 // maybeBackgroundRefresh starts a background `netssh cache refresh` if the cache
 // has not been fully refreshed within the last 24 hours.
 func maybeBackgroundRefresh(cfg *config.Config, c *cache.Cache) {
-	if cfg.NetBox.URL == "" {
+	if !cfg.HasNetBox() {
 		return
 	}
 	if !c.NeedsRefresh(24 * time.Hour) {

cmd/netssh/notes.go

@@ -34,11 +34,11 @@ func notesCmd() *cobra.Command {
 				return err
 			}
 			var client *netbox.Client
-			if cfg.NetBox.URL != "" {
-				client = netbox.NewClient(cfg.NetBox.URL, cfg.NetBox.Token, cfg.NetBox.TokenVersion)
+			if cfg.HasNetBox() {
+				client = newNetBoxClient(cfg)
 			}
 			host := netbox.HostEntry{Name: args[0], Kind: kind}
-			c := cache.New(cfg.Cache.Path, cfg.Cache.TTL)
+			c := cache.New(cfg.CachePath(), cfg.Cache.TTL)
 			if err := c.Load(); err != nil {
 				return err
 			}
@@ -46,13 +46,23 @@ func notesCmd() *cobra.Command {
 			if !remote {
 				cached = c.All()
 			}
+			query := host.Name
+			source, rawName := netbox.SplitTarget(query)
+			var matches []cache.Entry
 			for _, entry := range cached {
-				if strings.EqualFold(entry.Name, host.Name) && (kind == "" || kind == entry.Kind) {
-					host.Name = entry.Name
-					host.Kind = entry.Kind
-					break
+				_, entryName := netbox.SplitTarget(entry.Name)
+				if (kind == "" || kind == entry.Kind) && (strings.EqualFold(entry.Name, query) || (source == "" && strings.EqualFold(entryName, rawName))) {
+					matches = append(matches, entry)
 				}
 			}
+			if len(matches) > 1 {
+				return fmt.Errorf("ambiguous hostname %q; use instance/hostname", query)
+			}
+			if len(matches) == 1 {
+				host.Name = matches[0].Name
+				host.Kind = matches[0].Kind
+			}
+
 			if !remote && host.Kind == "" {
 				return fmt.Errorf("host is not cached; specify --kind device or --kind vm")
 			}

cmd/netssh/notes_test.go

@@ -2,6 +2,8 @@ package main
 
 import (
 	"bytes"
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/hook"
+	"os"
 	"path/filepath"
 	"strings"
 	"testing"
@@ -38,3 +40,37 @@ func TestLocalNotesCLI(t *testing.T) {
 		t.Fatalf("clear: %q, %v", out, err)
 	}
 }
+
+func TestShellInitUpdatesAndRemovesCommandAliasWithoutHosts(t *testing.T) {
+	t.Setenv("HOME", t.TempDir())
+	t.Setenv("XDG_CONFIG_HOME", t.TempDir())
+	t.Setenv("XDG_CACHE_HOME", t.TempDir())
+	t.Setenv("NETSSH_CACHE_PATH", filepath.Join(t.TempDir(), "hosts.json"))
+	t.Setenv("NETSSH_NETBOX_URL", "")
+	t.Setenv("NETSSH_SHELL_ALIAS", "j")
+	run := func() {
+		t.Helper()
+		root := rootCmd()
+		root.SetArgs([]string{"shell-init"})
+		if err := root.Execute(); err != nil {
+			t.Fatal(err)
+		}
+	}
+	run()
+	data, err := os.ReadFile(hook.AliasesPath())
+	if err != nil || !strings.Contains(string(data), "alias j='netssh'") {
+		t.Fatalf("alias missing: %s, %v", data, err)
+	}
+	t.Setenv("NETSSH_SHELL_ALIAS", "k")
+	run()
+	data, _ = os.ReadFile(hook.AliasesPath())
+	if strings.Contains(string(data), "alias j=") || !strings.Contains(string(data), "alias k='netssh'") {
+		t.Fatalf("alias change: %s", data)
+	}
+	t.Setenv("NETSSH_SHELL_ALIAS", "")
+	run()
+	data, _ = os.ReadFile(hook.AliasesPath())
+	if strings.Contains(string(data), "alias k=") {
+		t.Fatalf("stale alias: %s", data)
+	}
+}

cmd/netssh/uninstall.go

@@ -0,0 +1,250 @@
+package main
+
+import (
+	"bufio"
+	"errors"
+	"fmt"
+	"io"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/spf13/cobra"
+
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/config"
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/hook"
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/storage"
+)
+
+// uninstallPlan lists everything netssh has written to this machine.
+type uninstallPlan struct {
+	Profiles []string // shell profiles with a netssh block or legacy lines
+	Paths    []string // files and directories to delete
+	Config   string   // config file to back up and delete; empty when kept
+	Binaries []string
+}
+
+func buildUninstallPlan(cfg *config.Config, keepConfig bool) uninstallPlan {
+	var plan uninstallPlan
+	seen := make(map[string]bool)
+	addPath := func(path string) {
+		if path == "" || seen[path] {
+			return
+		}
+		if _, err := os.Lstat(path); err == nil {
+			seen[path] = true
+			plan.Paths = append(plan.Paths, path)
+		}
+	}
+
+	for _, profile := range hook.ProfileCandidates() {
+		target, err := filepath.EvalSymlinks(profile)
+		if err != nil || seen[target] {
+			continue
+		}
+		seen[target] = true
+		if hook.HasEntries(profile) {
+			plan.Profiles = append(plan.Profiles, profile)
+		}
+	}
+
+	aliases := []string{hook.CompletionAliasState()}
+	if cfg != nil {
+		aliases = append(aliases, cfg.Shell.Alias)
+	}
+	for _, path := range hook.CompletionFiles(aliases...) {
+		if hook.IsGenerated(path) {
+			addPath(path)
+		}
+	}
+
+	// The cache directory holds hosts, aliases, refresh stamps, and instance caches.
+	cacheDir := filepath.Dir(hook.AliasesPath())
+	addPath(cacheDir)
+	if cfg != nil {
+		for _, path := range []string{cfg.Cache.Path, cfg.CachePath()} {
+			if path == "" || strings.HasPrefix(path, cacheDir+string(filepath.Separator)) {
+				continue
+			}
+			addPath(path)
+			addPath(path + ".lock")
+			addPath(filepath.Join(filepath.Dir(path), "last_refresh"))
+			if strings.HasPrefix(filepath.Base(filepath.Dir(path)), "instances-") {
+				addPath(filepath.Dir(path))
+			}
+		}
+	}
+
+	if !keepConfig {
+		if _, err := os.Stat(config.Path()); err == nil {
+			plan.Config = config.Path()
+		}
+		// Local server notes live next to the config file.
+		addPath(filepath.Join(filepath.Dir(config.Path()), "netssh"))
+	}
+
+	plan.Binaries = installedBinaries()
+	return plan
+}
+
+// installedBinaries finds the running binary and any other netssh in PATH.
+func installedBinaries() []string {
+	var out []string
+	seen := make(map[string]bool)
+	add := func(path string) {
+		real, err := filepath.EvalSymlinks(path)
+		if err != nil || seen[real] {
+			return
+		}
+		if info, err := os.Stat(real); err != nil || info.IsDir() || filepath.Base(real) != "netssh" {
+			return
+		}
+		seen[real] = true
+		out = append(out, real)
+	}
+	if self, err := os.Executable(); err == nil {
+		add(self)
+	}
+	for _, dir := range filepath.SplitList(os.Getenv("PATH")) {
+		if dir != "" {
+			add(filepath.Join(dir, "netssh"))
+		}
+	}
+	return out
+}
+
+func (p uninstallPlan) empty() bool {
+	return len(p.Profiles) == 0 && len(p.Paths) == 0 && p.Config == "" && len(p.Binaries) == 0
+}
+
+func (p uninstallPlan) print(w io.Writer) {
+	for _, profile := range p.Profiles {
+		fmt.Fprintf(w, "  edit    %s (remove netssh entries)\n", profile)
+	}
+	for _, path := range p.Paths {
+		fmt.Fprintf(w, "  delete  %s\n", path)
+	}
+	if p.Config != "" {
+		fmt.Fprintf(w, "  delete  %s (a backup is kept)\n", p.Config)
+	}
+	for _, binary := range p.Binaries {
+		fmt.Fprintf(w, "  delete  %s\n", binary)
+	}
+}
+
+// execute applies the plan. It continues after errors so that one protected
+// file does not leave the rest behind, and returns commands that need sudo.
+func (p uninstallPlan) execute(w io.Writer) (manual []string, err error) {
+	var errs []error
+	for _, profile := range p.Profiles {
+		if _, err := hook.Uninstall(profile); err != nil {
+			errs = append(errs, err)
+			continue
+		}
+		fmt.Fprintf(w, "cleaned  %s\n", profile)
+	}
+	for _, path := range p.Paths {
+		if err := os.RemoveAll(path); err != nil {
+			errs = append(errs, err)
+			continue
+		}
+		fmt.Fprintf(w, "removed  %s\n", path)
+	}
+	if p.Config != "" {
+		backup, err := backupConfig(p.Config)
+		if err != nil {
+			errs = append(errs, fmt.Errorf("config not removed: %w", err))
+		} else if err := os.Remove(p.Config); err != nil {
+			errs = append(errs, err)
+		} else {
+			fmt.Fprintf(w, "removed  %s (backup: %s)\n", p.Config, backup)
+		}
+	}
+	for _, binary := range p.Binaries {
+		if err := os.Remove(binary); err != nil {
+			if errors.Is(err, fs.ErrPermission) {
+				manual = append(manual, "sudo rm -f "+shellQuote(binary))
+				continue
+			}
+			errs = append(errs, err)
+			continue
+		}
+		fmt.Fprintf(w, "removed  %s\n", binary)
+	}
+	return manual, errors.Join(errs...)
+}
+
+// backupConfig keeps a private copy, because the config holds API tokens.
+func backupConfig(path string) (string, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return "", err
+	}
+	backup := path + ".backup-" + time.Now().Format("20060102-150405")
+	if err := storage.WriteFile(backup, data, 0o600); err != nil {
+		return "", err
+	}
+	return backup, nil
+}
+
+func shellQuote(s string) string {
+	return "'" + strings.ReplaceAll(s, "'", `'\''`) + "'"
+}
+
+func uninstallCmd() *cobra.Command {
+	var keepConfig, yes, dryRun bool
+	cmd := &cobra.Command{
+		Use:   "uninstall",
+		Short: "Remove netssh, its shell integration, cache, and config",
+		Long: `Removes everything netssh and install.sh have set up:
+
+  - netssh blocks and unmarked entries of older versions in bash, zsh, and fish profiles
+  - shell completion files (bash, zsh, fish, oh-my-zsh cache, command alias)
+  - the cache directory with hosts, aliases, and per-instance caches
+  - the config file (a private backup is kept) and local server notes
+  - the netssh binary
+
+Use --keep-config to keep the config file and notes for a reinstall.`,
+		Args: cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			cfg, err := config.Load()
+			if err != nil {
+				// A broken config must not block the uninstall.
+				fmt.Fprintf(os.Stderr, "warning: %v\n", err)
+				cfg = nil
+			}
+			plan := buildUninstallPlan(cfg, keepConfig)
+			out := cmd.OutOrStdout()
+			if plan.empty() {
+				fmt.Fprintln(out, "Nothing to remove.")
+				return nil
+			}
+			fmt.Fprintln(out, "netssh uninstall will:")
+			plan.print(out)
+			if dryRun {
+				return nil
+			}
+			if !yes {
+				fmt.Fprint(out, "Proceed? [y/N] ")
+				answer, _ := bufio.NewReader(cmd.InOrStdin()).ReadString('\n')
+				if a := strings.ToLower(strings.TrimSpace(answer)); a != "y" && a != "yes" {
+					return fmt.Errorf("aborted")
+				}
+			}
+			manual, err := plan.execute(out)
+			for _, command := range manual {
+				fmt.Fprintf(out, "Permission denied. Run: %s\n", command)
+			}
+			if len(plan.Profiles) > 0 {
+				fmt.Fprintln(out, "Open a new terminal. For zsh, also run: rm -f ~/.zcompdump*")
+			}
+			return err
+		},
+	}
+	cmd.Flags().BoolVar(&keepConfig, "keep-config", false, "Keep the config file and local notes")
+	cmd.Flags().BoolVarP(&yes, "yes", "y", false, "Do not ask for confirmation")
+	cmd.Flags().BoolVar(&dryRun, "dry-run", false, "Only show what would be removed")
+	return cmd
+}

cmd/netssh/uninstall_test.go

@@ -0,0 +1,119 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/hook"
+)
+
+func uninstallFixture(t *testing.T) (home string) {
+	t.Helper()
+	home = t.TempDir()
+	t.Setenv("HOME", home)
+	t.Setenv("ZDOTDIR", home)
+	t.Setenv("XDG_CONFIG_HOME", filepath.Join(home, ".config"))
+	t.Setenv("XDG_CACHE_HOME", filepath.Join(home, ".cache"))
+	t.Setenv("ZSH", "")
+	t.Setenv("ZSH_CACHE_DIR", "")
+	t.Setenv("NETSSH_SHELL_ALIAS", "")
+	t.Setenv("NETSSH_CACHE_PATH", "")
+	t.Setenv("PATH", filepath.Join(home, "nobin"))
+	files := map[string]string{
+		".bashrc":                      "export KEEP=1\n# >>> netssh >>>\nnetssh shell-init\n# <<< netssh <<<\n",
+		".zshrc":                       "plugins=(git)\nnetssh shell-init  # netssh cache auto-refresh\nsource ~/.cache/netssh/aliases.sh 2>/dev/null  # netssh aliases\n",
+		".profile":                     "export UNRELATED=1\n",
+		".config/netssh.yaml":          "netbox:\n  url: \"https://netbox.example.com\"\n  token: \"secret\"\nshell:\n  alias: \"j\"\n",
+		".config/netssh/notes/abc.txt": "note",
+		".cache/netssh/hosts.json":     "{}",
+		".cache/netssh/instances-0011/hosts.json":         "{}",
+		".local/share/bash-completion/completions/netssh": "# bash completion for netssh",
+		".zfunc/_netssh": hook.ZshCompletionScript,
+		".zfunc/_j":      "#compdef j\n# netssh command alias completion — generated automatically\n",
+		".zfunc/_other":  "#compdef other\n",
+	}
+	for name, content := range files {
+		path := filepath.Join(home, name)
+		if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(path, []byte(content), 0o600); err != nil {
+			t.Fatal(err)
+		}
+	}
+	return home
+}
+
+func runUninstall(t *testing.T, args ...string) string {
+	t.Helper()
+	cmd := rootCmd()
+	var out strings.Builder
+	cmd.SetOut(&out)
+	cmd.SetArgs(append([]string{"uninstall"}, args...))
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("uninstall: %v\n%s", err, out.String())
+	}
+	return out.String()
+}
+
+func TestUninstallRemovesEverythingAndBacksUpConfig(t *testing.T) {
+	home := uninstallFixture(t)
+	if out := runUninstall(t, "--dry-run"); !strings.Contains(out, ".zshrc") || strings.Contains(out, ".profile") {
+		t.Fatalf("plan:\n%s", out)
+	}
+	if _, err := os.Stat(filepath.Join(home, ".cache", "netssh")); err != nil {
+		t.Fatal("dry run removed files")
+	}
+	runUninstall(t, "--yes")
+
+	for name, want := range map[string]string{".bashrc": "export KEEP=1\n", ".zshrc": "plugins=(git)\n", ".profile": "export UNRELATED=1\n"} {
+		data, _ := os.ReadFile(filepath.Join(home, name))
+		if string(data) != want {
+			t.Errorf("%s: %q", name, data)
+		}
+	}
+	for _, gone := range []string{".cache/netssh", ".config/netssh.yaml", ".config/netssh", ".zfunc/_netssh", ".zfunc/_j", ".local/share/bash-completion/completions/netssh"} {
+		if _, err := os.Stat(filepath.Join(home, gone)); !os.IsNotExist(err) {
+			t.Errorf("%s not removed: %v", gone, err)
+		}
+	}
+	if _, err := os.Stat(filepath.Join(home, ".zfunc", "_other")); err != nil {
+		t.Error("unrelated completion removed")
+	}
+	backups, _ := filepath.Glob(filepath.Join(home, ".config", "netssh.yaml.backup-*"))
+	if len(backups) != 1 {
+		t.Fatalf("backups: %v", backups)
+	}
+	if info, _ := os.Stat(backups[0]); info.Mode().Perm() != 0o600 {
+		t.Error("backup with token is not private")
+	}
+}
+
+func TestUninstallKeepConfig(t *testing.T) {
+	home := uninstallFixture(t)
+	runUninstall(t, "--yes", "--keep-config")
+	for _, kept := range []string{".config/netssh.yaml", ".config/netssh/notes/abc.txt"} {
+		if _, err := os.Stat(filepath.Join(home, kept)); err != nil {
+			t.Errorf("%s removed", kept)
+		}
+	}
+	if _, err := os.Stat(filepath.Join(home, ".cache", "netssh")); !os.IsNotExist(err) {
+		t.Error("cache kept")
+	}
+}
+
+func TestUninstallAbortsWithoutConfirmation(t *testing.T) {
+	home := uninstallFixture(t)
+	cmd := rootCmd()
+	cmd.SetOut(&strings.Builder{})
+	cmd.SetIn(strings.NewReader("n\n"))
+	cmd.SetArgs([]string{"uninstall"})
+	if err := cmd.Execute(); err == nil {
+		t.Fatal("no confirmation required")
+	}
+	if _, err := os.Stat(filepath.Join(home, ".config", "netssh.yaml")); err != nil {
+		t.Fatal("config removed without confirmation")
+	}
+}

cmd/netssh/version.go

@@ -0,0 +1,33 @@
+package main
+
+import (
+	"fmt"
+	"runtime/debug"
+
+	"github.com/spf13/cobra"
+)
+
+// version is set at build time: -ldflags "-X main.version=v1.2.3".
+var version = ""
+
+// buildVersion falls back to the module version for `go install` builds.
+func buildVersion() string {
+	if version != "" {
+		return version
+	}
+	if info, ok := debug.ReadBuildInfo(); ok && info.Main.Version != "" && info.Main.Version != "(devel)" {
+		return info.Main.Version
+	}
+	return "dev"
+}
+
+func versionCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "version",
+		Short: "Print the netssh version",
+		Args:  cobra.NoArgs,
+		Run: func(cmd *cobra.Command, args []string) {
+			fmt.Fprintf(cmd.OutOrStdout(), "netssh %s\n", buildVersion())
+		},
+	}
+}

go.mod

@@ -1,49 +1,53 @@
 module git.zb-server.de/Sebi/ssh-netbox-wrapper
 
-go 1.26.3
+go 1.27.3
+
+require (
+	charm.land/bubbles/v2 v2.2.1
+	charm.land/bubbletea/v2 v2.1.0
+	charm.land/huh/v2 v2.0.3
+	charm.land/lipgloss/v2 v2.0.6
+	github.com/spf13/cobra v1.10.2
+	github.com/spf13/viper v1.21.0
+	golang.org/x/sys v0.49.0
+)
 
 require (
 	github.com/atotto/clipboard v0.1.4 // indirect
-	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
 	github.com/catppuccin/go v0.3.0 // indirect
-	github.com/charmbracelet/bubbles v1.0.0 // indirect
-	github.com/charmbracelet/bubbletea v1.3.10 // indirect
-	github.com/charmbracelet/colorprofile v0.4.1 // indirect
-	github.com/charmbracelet/huh v1.0.0 // indirect
-	github.com/charmbracelet/lipgloss v1.1.0 // indirect
-	github.com/charmbracelet/x/ansi v0.11.6 // indirect
-	github.com/charmbracelet/x/cellbuf v0.0.15 // indirect
-	github.com/charmbracelet/x/exp/strings v0.0.0-20240722160745-212f7b056ed0 // indirect
+	github.com/charmbracelet/colorprofile v0.4.3 // indirect
+	github.com/charmbracelet/ultraviolet v0.0.0-20261023060817-a45b7c86333f // indirect
+	github.com/charmbracelet/x/ansi v0.11.9 // indirect
+	github.com/charmbracelet/x/exp/golden v0.1.0 // indirect
+	github.com/charmbracelet/x/exp/ordered v0.1.0 // indirect
+	github.com/charmbracelet/x/exp/strings v0.1.0 // indirect
 	github.com/charmbracelet/x/term v0.2.2 // indirect
-	github.com/clipperhouse/displaywidth v0.9.0 // indirect
-	github.com/clipperhouse/stringish v0.1.1 // indirect
-	github.com/clipperhouse/uax29/v2 v2.5.0 // indirect
-	github.com/dustin/go-humanize v1.0.1 // indirect
-	github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
-	github.com/fsnotify/fsnotify v1.9.0 // indirect
-	github.com/go-viper/mapstructure/v2 v2.4.0 // indirect
+	github.com/charmbracelet/x/termios v0.1.1 // indirect
+	github.com/charmbracelet/x/windows v0.2.2 // indirect
+	github.com/charmbracelet/x/xpty v0.1.4 // indirect
+	github.com/clipperhouse/displaywidth v0.11.0 // indirect
+	github.com/clipperhouse/uax29/v2 v2.7.0 // indirect
+	github.com/dustin/go-humanize v1.1.0 // indirect
+	github.com/fsnotify/fsnotify v1.10.1 // indirect
+	github.com/go-viper/mapstructure/v2 v2.5.0 // indirect
+	github.com/google/go-cmp v0.7.0 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
-	github.com/lucasb-eyer/go-colorful v1.3.0 // indirect
-	github.com/mattn/go-isatty v0.0.20 // indirect
-	github.com/mattn/go-localereader v0.0.1 // indirect
-	github.com/mattn/go-runewidth v0.0.19 // indirect
+	github.com/lucasb-eyer/go-colorful v1.4.1 // indirect
+	github.com/mattn/go-runewidth v0.0.31 // indirect
 	github.com/mitchellh/hashstructure/v2 v2.0.2 // indirect
-	github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 // indirect
 	github.com/muesli/cancelreader v0.2.2 // indirect
-	github.com/muesli/termenv v0.16.0 // indirect
-	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
+	github.com/pelletier/go-toml/v2 v2.4.3 // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
-	github.com/sagikazarmark/locafero v0.11.0 // indirect
-	github.com/sahilm/fuzzy v0.1.1 // indirect
-	github.com/sourcegraph/conc v0.3.1-0.20240121214520-5f936abd7ae8 // indirect
+	github.com/rogpeppe/go-internal v1.16.0 // indirect
+	github.com/sagikazarmark/locafero v0.12.0 // indirect
+	github.com/sahilm/fuzzy v0.1.3 // indirect
 	github.com/spf13/afero v1.15.0 // indirect
 	github.com/spf13/cast v1.10.0 // indirect
-	github.com/spf13/cobra v1.10.2 // indirect
 	github.com/spf13/pflag v1.0.10 // indirect
-	github.com/spf13/viper v1.21.0 // indirect
+	github.com/stretchr/testify v1.12.1 // indirect
 	github.com/subosito/gotenv v1.6.0 // indirect
-	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
-	go.yaml.in/yaml/v3 v3.0.4 // indirect
-	golang.org/x/sys v0.38.0 // indirect
-	golang.org/x/text v0.28.0 // indirect
+	github.com/xo/terminfo v1.2.0 // indirect
+	go.yaml.in/yaml/v3 v3.0.5 // indirect
+	golang.org/x/sync v0.24.0 // indirect
+	golang.org/x/text v0.43.0 // indirect
 )

go.sum

@@ -1,71 +1,85 @@
+charm.land/bubbles/v2 v2.2.1 h1:Fq1+qm5hV6GkvzLQDhCBpXXE5tLgvh1PRriCLwSvIQU=
+charm.land/bubbles/v2 v2.2.1/go.mod h1:wdMgn+sje1KNXdwFizIWjbf328fIUBxqEmJ/vYPo8yc=
+charm.land/bubbletea/v2 v2.1.0 h1:A9fj9h5LFrvQhQHFNggp8K8rvY6CUfgn9dMbb6p2HIw=
+charm.land/bubbletea/v2 v2.1.0/go.mod h1:xWHeyxIX9/wiFU2kgPW04ojOZyTzrWf+8lGjUCaftiU=
+charm.land/huh/v2 v2.0.3 h1:2cJsMqEPwSywGHvdlKsJyQKPtSJLVnFKyFbsYZTlLkU=
+charm.land/huh/v2 v2.0.3/go.mod h1:93eEveeeqn47MwiC3tf+2atZ2l7Is88rAtmZNZ8x9Wc=
+charm.land/lipgloss/v2 v2.0.6 h1:EaGKeuA8FvF+v2BT5VmZd2LoYLaMZJXA5n34th8nCIQ=
+charm.land/lipgloss/v2 v2.0.6/go.mod h1:ipDDJNSGa1hlwDtSfW1s2/xR8Vdhbut4PXh2zEKZd0Q=
+github.com/MakeNowJust/heredoc v1.0.0 h1:cXCdzVdstXyiTqTvfqk9SDHpKNjxuom+DOlyEeQ4pzQ=
+github.com/MakeNowJust/heredoc v1.0.0/go.mod h1:mG5amYoWBHf8vpLOuehzbGGw0EHxpZZ6lCpQ4fNJ8LE=
 github.com/atotto/clipboard v0.1.4 h1:EH0zSVneZPSuFR11BlR9YppQTVDbh5+16AmcJi4g1z4=
 github.com/atotto/clipboard v0.1.4/go.mod h1:ZY9tmq7sm5xIbd9bOK4onWV4S6X0u6GY7Vn0Yu86PYI=
-github.com/aymanbagabas/go-osc52/v2 v2.0.1 h1:HwpRHbFMcZLEVr42D4p7XBqjyuxQH5SMiErDT4WkJ2k=
-github.com/aymanbagabas/go-osc52/v2 v2.0.1/go.mod h1:uYgXzlJ7ZpABp8OJ+exZzJJhRNQ2ASbcXHWsFqH8hp8=
+github.com/aymanbagabas/go-udiff v0.4.1 h1:OEIrQ8maEeDBXQDoGCbbTTXYJMYRCRO1fnodZ12Gv5o=
+github.com/aymanbagabas/go-udiff v0.4.1/go.mod h1:0L9PGwj20lrtmEMeyw4WKJ/TMyDtvAoK9bf2u/mNo3w=
 github.com/catppuccin/go v0.3.0 h1:d+0/YicIq+hSTo5oPuRi5kOpqkVA5tAsU6dNhvRu+aY=
 github.com/catppuccin/go v0.3.0/go.mod h1:8IHJuMGaUUjQM82qBrGNBv7LFq6JI3NnQCF6MOlZjpc=
-github.com/charmbracelet/bubbles v1.0.0 h1:12J8/ak/uCZEMQ6KU7pcfwceyjLlWsDLAxB5fXonfvc=
-github.com/charmbracelet/bubbles v1.0.0/go.mod h1:9d/Zd5GdnauMI5ivUIVisuEm3ave1XwXtD1ckyV6r3E=
-github.com/charmbracelet/bubbletea v1.3.10 h1:otUDHWMMzQSB0Pkc87rm691KZ3SWa4KUlvF9nRvCICw=
-github.com/charmbracelet/bubbletea v1.3.10/go.mod h1:ORQfo0fk8U+po9VaNvnV95UPWA1BitP1E0N6xJPlHr4=
-github.com/charmbracelet/colorprofile v0.4.1 h1:a1lO03qTrSIRaK8c3JRxJDZOvhvIeSco3ej+ngLk1kk=
-github.com/charmbracelet/colorprofile v0.4.1/go.mod h1:U1d9Dljmdf9DLegaJ0nGZNJvoXAhayhmidOdcBwAvKk=
-github.com/charmbracelet/huh v1.0.0 h1:wOnedH8G4qzJbmhftTqrpppyqHakl/zbbNdXIWJyIxw=
-github.com/charmbracelet/huh v1.0.0/go.mod h1:5YVc+SlZ1IhQALxRPpkGwwEKftN/+OlJlnJYlDRFqN4=
-github.com/charmbracelet/lipgloss v1.1.0 h1:vYXsiLHVkK7fp74RkV7b2kq9+zDLoEU4MZoFqR/noCY=
-github.com/charmbracelet/lipgloss v1.1.0/go.mod h1:/6Q8FR2o+kj8rz4Dq0zQc3vYf7X+B0binUUBwA0aL30=
-github.com/charmbracelet/x/ansi v0.11.6 h1:GhV21SiDz/45W9AnV2R61xZMRri5NlLnl6CVF7ihZW8=
-github.com/charmbracelet/x/ansi v0.11.6/go.mod h1:2JNYLgQUsyqaiLovhU2Rv/pb8r6ydXKS3NIttu3VGZQ=
-github.com/charmbracelet/x/cellbuf v0.0.15 h1:ur3pZy0o6z/R7EylET877CBxaiE1Sp1GMxoFPAIztPI=
-github.com/charmbracelet/x/cellbuf v0.0.15/go.mod h1:J1YVbR7MUuEGIFPCaaZ96KDl5NoS0DAWkskup+mOY+Q=
-github.com/charmbracelet/x/exp/strings v0.0.0-20240722160745-212f7b056ed0 h1:qko3AQ4gK1MTS/de7F5hPGx6/k1u0w4TeYmBFwzYVP4=
-github.com/charmbracelet/x/exp/strings v0.0.0-20240722160745-212f7b056ed0/go.mod h1:pBhA0ybfXv6hDjQUZ7hk1lVxBiUbupdw5R31yPUViVQ=
+github.com/charmbracelet/colorprofile v0.4.3 h1:QPa1IWkYI+AOB+fE+mg/5/4HRMZcaXex9t5KX76i20Q=
+github.com/charmbracelet/colorprofile v0.4.3/go.mod h1:/zT4BhpD5aGFpqQQqw7a+VtHCzu+zrQtt1zhMt9mR4Q=
+github.com/charmbracelet/ultraviolet v0.0.0-20261023060817-a45b7c86333f h1:D2JpB65eehsnkEwEG401dMBSNYtTDgvKXZZSl7ZCxWI=
+github.com/charmbracelet/ultraviolet v0.0.0-20261023060817-a45b7c86333f/go.mod h1:aJDVk+WOVM1K04rdc/71PMPoUGfjxjhvXfP3Pjz1Zio=
+github.com/charmbracelet/x/ansi v0.11.9 h1:kIrqLBxtTVbLyyHO2Evoi93EjQo1mylWmpNEsfPxXAM=
+github.com/charmbracelet/x/ansi v0.11.9/go.mod h1:DG/hpOnaI2QJ/KMMqLL2h0KVhluuJLazf8973P+Vy5w=
+github.com/charmbracelet/x/conpty v0.2.0 h1:eKtA2hm34qNfgJCDp/M6Dc0gLy7e07YEK4qAdNGOvVY=
+github.com/charmbracelet/x/conpty v0.2.0/go.mod h1:fexgUnVrZgw8scD49f6VSi0Ggj9GWYIrpedRthAwW/8=
+github.com/charmbracelet/x/exp/golden v0.1.0 h1:qgUxGaHX4I8Fg077vD+54+qFmDWrgO19lTCQLblHWko=
+github.com/charmbracelet/x/exp/golden v0.1.0/go.mod h1:6fMpcW6iwN/kX+xJ52eqVWsDiBTe0UJD24JLoHFe+P0=
+github.com/charmbracelet/x/exp/ordered v0.1.0 h1:55/qLwjIh0gL0Vni+QAWk7T/qRVP6sBf+2agPBgnOFE=
+github.com/charmbracelet/x/exp/ordered v0.1.0/go.mod h1:5UHwmG+is5THxMyCJHNPCn2/ecI07aKNrW+LcResjJ8=
+github.com/charmbracelet/x/exp/strings v0.1.0 h1:i69S2XI7uG1u4NLGeJPSYU++Nmjvpo9nwd6aoEm7gkA=
+github.com/charmbracelet/x/exp/strings v0.1.0/go.mod h1:/ehtMPNh9K4odGFkqYJKpIYyePhdp1hLBRvyY4bWkH8=
 github.com/charmbracelet/x/term v0.2.2 h1:xVRT/S2ZcKdhhOuSP4t5cLi5o+JxklsoEObBSgfgZRk=
 github.com/charmbracelet/x/term v0.2.2/go.mod h1:kF8CY5RddLWrsgVwpw4kAa6TESp6EB5y3uxGLeCqzAI=
-github.com/clipperhouse/displaywidth v0.9.0 h1:Qb4KOhYwRiN3viMv1v/3cTBlz3AcAZX3+y9OLhMtAtA=
-github.com/clipperhouse/displaywidth v0.9.0/go.mod h1:aCAAqTlh4GIVkhQnJpbL0T/WfcrJXHcj8C0yjYcjOZA=
-github.com/clipperhouse/stringish v0.1.1 h1:+NSqMOr3GR6k1FdRhhnXrLfztGzuG+VuFDfatpWHKCs=
-github.com/clipperhouse/stringish v0.1.1/go.mod h1:v/WhFtE1q0ovMta2+m+UbpZ+2/HEXNWYXQgCt4hdOzA=
-github.com/clipperhouse/uax29/v2 v2.5.0 h1:x7T0T4eTHDONxFJsL94uKNKPHrclyFI0lm7+w94cO8U=
-github.com/clipperhouse/uax29/v2 v2.5.0/go.mod h1:Wn1g7MK6OoeDT0vL+Q0SQLDz/KpfsVRgg6W7ihQeh4g=
+github.com/charmbracelet/x/termios v0.1.1 h1:o3Q2bT8eqzGnGPOYheoYS8eEleT5ZVNYNy8JawjaNZY=
+github.com/charmbracelet/x/termios v0.1.1/go.mod h1:rB7fnv1TgOPOyyKRJ9o+AsTU/vK5WHJ2ivHeut/Pcwo=
+github.com/charmbracelet/x/windows v0.2.2 h1:IofanmuvaxnKHuV04sC0eBy/smG6kIKrWG2/jYn2GuM=
+github.com/charmbracelet/x/windows v0.2.2/go.mod h1:/8XtdKZzedat74NQFn0NGlGL4soHB0YQZrETF96h75k=
+github.com/charmbracelet/x/xpty v0.1.4 h1:4jaW7u+8AHQMxesiVc+zUMsspu7GyDwtJO+gy/tFtW4=
+github.com/charmbracelet/x/xpty v0.1.4/go.mod h1:7t8P7BpPiolHJ1pLzz7/4ujDbD+sUxI9yA3CBOLOIcU=
+github.com/clipperhouse/displaywidth v0.11.0 h1:lBc6kY44VFw+TDx4I8opi/EtL9m20WSEFgwIwO+UVM8=
+github.com/clipperhouse/displaywidth v0.11.0/go.mod h1:bkrFNkf81G8HyVqmKGxsPufD3JhNl3dSqnGhOoSD/o0=
+github.com/clipperhouse/uax29/v2 v2.7.0 h1:+gs4oBZ2gPfVrKPthwbMzWZDaAFPGYK72F0NJv2v7Vk=
+github.com/clipperhouse/uax29/v2 v2.7.0/go.mod h1:EFJ2TJMRUaplDxHKj1qAEhCtQPW2tJSwu5BF98AuoVM=
 github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
-github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
-github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
-github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f h1:Y/CXytFA4m6baUTXGLOoWe4PQhGxaX0KpnayAqC48p4=
-github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f/go.mod h1:vw97MGsxSvLiUE2X8qFplwetxpGLQrlU1Q9AUEIzCaM=
-github.com/fsnotify/fsnotify v1.9.0 h1:2Ml+OJNzbYCTzsxtv8vKSFD9PbJjmhYF14k/jKC7S9k=
-github.com/fsnotify/fsnotify v1.9.0/go.mod h1:8jBTzvmWwFyi3Pb8djgCCO5IBqzKJ/Jwo8TRcHyHii0=
-github.com/go-viper/mapstructure/v2 v2.4.0 h1:EBsztssimR/CONLSZZ04E8qAkxNYq4Qp9LvH92wZUgs=
-github.com/go-viper/mapstructure/v2 v2.4.0/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM=
+github.com/creack/pty v1.1.24 h1:bJrF4RRfyJnbTJqzRLHzcGaZK1NeM5kTC9jGgovnR1s=
+github.com/creack/pty v1.1.24/go.mod h1:08sCNb52WyoAwi2QDyzUCTgcvVFhUzewun7wtTfvcwE=
+github.com/dustin/go-humanize v1.1.0 h1:dbKTrvD0klcbBV/h4AWJdMuZogJACoMlvWIWZ5b2xWg=
+github.com/dustin/go-humanize v1.1.0/go.mod h1:hc1CvRkJMsgxqjmjMQF3QNRAZBwY8AXBAzKYoSX9sFI=
+github.com/frankban/quicktest v1.14.6 h1:7Xjx+VpznH+oBnejlPUj8oUpdxnVs4f8XU8WnHkI4W8=
+github.com/frankban/quicktest v1.14.6/go.mod h1:4ptaffx2x8+WTWXmUCuVU6aPUX1/Mz7zb5vbUoiM6w0=
+github.com/fsnotify/fsnotify v1.10.1 h1:b0/UzAf9yR5rhf3RPm9gf3ehBPpf0oZKIjtpKrx59Ho=
+github.com/fsnotify/fsnotify v1.10.1/go.mod h1:TLheqan6HD6GBK6PrDWyDPBaEV8LspOxvPSjC+bVfgo=
+github.com/go-viper/mapstructure/v2 v2.5.0 h1:vM5IJoUAy3d7zRSVtIwQgBj7BiWtMPfmPEgAXnvj1Ro=
+github.com/go-viper/mapstructure/v2 v2.5.0/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
-github.com/lucasb-eyer/go-colorful v1.3.0 h1:2/yBRLdWBZKrf7gB40FoiKfAWYQ0lqNcbuQwVHXptag=
-github.com/lucasb-eyer/go-colorful v1.3.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
-github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
-github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
-github.com/mattn/go-localereader v0.0.1 h1:ygSAOl7ZXTx4RdPYinUpg6W99U8jWvWi9Ye2JC/oIi4=
-github.com/mattn/go-localereader v0.0.1/go.mod h1:8fBrzywKY7BI3czFoHkuzRoWE9C+EiG4R1k4Cjx5p88=
-github.com/mattn/go-runewidth v0.0.19 h1:v++JhqYnZuu5jSKrk9RbgF5v4CGUjqRfBm05byFGLdw=
-github.com/mattn/go-runewidth v0.0.19/go.mod h1:XBkDxAl56ILZc9knddidhrOlY5R/pDhgLpndooCuJAs=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0SNc=
+github.com/kylelemons/godebug v1.1.0/go.mod h1:9/0rRGxNHcop5bhtWyNeEfOS8JIWk580+fNqagV/RAw=
+github.com/lucasb-eyer/go-colorful v1.4.1 h1:1EO+WB73+EH8EVbzlrG3KLAfEypQWVHIBqlTf+2hNss=
+github.com/lucasb-eyer/go-colorful v1.4.1/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
+github.com/mattn/go-runewidth v0.0.31 h1:1oCV4ReTlosDBc6rYRw5cL8S/4y8iv5oRl4SJ5IBgwo=
+github.com/mattn/go-runewidth v0.0.31/go.mod h1:3qAiGCV4Koz/yuveO58qUefmUTRm8r0IGEXZ9jeHp/8=
 github.com/mitchellh/hashstructure/v2 v2.0.2 h1:vGKWl0YJqUNxE8d+h8f6NJLcCJrgbhC4NcD46KavDd4=
 github.com/mitchellh/hashstructure/v2 v2.0.2/go.mod h1:MG3aRVU/N29oo/V/IhBX8GR/zz4kQkprJgF2EVszyDE=
-github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 h1:ZK8zHtRHOkbHy6Mmr5D264iyp3TiX5OmNcI5cIARiQI=
-github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6/go.mod h1:CJlz5H+gyd6CUWT45Oy4q24RdLyn7Md9Vj2/ldJBSIo=
 github.com/muesli/cancelreader v0.2.2 h1:3I4Kt4BQjOR54NavqnDogx/MIoWBFa0StPA8ELUXHmA=
 github.com/muesli/cancelreader v0.2.2/go.mod h1:3XuTXfFS2VjM+HTLZY9Ak0l6eUKfijIfMUZ4EgX0QYo=
-github.com/muesli/termenv v0.16.0 h1:S5AlUN9dENB57rsbnkPyfdGuWIlkmzJjbFf0Tf5FWUc=
-github.com/muesli/termenv v0.16.0/go.mod h1:ZRfOIKPFDYQoDFF4Olj7/QJbW60Ol/kL1pU3VfY/Cnk=
-github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0t5Ec4=
-github.com/pelletier/go-toml/v2 v2.2.4/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
+github.com/pelletier/go-toml/v2 v2.4.3 h1:GTRvJQutkOSftxIFD5xw9aepkYNuPWmVJpffdDPYVpY=
+github.com/pelletier/go-toml/v2 v2.4.3/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
 github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
 github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
+github.com/rogpeppe/go-internal v1.16.0 h1:O9DK+vNMDVGLr2BeZqmpLeMjiMNkuXfcqntWbZV6S5g=
+github.com/rogpeppe/go-internal v1.16.0/go.mod h1:DrUVZyrJU+txYW5/1kwtXQSMFio52ZOxX7yM1VHvnxs=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
-github.com/sagikazarmark/locafero v0.11.0 h1:1iurJgmM9G3PA/I+wWYIOw/5SyBtxapeHDcg+AAIFXc=
-github.com/sagikazarmark/locafero v0.11.0/go.mod h1:nVIGvgyzw595SUSUE6tvCp3YYTeHs15MvlmU87WwIik=
-github.com/sahilm/fuzzy v0.1.1 h1:ceu5RHF8DGgoi+/dR5PsECjCDH1BE3Fnmpo7aVXOdRA=
-github.com/sahilm/fuzzy v0.1.1/go.mod h1:VFvziUEIMCrT6A6tw2RFIXPXXmzXbOsSHF0DOI8ZK9Y=
-github.com/sourcegraph/conc v0.3.1-0.20240121214520-5f936abd7ae8 h1:+jumHNA0Wrelhe64i8F6HNlS8pkoyMv5sreGx2Ry5Rw=
-github.com/sourcegraph/conc v0.3.1-0.20240121214520-5f936abd7ae8/go.mod h1:3n1Cwaq1E1/1lhQhtRK2ts/ZwZEhjcQeJQ1RuC6Q/8U=
+github.com/sagikazarmark/locafero v0.12.0 h1:/NQhBAkUb4+fH1jivKHWusDYFjMOOKU88eegjfxfHb4=
+github.com/sagikazarmark/locafero v0.12.0/go.mod h1:sZh36u/YSZ918v0Io+U9ogLYQJ9tLLBmM4eneO6WwsI=
+github.com/sahilm/fuzzy v0.1.3 h1:juByESSS32nVD81vr6tHmKmA/8zde7gE+x5CLxrzXPU=
+github.com/sahilm/fuzzy v0.1.3/go.mod h1:au6//VbVSqu6DFrkL2CfjlJ5iURpNCPeE+1GwY3XsT8=
 github.com/spf13/afero v1.15.0 h1:b/YBCLWAJdFWJTN9cLhiXXcD7mzKn9Dm86dNnfyQw1I=
 github.com/spf13/afero v1.15.0/go.mod h1:NC2ByUVxtQs4b3sIUphxK0NioZnmxgyCrfzeuq8lxMg=
 github.com/spf13/cast v1.10.0 h1:h2x0u2shc1QuLHfxi+cTJvs30+ZAHOGRic8uyGTDWxY=
@@ -77,16 +91,19 @@ github.com/spf13/pflag v1.0.10 h1:4EBh2KAYBwaONj6b2Ye1GiHfwjqyROoF4RwYO+vPwFk=
 github.com/spf13/pflag v1.0.10/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
 github.com/spf13/viper v1.21.0 h1:x5S+0EU27Lbphp4UKm1C+1oQO+rKx36vfCoaVebLFSU=
 github.com/spf13/viper v1.21.0/go.mod h1:P0lhsswPGWD/1lZJ9ny3fYnVqxiegrlNrEmgLjbTCAY=
+github.com/stretchr/testify v1.12.1 h1:EuwCh5fleGS7H32xRwO3wRGT7DxrDhLAT6FF8MpWDWE=
+github.com/stretchr/testify v1.12.1/go.mod h1:MDEgiDPPsNp5cuIrHPPCyornHKgEVbtFUmoNlxoYthg=
 github.com/subosito/gotenv v1.6.0 h1:9NlTDc1FTs4qu0DDq7AEtTPNw6SVm7uBMsUCUjABIf8=
 github.com/subosito/gotenv v1.6.0/go.mod h1:Dk4QP5c2W3ibzajGcXpNraDfq2IrhjMIvMSWPKKo0FU=
-github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e h1:JVG44RsyaB9T2KIHavMF/ppJZNG9ZpyihvCd0w101no=
-github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e/go.mod h1:RbqR21r5mrJuqunuUZ/Dhy/avygyECGrLceyNeo4LiM=
-go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc=
+github.com/xo/terminfo v1.2.0 h1:d0ZTOCpuGE0lwSAOs0zcJjwz3jWQyqcRt9XbGJpCOl4=
+github.com/xo/terminfo v1.2.0/go.mod h1:lGzkSo8Fe7IRh/w+Gqz7n5mDog4FVXCj3gy/DYTBqio=
 go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
-golang.org/x/sys v0.0.0-20210809222454-d867a43fc93e/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.38.0 h1:3yZWxaJjBmCWXqhN1qh02AkOnCQ1poK6oF+a7xWL6Gc=
-golang.org/x/sys v0.38.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
-golang.org/x/text v0.28.0 h1:rhazDwis8INMIwQ4tpjLDzUhx6RlXqZNPEM0huQojng=
-golang.org/x/text v0.28.0/go.mod h1:U8nCwOR8jO/marOQ0QbDiOngZVEBB7MAiitBuMjXiNU=
+go.yaml.in/yaml/v3 v3.0.5 h1:N6y/pJk8buWs9NY5ERU2HSMfm+IuD/OtfdAnq6kESPw=
+go.yaml.in/yaml/v3 v3.0.5/go.mod h1:HVTZu1O7/Vkt2N+BFy8Zza+lnLsABggaTM2ZpNIGuKg=
+golang.org/x/sync v0.24.0 h1:iqiDrGoDgyuvAKrhLQthUEzU/R378N78gXbBjxed7oA=
+golang.org/x/sync v0.24.0/go.mod h1:sUUOizhqBxiL6pEWpqNLUiaJn1ShEbZ6BBqskPbjZm0=
+golang.org/x/sys v0.49.0 h1:XbzkgYJHdqh/8m2Uu0W/dQv8nktxx4BFHp1M0gROTXA=
+golang.org/x/sys v0.49.0/go.mod h1:hNLxWAXmnKAxqDtdwIYC4bM9oQPEecfsnNMuSxOs3og=
+golang.org/x/text v0.43.0 h1:1QivrlhwAsnMOcqgOdl9my7s9OyZl8O5/UGUTJVXoWc=
+golang.org/x/text v0.43.0/go.mod h1:hbSIYA/amXcRXTFSZqh8tWHEoqRvvbKPJ2uz/KU+a+s=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=

install.sh

@@ -1,94 +1,261 @@
 #!/usr/bin/env bash
-set -euo pipefail
+set -eo pipefail
+# Bash 3 (macOS) treats empty arrays as unset under nounset.
+: "${HOME:?HOME must be set}"
 
 REPO="Sebi/ssh-netbox-wrapper"
 BASE_URL="https://git.zb-server.de"
 BINARY="netssh"
-INSTALL_DIR="${INSTALL_DIR:-/usr/local/bin}"
+info() { printf '  %s\n' "$*"; }
+die() { printf 'error: %s\n' "$*" >&2; exit 1; }
+need() { command -v "$1" >/dev/null 2>&1 || die "'$1' is required but not installed"; }
+# Check the complete toolchain before any network request or filesystem change.
+MISSING=()
+for program in curl uname sed awk mktemp rm dirname readlink mkdir cat install mv cp chmod cmp; do
+  if ! command -v "$program" >/dev/null 2>&1; then MISSING+=("$program"); fi
+done
+if command -v sha256sum >/dev/null 2>&1; then
+  SHA256=(sha256sum)
+elif command -v shasum >/dev/null 2>&1; then
+  SHA256=(shasum -a 256)
+else
+  MISSING+=("sha256sum or shasum (SHA-256 verification)")
+fi
+if [[ ${#MISSING[@]} -gt 0 ]]; then
+  printf 'error: required programs are missing:\n' >&2
+  printf '  - %s\n' "${MISSING[@]}" >&2
+  die "install these dependencies using your package manager, then run the installer again"
+fi
 
-# --- helpers -----------------------------------------------------------------
-
-red()   { printf '\033[31m%s\033[0m\n' "$*"; }
-green() { printf '\033[32m%s\033[0m\n' "$*"; }
-bold()  { printf '\033[1m%s\033[0m\n' "$*"; }
-info()  { printf '  %s\n' "$*"; }
-
-die() { red "error: $*" >&2; exit 1; }
-
-need() {
-  command -v "$1" &>/dev/null || die "'$1' is required but not installed"
-}
-
-# --- detect OS / arch --------------------------------------------------------
-
-detect_os() {
-  case "$(uname -s)" in
-    Linux)  echo linux ;;
-    Darwin) echo darwin ;;
-    *)      die "unsupported OS: $(uname -s)" ;;
-  esac
-}
-
-detect_arch() {
-  case "$(uname -m)" in
-    x86_64|amd64)   echo amd64 ;;
-    aarch64|arm64)  echo arm64 ;;
-    *)              die "unsupported architecture: $(uname -m)" ;;
-  esac
-}
-
-# --- main --------------------------------------------------------------------
-
-need curl
-
-OS=$(detect_os)
-ARCH=$(detect_arch)
-
-bold "netssh installer"
-info "platform : $OS/$ARCH"
+# Re-running the one-liner updates the existing installation in its current path.
+if [[ -z "${INSTALL_DIR:-}" ]]; then
+  EXISTING=$(command -v "$BINARY" || true)
+  if [[ "$EXISTING" == /* && -f "$EXISTING" ]]; then
+    INSTALL_DIR=$(dirname "$EXISTING")
+  else
+    INSTALL_DIR=/usr/local/bin
+  fi
+fi
+[[ "$INSTALL_DIR" == /* ]] || INSTALL_DIR="$PWD/$INSTALL_DIR"
+# Check sudo only when the destination needs elevated permissions, also before
+# downloading. For a new directory, inspect its nearest existing parent.
+PRIVILEGE=()
+INSTALL_PARENT=$INSTALL_DIR
+while [[ ! -e "$INSTALL_PARENT" ]]; do INSTALL_PARENT=$(dirname "$INSTALL_PARENT"); done
+[[ -d "$INSTALL_PARENT" ]] || die "installation path is not a directory: $INSTALL_PARENT"
+if [[ ! -w "$INSTALL_PARENT" || ! -x "$INSTALL_PARENT" ]]; then
+  need sudo
+  PRIVILEGE=(sudo)
+fi
+case "$(uname -s)" in
+  Linux) PLATFORM_OS=linux ;;
+  Darwin) PLATFORM_OS=darwin ;;
+  *) die "unsupported OS: $(uname -s)" ;;
+esac
+case "$(uname -m)" in
+  x86_64|amd64) PLATFORM_ARCH=amd64 ;;
+  aarch64|arm64) PLATFORM_ARCH=arm64 ;;
+  *) die "unsupported architecture: $(uname -m)" ;;
+esac
+printf 'netssh install / update\n'
+info "platform : $PLATFORM_OS/$PLATFORM_ARCH"
 info "target   : $INSTALL_DIR/$BINARY"
 
-# Fetch the latest release tag from the Gitea API.
 API_URL="$BASE_URL/api/v1/repos/$REPO/releases/latest"
-TAG=$(curl -sf "$API_URL" | python3 -c "import sys,json; print(json.load(sys.stdin)['tag_name'])") \
-  || die "could not fetch latest release from $API_URL"
-
-ASSET="${BINARY}_${OS}_${ARCH}"
-DOWNLOAD_URL="$BASE_URL/$REPO/releases/download/$TAG/$ASSET"
-CHECKSUM_URL="$BASE_URL/$REPO/releases/download/$TAG/checksums.txt"
-
+RELEASE=$(curl -fsSL "$API_URL") || die "could not fetch latest release from $API_URL"
+TAG=$(printf '%s\n' "$RELEASE" | sed -n 's/.*"tag_name"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p')
+[[ "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+([.+-][a-zA-Z0-9.+-]+)?$ ]] || die "invalid or missing release tag"
+ASSET="${BINARY}_${PLATFORM_OS}_${PLATFORM_ARCH}"
+DOWNLOAD_URL="$BASE_URL/$REPO/releases/download/$TAG"
 info "version  : $TAG"
-echo
 
-# Download binary and checksums into a temp directory.
 TMP=$(mktemp -d)
-trap 'rm -rf "$TMP"' EXIT
-
+STAGED=""
+cleanup() {
+  rm -rf "$TMP"
+  if [[ -n "$STAGED" ]]; then "${PRIVILEGE[@]}" rm -f "$STAGED"; fi
+}
+trap cleanup EXIT
 info "downloading $ASSET..."
-curl -fL --progress-bar -o "$TMP/$ASSET" "$DOWNLOAD_URL"
+curl -fL --progress-bar -o "$TMP/$ASSET" "$DOWNLOAD_URL/$ASSET"
+curl -fsSL -o "$TMP/checksums.txt" "$DOWNLOAD_URL/checksums.txt" \
+  || die "could not fetch checksums; installation aborted"
+EXPECTED=$(awk -v asset="$ASSET" '$2 == asset || $2 == "*" asset {print tolower($1)}' "$TMP/checksums.txt")
+[[ "$EXPECTED" =~ ^[a-f0-9]{64}$ ]] || die "missing, duplicate, or invalid checksum; installation aborted"
+ACTUAL=$("${SHA256[@]}" "$TMP/$ASSET")
+ACTUAL=${ACTUAL%% *}
+[[ "$ACTUAL" == "$EXPECTED" ]] || die "checksum mismatch; installation aborted"
+info "checksum OK"
 
-info "verifying checksum..."
-curl -sf -o "$TMP/checksums.txt" "$CHECKSUM_URL" \
-  || { info "warning: could not fetch checksums, skipping verification"; }
+# Only standalone commands and our managed blocks are removed. Unrelated content
+# and commands which merely mention netssh are retained.
+cat > "$TMP/clean-profile.awk" <<'AWK'
+function legacy(s) {
+  if (s ~ /^([^ \t]*\/)?netssh[ \t]+shell-init[ \t]*(#.*)?$/) return 1
+  if (s ~ /^(source|\.)[ \t]+["']?[^;|&]*netssh\/aliases\.sh["']?([ \t]+2>\/dev\/null)?[ \t]*(#.*)?$/) return 1
+  if (s ~ /^eval[ \t]+["']?\$\(([^ \t]*\/)?netssh[ \t]+alias([ \t]+--shell[ \t]+(bash|zsh))?\)["']?[ \t]*(#.*)?$/) return 1
+  if (s ~ /^([^ \t]*\/)?netssh[ \t]+alias([ \t]+--shell[ \t]+fish)?[ \t]*\|[ \t]*source[ \t]*(#.*)?$/) return 1
+  if (s ~ /^source[ \t]+<\(([^ \t]*\/)?netssh[ \t]+alias\)[ \t]*(#.*)?$/) return 1
+  if (s ~ /^alias[ \t]+[A-Za-z0-9_.-]+(=|[ \t]+)["']netssh([ \t]+[^"']+)?["'][ \t]*(#.*)?$/) return 1
+  return 0
+}
+{
+  s = $0
+  sub(/^[ \t]+/, "", s); sub(/[ \t\r]+$/, "", s)
+  if (s == "# >>> netssh >>>") { if (inside) bad = 1; inside = 1; next }
+  if (s == "# <<< netssh <<<") { if (!inside) bad = 1; inside = 0; next }
+  if (!inside && !legacy(s)) print $0
+}
+END { if (inside || bad) exit 1 }
+AWK
 
-if [[ -f "$TMP/checksums.txt" ]]; then
-  # checksums.txt was built with `sha256sum` in the dist/ dir, so entries look
-  # like "abc123  netssh_linux_amd64". We need to cd into the temp dir first.
-  (cd "$TMP" && grep "$ASSET" checksums.txt | sha256sum --check --status) \
-    || die "checksum mismatch — aborting installation"
-  info "checksum OK"
-fi
+# POSIX-style single quoting also works for these paths in fish, except embedded
+# quotes, which fish escapes with a backslash instead of concatenated quotes.
+quote_sh() { printf "'%s'" "${1//\'/\'\\\'\'}"; }
+quote_fish() {
+  local value=${1//\\/\\\\}
+  value=${value//\'/\\\'}
+  printf "'%s'" "$value"
+}
+resolve_profile() {
+  local path=$1 target steps=0
+  while [[ -L "$path" ]]; do
+    steps=$((steps + 1))
+    [[ "$steps" -le 40 ]] || die "symlink loop in $1"
+    target=$(readlink "$path")
+    if [[ "$target" == /* ]]; then path=$target; else path="$(dirname "$path")/$target"; fi
+  done
+  printf '%s\n' "$path"
+}
 
-chmod +x "$TMP/$ASSET"
-
-# Install — try without sudo first, fall back if needed.
-if [[ -w "$INSTALL_DIR" ]]; then
-  mv "$TMP/$ASSET" "$INSTALL_DIR/$BINARY"
+PROFILE_PATHS=()
+PROFILE_TARGETS=()
+PROFILE_DATA=()
+SHELLS=()
+CURRENT_SHELL=${SHELL:-}
+CURRENT_SHELL=${CURRENT_SHELL##*/}
+CONFIG_DIR=${XDG_CONFIG_HOME:-$HOME/.config}
+if [[ "$PLATFORM_OS" == darwin ]]; then
+  CACHE_DIR=${XDG_CACHE_HOME:-$HOME/Library/Caches}
 else
-  info "sudo required to write to $INSTALL_DIR"
-  sudo mv "$TMP/$ASSET" "$INSTALL_DIR/$BINARY"
+  CACHE_DIR=${XDG_CACHE_HOME:-$HOME/.cache}
 fi
+ZSH_DIR=${ZDOTDIR:-$HOME}
+plan_profile() {
+  local path=$1 kind=$2 target data previous count
+  if [[ ! -e "$path" && ! -L "$path" ]] && { [[ -z "$kind" ]] || [[ "$kind" != "$CURRENT_SHELL" ]]; }; then return; fi
+  target=$(resolve_profile "$path")
+  # A dotfile manager may point two profile names at the same file.
+  for previous in "${PROFILE_TARGETS[@]}"; do [[ "$previous" != "$target" ]] || return 0; done
+  data="$TMP/profile-${#PROFILE_PATHS[@]}"
+  if [[ -e "$target" ]]; then
+    awk -f "$TMP/clean-profile.awk" "$target" > "$data" \
+      || die "unclosed or nested netssh block in $path; profiles were not changed"
+  else
+    : > "$data"
+  fi
+  if [[ -n "$kind" ]]; then
+    count=0
+    for previous in "${SHELLS[@]}"; do [[ "$previous" != "$kind" ]] || count=1; done
+    if [[ "$count" == 0 ]]; then SHELLS+=("$kind"); fi
+    {
+      printf '# >>> netssh >>>\n'
+      if [[ "$kind" == fish ]]; then
+        printf 'set -gx PATH %s $PATH\n' "$(quote_fish "$INSTALL_DIR")"
+        printf '%s shell-init\n' "$(quote_fish "$INSTALL_DIR/$BINARY")"
+      else
+        printf 'export PATH=%s:"$PATH"\n' "$(quote_sh "$INSTALL_DIR")"
+        printf '%s shell-init\n' "$(quote_sh "$INSTALL_DIR/$BINARY")"
+        printf '[ ! -f %s ] || . %s\n' "$(quote_sh "$CACHE_DIR/netssh/aliases.sh")" "$(quote_sh "$CACHE_DIR/netssh/aliases.sh")"
+      fi
+      if [[ "$kind" == zsh ]]; then
+        # Register completion also when compinit already ran (e.g. oh-my-zsh).
+        printf 'fpath=(%s $fpath)\n' "$(quote_sh "$HOME/.zfunc")"
+        printf 'if (( $+functions[compdef] )); then autoload -Uz _netssh && compdef _netssh netssh; fi\n'
+      fi
+      printf '# <<< netssh <<<\n'
+    } >> "$data"
+  fi
+  PROFILE_PATHS+=("$path"); PROFILE_TARGETS+=("$target"); PROFILE_DATA+=("$data")
+}
+# Preflight every profile before installing the binary or modifying any profile.
+plan_profile "$HOME/.bashrc" bash
+plan_profile "$HOME/.bash_profile" ""
+plan_profile "$HOME/.bash_login" ""
+plan_profile "$HOME/.profile" ""
+plan_profile "$ZSH_DIR/.zshrc" zsh
+plan_profile "$ZSH_DIR/.zprofile" ""
+plan_profile "$ZSH_DIR/.zshenv" ""
+if [[ "$ZSH_DIR" != "$HOME" ]]; then
+  plan_profile "$HOME/.zshrc" ""
+  plan_profile "$HOME/.zprofile" ""
+  plan_profile "$HOME/.zshenv" ""
+fi
+plan_profile "$CONFIG_DIR/fish/config.fish" fish
 
-echo
-green "✓ netssh $TAG installed to $INSTALL_DIR/$BINARY"
-info "run 'netssh --help' to get started"
+if [[ ${#PRIVILEGE[@]} -gt 0 ]]; then
+  info "sudo required to write to $INSTALL_DIR"
+fi
+"${PRIVILEGE[@]}" mkdir -p "$INSTALL_DIR"
+# Stage on the destination filesystem to replace a running binary atomically.
+STAGED=$("${PRIVILEGE[@]}" mktemp "$INSTALL_DIR/.netssh.XXXXXX")
+"${PRIVILEGE[@]}" install -m 755 "$TMP/$ASSET" "$STAGED"
+"${PRIVILEGE[@]}" mv -f "$STAGED" "$INSTALL_DIR/$BINARY"
+STAGED=""
+
+# Regenerate aliases, including the configured command alias, as the calling user.
+# An empty cache clears obsolete generated aliases. Never run the wizard here.
+write_aliases() {
+  local kind=$1 path=$2 staged
+  "$INSTALL_DIR/$BINARY" alias --shell "$kind" > "$TMP/aliases-$kind" \
+    || die "could not regenerate $kind aliases; profiles were not changed"
+  mkdir -p "$(dirname "$path")"
+  staged=$(mktemp "$(dirname "$path")/.netssh.XXXXXX")
+  cat "$TMP/aliases-$kind" > "$staged"
+  chmod 600 "$staged"
+  mv -f "$staged" "$path"
+}
+write_aliases bash "$CACHE_DIR/netssh/aliases.sh"
+for kind in "${SHELLS[@]}"; do
+  if [[ "$kind" == fish ]]; then write_aliases fish "$CONFIG_DIR/fish/conf.d/netssh.fish"; fi
+done
+
+for ((index=0; index<${#PROFILE_PATHS[@]}; index++)); do
+  target=${PROFILE_TARGETS[$index]}
+  data=${PROFILE_DATA[$index]}
+  if [[ -e "$target" ]] && cmp -s "$target" "$data"; then continue; fi
+  mkdir -p "$(dirname "$target")"
+  if [[ -e "$target" ]]; then
+    backup=$(mktemp "$target.netssh-backup.XXXXXX")
+    cp -p "$target" "$backup"
+    info "backup   : $backup"
+  fi
+  staged=$(mktemp "$(dirname "$target")/.netssh.XXXXXX")
+  if [[ -e "$target" ]]; then cp -p "$target" "$staged"; else chmod 644 "$staged"; fi
+  cat "$data" > "$staged"
+  mv -f "$staged" "$target"
+  info "updated  : ${PROFILE_PATHS[$index]}"
+done
+COMPLETIONS=()
+for kind in "${SHELLS[@]}"; do
+  if "$INSTALL_DIR/$BINARY" completion install --shell "$kind" >/dev/null; then
+    COMPLETIONS+=("$kind")
+  else
+    info "warning: could not update $kind completion"
+  fi
+done
+printf '\nnetssh %s installed / updated at %s/%s\n' "$TAG" "$INSTALL_DIR" "$BINARY"
+for kind in "${COMPLETIONS[@]}"; do
+  case "$kind" in
+    bash) info "completion: bash -> $HOME/.local/share/bash-completion/completions/netssh" ;;
+    zsh) info "completion: zsh  -> $HOME/.zfunc/_netssh (registered in ${ZSH_DIR}/.zshrc)" ;;
+    fish) info "completion: fish -> $CONFIG_DIR/fish/completions/netssh.fish" ;;
+  esac
+done
+info "Open a new terminal to load the current hooks and aliases."
+for kind in "${COMPLETIONS[@]}"; do
+  if [[ "$kind" == zsh ]]; then
+    info "zsh: if <Tab> still shows files, run: rm -f $(quote_sh "$ZSH_DIR")/.zcompdump* && exec zsh"
+  fi
+done
+info "Remove netssh again with: netssh uninstall"

installer_test.go

@@ -0,0 +1,358 @@
+package netssh_test
+
+import (
+	"crypto/sha256"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+type installerFixture struct {
+	home, bin, assets string
+	env               []string
+}
+
+func newInstallerFixture(t *testing.T) installerFixture {
+	t.Helper()
+	root := t.TempDir()
+	f := installerFixture{home: filepath.Join(root, "home"), bin: filepath.Join(root, "tools"), assets: filepath.Join(root, "assets")}
+	for _, dir := range []string{f.home, f.bin, f.assets} {
+		if err := os.MkdirAll(dir, 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	writeFixture(t, filepath.Join(f.bin, "curl"), `#!/bin/bash
+set -eu
+out=""
+while [[ $# -gt 0 ]]; do
+ case "$1" in -o) out=$2; shift 2 ;; *) url=$1; shift ;; esac
+done
+case "$url" in
+ */releases/latest) printf '{"tag_name": "v0.0.99"}\n'; exit ;;
+ */checksums.txt) [[ "${CHECKSUM_MODE:-}" != missing ]] || exit 22; file="$FIXTURE_ASSETS/checksums.txt" ;;
+ *) file="$FIXTURE_ASSETS/netssh_linux_amd64" ;;
+esac
+if [[ -n "$out" ]]; then cp "$file" "$out"; else cat "$file"; fi
+`, 0o755)
+	writeFixture(t, filepath.Join(f.bin, "uname"), "#!/bin/sh\ncase \"$1\" in -s) echo Linux;; -m) echo x86_64;; esac\n", 0o755)
+	// Any accidental runtime dependency on Python must fail the installation.
+	writeFixture(t, filepath.Join(f.bin, "python3"), "#!/bin/sh\nexit 99\n", 0o755)
+	binary := `#!/bin/bash
+set -eu
+case "$1" in
+ alias)
+  if [[ "$3" == fish ]]; then printf "alias j 'netssh'\n"; else printf "alias j='netssh'\n"; fi ;;
+ completion) exit 0 ;;
+ shell-init) exit 0 ;;
+ *) exit 1 ;;
+esac
+`
+	writeFixture(t, filepath.Join(f.assets, "netssh_linux_amd64"), binary, 0o755)
+	checksum := fmt.Sprintf("%x  netssh_linux_amd64\n", sha256.Sum256([]byte(binary)))
+	writeFixture(t, filepath.Join(f.assets, "checksums.txt"), checksum, 0o644)
+	f.env = append(os.Environ(), "HOME="+f.home, "XDG_CONFIG_HOME="+filepath.Join(f.home, "config"), "XDG_CACHE_HOME="+filepath.Join(f.home, "cache"), "ZDOTDIR="+f.home, "SHELL=/bin/bash", "PATH="+f.bin+":"+os.Getenv("PATH"), "FIXTURE_ASSETS="+f.assets, "INSTALL_DIR="+filepath.Join(f.home, "local bin's"), "BASH_ENV=", "CHECKSUM_MODE=")
+	return f
+}
+
+func writeFixture(t *testing.T, path, content string, mode os.FileMode) {
+	t.Helper()
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(path, []byte(content), mode); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func (f installerFixture) run(t *testing.T) (string, error) {
+	t.Helper()
+	// Piping stdin mirrors curl | bash, including EOF for any child commands.
+	script, err := os.ReadFile("install.sh")
+	if err != nil {
+		t.Fatal(err)
+	}
+	cmd := exec.Command("bash")
+	cmd.Env = f.env
+	cmd.Stdin = strings.NewReader(string(script))
+	out, err := cmd.CombinedOutput()
+	return string(out), err
+}
+
+func TestInstallerUpdatesAndConsolidatesProfilesWithoutPython(t *testing.T) {
+	f := newInstallerFixture(t)
+	original := "export KEEP=yes\n# netssh shell-init is documented here\necho 'netssh shell-init'\nnetssh shell-init\nnetssh shell-init  # duplicate\nsource ~/.cache/netssh/aliases.sh 2>/dev/null\neval \"$(netssh alias)\"\nalias old='netssh old.example.com'\n"
+	target := filepath.Join(f.home, "dotfiles", "bashrc")
+	writeFixture(t, target, original, 0o600)
+	bashrc := filepath.Join(f.home, ".bashrc")
+	if err := os.Symlink(target, bashrc); err != nil {
+		t.Fatal(err)
+	}
+	writeFixture(t, filepath.Join(f.home, ".zshrc"), "export ZSH_KEEP=yes\nnetssh shell-init\n", 0o644)
+	writeFixture(t, filepath.Join(f.home, ".profile"), "export LOGIN_KEEP=yes\nnetssh shell-init\n", 0o644)
+	fish := filepath.Join(f.home, "config", "fish", "config.fish")
+	writeFixture(t, fish, "set KEEP yes\nnetssh alias --shell fish | source\n", 0o644)
+	installed := filepath.Join(f.home, "local bin's", "netssh")
+	writeFixture(t, installed, "old binary", 0o755)
+	if out, err := f.run(t); err != nil {
+		t.Fatalf("install: %v\n%s", err, out)
+	}
+	for _, path := range []string{bashrc, filepath.Join(f.home, ".zshrc"), fish} {
+		data, err := os.ReadFile(path)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if strings.Count(string(data), "# >>> netssh >>>") != 1 {
+			t.Fatalf("bad managed blocks: %s", data)
+		}
+	}
+	zshrc, _ := os.ReadFile(filepath.Join(f.home, ".zshrc"))
+	if !strings.Contains(string(zshrc), "compdef _netssh netssh") || !strings.Contains(string(zshrc), "/.zfunc' $fpath)") {
+		t.Fatalf("zsh completion not registered: %s", zshrc)
+	}
+	data, _ := os.ReadFile(bashrc)
+	if strings.Contains(string(data), "compdef") {
+		t.Fatalf("zsh code in bash profile: %s", data)
+	}
+	for _, kept := range []string{"export KEEP=yes", "# netssh shell-init is documented here", "echo 'netssh shell-init'"} {
+		if !strings.Contains(string(data), kept) {
+			t.Fatalf("unrelated line lost: %s", kept)
+		}
+	}
+	if strings.Contains(string(data), "alias old=") || strings.Contains(string(data), "eval ") {
+		t.Fatalf("legacy entries remain: %s", data)
+	}
+	if info, err := os.Lstat(bashrc); err != nil || info.Mode()&os.ModeSymlink == 0 {
+		t.Fatalf("symlink lost: %v", err)
+	}
+	if info, _ := os.Stat(target); info.Mode().Perm() != 0o600 {
+		t.Fatal("permissions changed")
+	}
+	backups, _ := filepath.Glob(target + ".netssh-backup.*")
+	if len(backups) != 1 {
+		t.Fatalf("backups: %v", backups)
+	}
+	backup, _ := os.ReadFile(backups[0])
+	if string(backup) != original {
+		t.Fatal("backup lost original content")
+	}
+	before := string(data)
+	if out, err := f.run(t); err != nil {
+		t.Fatalf("second install: %v\n%s", err, out)
+	}
+	data, _ = os.ReadFile(bashrc)
+	if string(data) != before {
+		t.Fatalf("not idempotent:\n%s", data)
+	}
+	backups, _ = filepath.Glob(target + ".netssh-backup.*")
+	if len(backups) != 1 {
+		t.Fatal("unchanged profile backed up again")
+	}
+	// Execute the generated Bash block to verify paths containing quotes and spaces.
+	cmd := exec.Command("bash", "-c", `. "$HOME/.bashrc"; alias j`)
+	cmd.Env = f.env
+	if out, err := cmd.CombinedOutput(); err != nil || !strings.Contains(string(out), "alias j='netssh'") {
+		t.Fatalf("source: %v\n%s", err, out)
+	}
+}
+
+func TestInstallerRejectsUnverifiedDownloads(t *testing.T) {
+	for _, mode := range []string{"missing", "mismatch", "no-entry", "duplicate"} {
+		t.Run(mode, func(t *testing.T) {
+			f := newInstallerFixture(t)
+			f.env = append(f.env, "CHECKSUM_MODE="+mode)
+			sums := filepath.Join(f.assets, "checksums.txt")
+			switch mode {
+			case "mismatch":
+				writeFixture(t, sums, strings.Repeat("0", 64)+"  netssh_linux_amd64\n", 0o644)
+			case "no-entry":
+				writeFixture(t, sums, strings.Repeat("0", 64)+"  other_binary\n", 0o644)
+			case "duplicate":
+				data, _ := os.ReadFile(sums)
+				writeFixture(t, sums, string(data)+string(data), 0o644)
+			}
+			installed := filepath.Join(f.home, "local bin's", "netssh")
+			writeFixture(t, installed, "old binary", 0o755)
+			profile := filepath.Join(f.home, ".bashrc")
+			writeFixture(t, profile, "old profile\n", 0o600)
+			if out, err := f.run(t); err == nil {
+				t.Fatalf("accepted invalid checksum: %s", out)
+			}
+			data, _ := os.ReadFile(installed)
+			if string(data) != "old binary" {
+				t.Fatal("binary changed")
+			}
+			data, _ = os.ReadFile(profile)
+			if string(data) != "old profile\n" {
+				t.Fatal("profile changed")
+			}
+		})
+	}
+}
+
+func TestInstallerRefusesBrokenManagedBlock(t *testing.T) {
+	f := newInstallerFixture(t)
+	profile := filepath.Join(f.home, ".bashrc")
+	original := "export KEEP=yes\n# >>> netssh >>>\nunfinished\n"
+	writeFixture(t, profile, original, 0o644)
+	if out, err := f.run(t); err == nil {
+		t.Fatalf("accepted broken block: %s", out)
+	}
+	data, _ := os.ReadFile(profile)
+	if string(data) != original {
+		t.Fatal("profile changed")
+	}
+}
+
+func TestInstallerUsesShasumAndFindsExistingBinary(t *testing.T) {
+	if _, err := exec.LookPath("shasum"); err != nil {
+		t.Skip("shasum not available")
+	}
+	f := newInstallerFixture(t)
+	// Hide sha256sum (and Python) as on a standard macOS installation.
+	for _, name := range []string{"shasum", "sed", "awk", "mktemp", "rm", "dirname", "readlink", "mkdir", "cat", "install", "mv", "cp", "chmod", "cmp", "perl"} {
+		tool, err := exec.LookPath(name)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if err := os.Symlink(tool, filepath.Join(f.bin, name)); err != nil {
+			t.Fatal(err)
+		}
+	}
+	f.env = append(f.env, "PATH="+f.bin, "INSTALL_DIR=")
+	installed := filepath.Join(f.bin, "netssh")
+	writeFixture(t, installed, "#!/bin/sh\nexit 1\n", 0o755)
+	if out, err := f.run(t); err != nil {
+		t.Fatalf("shasum update: %v\n%s", err, out)
+	}
+	data, _ := os.ReadFile(installed)
+	expected, _ := os.ReadFile(filepath.Join(f.assets, "netssh_linux_amd64"))
+	if string(data) != string(expected) {
+		t.Fatal("existing installation was not replaced")
+	}
+}
+
+func TestInstallerRespectsZdotdir(t *testing.T) {
+	f := newInstallerFixture(t)
+	zshDir := filepath.Join(f.home, "custom-zsh")
+	f.env = append(f.env, "SHELL=/bin/zsh", "ZDOTDIR="+zshDir)
+	old := filepath.Join(f.home, ".zshrc")
+	writeFixture(t, old, "export KEEP=yes\nnetssh shell-init\n", 0o644)
+	if out, err := f.run(t); err != nil {
+		t.Fatalf("zsh setup: %v\n%s", err, out)
+	}
+	data, _ := os.ReadFile(filepath.Join(zshDir, ".zshrc"))
+	if strings.Count(string(data), "# >>> netssh >>>") != 1 {
+		t.Fatalf("missing custom zsh setup: %s", data)
+	}
+	data, _ = os.ReadFile(old)
+	if string(data) != "export KEEP=yes\n" {
+		t.Fatalf("old zsh setup not cleaned: %s", data)
+	}
+}
+
+func TestInstallerUsesMacOSCacheLayout(t *testing.T) {
+	f := newInstallerFixture(t)
+	writeFixture(t, filepath.Join(f.bin, "uname"), "#!/bin/sh\ncase \"$1\" in -s) echo Darwin;; -m) echo x86_64;; esac\n", 0o755)
+	data, _ := os.ReadFile(filepath.Join(f.assets, "netssh_linux_amd64"))
+	writeFixture(t, filepath.Join(f.assets, "checksums.txt"), fmt.Sprintf("%x  netssh_darwin_amd64\n", sha256.Sum256(data)), 0o644)
+	f.env = append(f.env, "XDG_CACHE_HOME=")
+	if out, err := f.run(t); err != nil {
+		t.Fatalf("macOS setup: %v\n%s", err, out)
+	}
+	if _, err := os.Stat(filepath.Join(f.home, "Library", "Caches", "netssh", "aliases.sh")); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestInstallerChecksDependenciesBeforeDownloading(t *testing.T) {
+	for _, missing := range [][]string{{"awk", "cmp"}, {"curl"}, {"sha256sum", "shasum"}} {
+		t.Run(strings.Join(missing, "+"), func(t *testing.T) {
+			f := newInstallerFixture(t)
+			// Build an isolated PATH containing every dependency except the selected tools.
+			for _, name := range []string{"curl", "uname", "sed", "awk", "mktemp", "rm", "dirname", "readlink", "mkdir", "cat", "install", "mv", "cp", "chmod", "cmp", "sha256sum"} {
+				skip := false
+				for _, absent := range missing {
+					if name == absent {
+						skip = true
+					}
+				}
+				if skip {
+					if err := os.Remove(filepath.Join(f.bin, name)); err != nil && !os.IsNotExist(err) {
+						t.Fatal(err)
+					}
+					continue
+				}
+				if _, err := os.Stat(filepath.Join(f.bin, name)); err == nil {
+					continue
+				}
+				path, err := exec.LookPath(name)
+				if err != nil {
+					t.Fatal(err)
+				}
+				if err := os.Symlink(path, filepath.Join(f.bin, name)); err != nil {
+					t.Fatal(err)
+				}
+			}
+			marker := filepath.Join(f.assets, "curl-was-called")
+			// Replacing curl with a marker makes any premature network operation observable.
+			if missing[0] != "curl" {
+				writeFixture(t, filepath.Join(f.bin, "curl"), "#!/bin/bash\nprintf called > \"$FIXTURE_ASSETS/curl-was-called\"\nexit 99\n", 0o755)
+			}
+			f.env = append(f.env, "PATH="+f.bin)
+			installed := filepath.Join(f.home, "local bin's", "netssh")
+			writeFixture(t, installed, "old binary", 0o755)
+			out, err := f.run(t)
+			if err == nil {
+				t.Fatalf("missing dependencies accepted: %s", out)
+			}
+			for _, name := range missing {
+				if !strings.Contains(out, name) {
+					t.Errorf("missing diagnostic for %s: %s", name, out)
+				}
+			}
+			if _, err := os.Stat(marker); !os.IsNotExist(err) {
+				t.Fatal("curl ran before dependency checks completed")
+			}
+			data, _ := os.ReadFile(installed)
+			if string(data) != "old binary" {
+				t.Fatal("binary changed")
+			}
+			if _, err := os.Stat(filepath.Join(f.home, ".bashrc")); !os.IsNotExist(err) {
+				t.Fatal("profile created")
+			}
+		})
+	}
+}
+
+func TestInstallerChecksSudoBeforeDownloadingWhenNeeded(t *testing.T) {
+	if os.Geteuid() == 0 {
+		t.Skip("root can write directories regardless of mode bits")
+	}
+	f := newInstallerFixture(t)
+	for _, name := range []string{"sed", "awk", "mktemp", "rm", "dirname", "readlink", "mkdir", "cat", "install", "mv", "cp", "chmod", "cmp", "sha256sum"} {
+		path, err := exec.LookPath(name)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if err := os.Symlink(path, filepath.Join(f.bin, name)); err != nil {
+			t.Fatal(err)
+		}
+	}
+	locked := filepath.Join(f.home, "locked")
+	if err := os.Mkdir(locked, 0o555); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { os.Chmod(locked, 0o755) })
+	writeFixture(t, filepath.Join(f.bin, "curl"), "#!/bin/bash\nprintf called > \"$FIXTURE_ASSETS/curl-was-called\"\nexit 99\n", 0o755)
+	f.env = append(f.env, "PATH="+f.bin, "INSTALL_DIR="+filepath.Join(locked, "bin"))
+	out, err := f.run(t)
+	if err == nil || !strings.Contains(out, "sudo") {
+		t.Fatalf("missing sudo diagnostic: %v\n%s", err, out)
+	}
+	if _, err := os.Stat(filepath.Join(f.assets, "curl-was-called")); !os.IsNotExist(err) {
+		t.Fatal("download ran before sudo check")
+	}
+}

internal/cache/cache.go

@@ -2,13 +2,17 @@ package cache
 
 import (
 	"encoding/json"
-	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/storage"
+	"fmt"
 	"os"
 	"path/filepath"
 	"sort"
 	"strings"
 	"sync"
 	"time"
+
+	"golang.org/x/sys/unix"
+
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/storage"
 )
 
 type Entry struct {
@@ -20,8 +24,18 @@ type Entry struct {
 	LastUsed time.Time `json:"last_used,omitempty"`
 }
 
+type changeKind uint8
+
+const (
+	upsertChange changeKind = iota
+	deleteChange
+	usageChange
+)
+
 type Cache struct {
 	mu           sync.RWMutex
+	dirty        map[string]changeKind
+	cleared      bool
 	entries      map[string]Entry
 	path         string
 	ttl          time.Duration
@@ -39,6 +53,7 @@ func New(path string, ttlSeconds int) *Cache {
 	}
 	return &Cache{
 		entries:      make(map[string]Entry),
+		dirty:        make(map[string]changeKind),
 		path:         path,
 		ttl:          time.Duration(ttlSeconds) * time.Second,
 		refreshStamp: stamp,
@@ -94,6 +109,8 @@ func (c *Cache) Load() error {
 		return err
 	}
 
+	c.dirty = make(map[string]changeKind)
+	c.cleared = false
 	c.entries = make(map[string]Entry, len(df.Entries))
 	for _, e := range df.Entries {
 		c.entries[e.Name] = e
@@ -101,23 +118,80 @@ func (c *Cache) Load() error {
 	return nil
 }
 
+// Save merges only local changes under a process-wide file lock. Atomic rename
+// alone prevents torn JSON but cannot prevent lost updates from another process.
 func (c *Cache) Save() error {
-	c.mu.RLock()
-	df := diskFormat{Entries: make([]Entry, 0, len(c.entries))}
-	for _, e := range c.entries {
-		df.Entries = append(df.Entries, e)
-	}
-	c.mu.RUnlock()
-
+	c.mu.Lock()
+	defer c.mu.Unlock()
 	if err := os.MkdirAll(filepath.Dir(c.path), 0o755); err != nil {
 		return err
 	}
+	lock, err := os.OpenFile(c.path+".lock", os.O_CREATE|os.O_RDWR, 0o600)
+	if err != nil {
+		return err
+	}
+	defer lock.Close()
+	if err := unix.Flock(int(lock.Fd()), unix.LOCK_EX); err != nil {
+		return err
+	}
+	defer unix.Flock(int(lock.Fd()), unix.LOCK_UN)
 
+	merged := make(map[string]Entry)
+	if !c.cleared {
+		data, err := os.ReadFile(c.path)
+		if err != nil && !os.IsNotExist(err) {
+			return err
+		}
+		if err == nil {
+			var df diskFormat
+			if err := json.Unmarshal(data, &df); err != nil {
+				return err
+			}
+			for _, e := range df.Entries {
+				merged[e.Name] = e
+			}
+		}
+	}
+	for name, change := range c.dirty {
+		if change == deleteChange {
+			delete(merged, name)
+			continue
+		}
+		e := c.entries[name]
+		old, exists := merged[name]
+		if change == usageChange && !exists {
+			// A connection finishing after a refresh or clear must not
+			// restore an entry that the other process removed.
+			continue
+		}
+		if exists {
+			lastUsed := e.LastUsed
+			if change == usageChange || old.CachedAt.After(e.CachedAt) {
+				e = old
+			}
+			if old.LastUsed.After(lastUsed) {
+				lastUsed = old.LastUsed
+			}
+			e.LastUsed = lastUsed
+		}
+		merged[name] = e
+	}
+	df := diskFormat{Entries: make([]Entry, 0, len(merged))}
+	for _, e := range merged {
+		df.Entries = append(df.Entries, e)
+	}
+	sort.Slice(df.Entries, func(i, j int) bool { return df.Entries[i].Name < df.Entries[j].Name })
 	data, err := json.MarshalIndent(df, "", "  ")
 	if err != nil {
 		return err
 	}
-	return storage.WriteFile(c.path, data, 0o600)
+	if err := storage.WriteFile(c.path, data, 0o600); err != nil {
+		return err
+	}
+	c.entries = merged
+	c.dirty = make(map[string]changeKind)
+	c.cleared = false
+	return nil
 }
 
 func (c *Cache) Upsert(e Entry) {
@@ -127,9 +201,18 @@ func (c *Cache) Upsert(e Entry) {
 		e.LastUsed = old.LastUsed
 	}
 	c.entries[e.Name] = e
+	c.dirty[e.Name] = upsertChange
 	c.mu.Unlock()
 }
 
+// Delete removes an entry when a refresh can no longer resolve it safely.
+func (c *Cache) Delete(name string) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	delete(c.entries, name)
+	c.dirty[name] = deleteChange
+}
+
 // MarkUsed records the current time as LastUsed for the named entry.
 // It is a no-op if the entry does not exist.
 func (c *Cache) MarkUsed(name string) {
@@ -138,6 +221,9 @@ func (c *Cache) MarkUsed(name string) {
 	if e, ok := c.entries[name]; ok {
 		e.LastUsed = time.Now()
 		c.entries[name] = e
+		if _, changed := c.dirty[name]; !changed {
+			c.dirty[name] = usageChange
+		}
 	}
 }
 
@@ -172,26 +258,28 @@ func (c *Cache) Search(prefix string) []Entry {
 	prefix = strings.ToLower(prefix)
 	var out []Entry
 	for name, e := range c.entries {
-		if strings.HasPrefix(strings.ToLower(name), prefix) {
+		_, hostname, qualified := strings.Cut(strings.ToLower(name), "/")
+		if strings.HasPrefix(strings.ToLower(name), prefix) || (qualified && !strings.Contains(prefix, "/") && strings.HasPrefix(hostname, prefix)) {
 			out = append(out, e)
 		}
 	}
 	return out
 }
 
-// GetByShortcut scans all entries and returns the first whose normalized name matches
-// the normalized shortcut. Returns (entry, found, fresh).
-func (c *Cache) GetByShortcut(shortcut string, normalize func(string) string) (entry Entry, found bool, fresh bool) {
+// GetByShortcut rejects collisions instead of choosing a random map entry.
+func (c *Cache) GetByShortcut(shortcut string, normalize func(string) string) (entry Entry, found bool, fresh bool, err error) {
 	c.mu.RLock()
 	defer c.mu.RUnlock()
 	norm := normalize(shortcut)
 	for _, e := range c.entries {
 		if normalize(e.Name) == norm {
-			isFresh := c.ttl > 0 && time.Since(e.CachedAt) < c.ttl
-			return e, true, isFresh
+			if found {
+				return Entry{}, false, false, fmt.Errorf("ambiguous shortcut %q; use a full hostname", shortcut)
+			}
+			entry, found = e, true
 		}
 	}
-	return Entry{}, false, false
+	return entry, found, found && c.ttl > 0 && time.Since(entry.CachedAt) < c.ttl, nil
 }
 
 // Get returns an entry and reports whether it is still within the TTL.
@@ -212,6 +300,8 @@ func (c *Cache) Get(name string) (entry Entry, fresh bool) {
 func (c *Cache) Clear() {
 	c.mu.Lock()
 	c.entries = make(map[string]Entry)
+	c.dirty = make(map[string]changeKind)
+	c.cleared = true
 	c.mu.Unlock()
 }
 

internal/cache/cache_test.go

@@ -314,7 +314,7 @@ func TestGetByShortcut_MatchFresh(t *testing.T) {
 		return s
 	}
 
-	e, found, fresh := c.GetByShortcut("web01", normalize)
+	e, found, fresh, _ := c.GetByShortcut("web01", normalize)
 	if !found {
 		t.Fatal("expected entry to be found")
 	}
@@ -340,7 +340,7 @@ func TestGetByShortcut_MatchStale(t *testing.T) {
 		return s
 	}
 
-	_, found, fresh := c.GetByShortcut("web01", normalize)
+	_, found, fresh, _ := c.GetByShortcut("web01", normalize)
 	if !found {
 		t.Fatal("expected entry to be found even when stale")
 	}
@@ -353,7 +353,7 @@ func TestGetByShortcut_NotFound(t *testing.T) {
 	c := New("", 3600)
 	c.Upsert(Entry{Name: "db01.example.com", IP: "10.0.0.2", Kind: "device"})
 
-	_, found, _ := c.GetByShortcut("web01", func(s string) string { return s })
+	_, found, _, _ := c.GetByShortcut("web01", func(s string) string { return s })
 	if found {
 		t.Error("should not find an entry that does not match the shortcut")
 	}
@@ -361,7 +361,7 @@ func TestGetByShortcut_NotFound(t *testing.T) {
 
 func TestGetByShortcut_EmptyCache(t *testing.T) {
 	c := New("", 3600)
-	_, found, _ := c.GetByShortcut("web01", func(s string) string { return s })
+	_, found, _, _ := c.GetByShortcut("web01", func(s string) string { return s })
 	if found {
 		t.Error("empty cache should return found=false")
 	}
@@ -381,7 +381,7 @@ func TestGetByShortcut_MultiDomain(t *testing.T) {
 		return s
 	}
 
-	e, found, _ := c.GetByShortcut("web01", normalize)
+	e, found, _, _ := c.GetByShortcut("web01", normalize)
 	if !found {
 		t.Fatal("should match entry with second configured domain")
 	}
@@ -483,3 +483,15 @@ func TestUpsertPreservesUsageHistory(t *testing.T) {
 		t.Fatalf("history lost: %+v", after)
 	}
 }
+
+func TestSearchMatchesHostnamesAcrossQualifiedSources(t *testing.T) {
+	c := New("", 3600)
+	c.Upsert(Entry{Name: "office/web01", IP: "10.0.0.1"})
+	c.Upsert(Entry{Name: "lab/web01", IP: "10.0.0.2"})
+	c.Upsert(Entry{Name: "lab/db01", IP: "10.0.0.3"})
+	for query, want := range map[string]int{"web": 2, "office/web": 1, "lab/": 2, "WEB": 2} {
+		if got := len(c.Search(query)); got != want {
+			t.Errorf("Search(%q)=%d, want %d", query, got, want)
+		}
+	}
+}

internal/cache/concurrency_test.go

@@ -0,0 +1,182 @@
+package cache
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestShortcutRejectsAmbiguousTargets(t *testing.T) {
+	c := New("", 3600)
+	c.Upsert(Entry{Name: "web.prod.example", IP: "10.0.0.1"})
+	c.Upsert(Entry{Name: "web.dev.example", IP: "10.0.0.2"})
+	normalize := func(s string) string { return strings.SplitN(s, ".", 2)[0] }
+	for range 100 {
+		entry, found, fresh, err := c.GetByShortcut("web", normalize)
+		if err == nil || found || fresh || entry.Name != "" {
+			t.Fatalf("ambiguous shortcut returned target: %+v, %v, %v, %v", entry, found, fresh, err)
+		}
+	}
+}
+
+func TestSaveMergesIndependentlyLoadedCaches(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "hosts.json")
+	a, b := New(path, 3600), New(path, 3600)
+	for _, c := range []*Cache{a, b} {
+		if err := c.Load(); err != nil {
+			t.Fatal(err)
+		}
+	}
+	a.Upsert(Entry{Name: "a", IP: "10.0.0.1"})
+	b.Upsert(Entry{Name: "b", IP: "10.0.0.2"})
+	for _, c := range []*Cache{a, b} {
+		if err := c.Save(); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if err := a.Load(); err != nil {
+		t.Fatal(err)
+	}
+	if len(a.All()) != 2 {
+		t.Fatalf("lost an update: %+v", a.All())
+	}
+
+	// Saving a stale usage update must retain newer IPs and both usage times.
+	if err := b.Load(); err != nil {
+		t.Fatal(err)
+	}
+	b.MarkUsed("a")
+	used, _ := b.Get("a")
+	a.Upsert(Entry{Name: "a", IP: "10.0.0.3"})
+	if err := a.Save(); err != nil {
+		t.Fatal(err)
+	}
+	if err := b.Save(); err != nil {
+		t.Fatal(err)
+	}
+	got, _ := b.Get("a")
+	if got.IP != "10.0.0.3" || !got.LastUsed.Equal(used.LastUsed) {
+		t.Fatalf("lost refreshed IP or usage: %+v", got)
+	}
+
+	b.Delete("a")
+	if err := b.Save(); err != nil {
+		t.Fatal(err)
+	}
+	if err := a.Load(); err != nil {
+		t.Fatal(err)
+	}
+	if got, _ := a.Get("a"); got.Name != "" {
+		t.Fatalf("deleted entry survived: %+v", got)
+	}
+	a.Clear()
+	if err := a.Save(); err != nil {
+		t.Fatal(err)
+	}
+	if err := b.Load(); err != nil {
+		t.Fatal(err)
+	}
+	if len(b.All()) != 0 {
+		t.Fatal("clear merged old entries back in")
+	}
+}
+
+func TestSaveAcrossProcesses(t *testing.T) {
+	if path := os.Getenv("NETSSH_TEST_CACHE_WRITER_PATH"); path != "" {
+		c := New(path, 3600)
+		if err := c.Load(); err != nil {
+			t.Fatal(err)
+		}
+		c.Upsert(Entry{Name: os.Getenv("NETSSH_TEST_CACHE_WRITER_NAME"), IP: "10.0.0.1"})
+		if err := c.Save(); err != nil {
+			t.Fatal(err)
+		}
+		return
+	}
+	path := filepath.Join(t.TempDir(), "hosts.json")
+	const writers = 8
+	cmds := make([]*exec.Cmd, writers)
+	for i := range cmds {
+		cmd := exec.Command(os.Args[0], "-test.run=^TestSaveAcrossProcesses$")
+		cmd.Env = append(os.Environ(), "NETSSH_TEST_CACHE_WRITER_PATH="+path, fmt.Sprintf("NETSSH_TEST_CACHE_WRITER_NAME=host-%d", i))
+		cmd.Stdout, cmd.Stderr = os.Stdout, os.Stderr
+		if err := cmd.Start(); err != nil {
+			t.Fatal(err)
+		}
+		cmds[i] = cmd
+	}
+	for _, cmd := range cmds {
+		if err := cmd.Wait(); err != nil {
+			t.Error(err)
+		}
+	}
+	c := New(path, 3600)
+	if err := c.Load(); err != nil {
+		t.Fatal(err)
+	}
+	if len(c.All()) != writers {
+		t.Fatalf("lost concurrent updates: got %d, want %d", len(c.All()), writers)
+	}
+}
+
+func TestSavePreservesNewerUsageFromDisk(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "hosts.json")
+	a := New(path, 3600)
+	a.Upsert(Entry{Name: "web", IP: "10.0.0.1", LastUsed: time.Now()})
+	if err := a.Save(); err != nil {
+		t.Fatal(err)
+	}
+	b := New(path, 3600)
+	if err := b.Load(); err != nil {
+		t.Fatal(err)
+	}
+	a.MarkUsed("web")
+	used, _ := a.Get("web")
+	if err := a.Save(); err != nil {
+		t.Fatal(err)
+	}
+	b.Upsert(Entry{Name: "web", IP: "10.0.0.2"})
+	if err := b.Save(); err != nil {
+		t.Fatal(err)
+	}
+	got, _ := b.Get("web")
+	if got.IP != "10.0.0.2" || !got.LastUsed.Equal(used.LastUsed) {
+		t.Fatalf("lost data: %+v", got)
+	}
+}
+
+func TestUsageSaveDoesNotRestoreRemovedHosts(t *testing.T) {
+	for _, clear := range []bool{false, true} {
+		t.Run(fmt.Sprintf("clear=%v", clear), func(t *testing.T) {
+			path := filepath.Join(t.TempDir(), "hosts.json")
+			a := New(path, 3600)
+			a.Upsert(Entry{Name: "web", IP: "10.0.0.1"})
+			if err := a.Save(); err != nil {
+				t.Fatal(err)
+			}
+			b := New(path, 3600)
+			if err := b.Load(); err != nil {
+				t.Fatal(err)
+			}
+			b.MarkUsed("web")
+			if clear {
+				a.Clear()
+			} else {
+				a.Delete("web")
+			}
+			if err := a.Save(); err != nil {
+				t.Fatal(err)
+			}
+			if err := b.Save(); err != nil {
+				t.Fatal(err)
+			}
+			if len(b.All()) != 0 {
+				t.Fatalf("usage update restored removed entry: %+v", b.All())
+			}
+		})
+	}
+}

internal/config/config.go

@@ -4,23 +4,33 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"regexp"
 	"strings"
 
 	"github.com/spf13/viper"
 )
 
 type Config struct {
-	NetBox    NetBoxConfig    `mapstructure:"netbox"`
-	Resolver  ResolverConfig  `mapstructure:"resolver"`
-	Cache     CacheConfig     `mapstructure:"cache"`
-	SSH       SSHConfig       `mapstructure:"ssh"`
-	Shortcuts ShortcutsConfig `mapstructure:"shortcuts"`
+	Shell      ShellConfig      `mapstructure:"shell"`
+	NetBox     NetBoxConfig     `mapstructure:"netbox"`
+	NetBoxes   []NetBoxConfig   `mapstructure:"netboxes"`
+	Resolver   ResolverConfig   `mapstructure:"resolver"`
+	Cache      CacheConfig      `mapstructure:"cache"`
+	SSH        SSHConfig        `mapstructure:"ssh"`
+	Shortcuts  ShortcutsConfig  `mapstructure:"shortcuts"`
+	Completion CompletionConfig `mapstructure:"completion"`
+}
+
+type ShellConfig struct {
+	Alias string `mapstructure:"alias"`
 }
 
 type NetBoxConfig struct {
-	URL          string `mapstructure:"url"`
-	Token        string `mapstructure:"token"`
-	TokenVersion int    `mapstructure:"token_version"`
+	Name         string     `mapstructure:"name"`
+	URL          string     `mapstructure:"url"`
+	Token        string     `mapstructure:"token"`
+	TokenVersion int        `mapstructure:"token_version"`
+	SSH          SSHOptions `mapstructure:"ssh"`
 }
 
 type ResolverConfig struct {
@@ -37,6 +47,13 @@ type CacheConfig struct {
 type SSHConfig struct {
 	DefaultUser string `mapstructure:"default_user"`
 	DefaultPort int    `mapstructure:"default_port"`
+	SSHOptions  `mapstructure:",squash"`
+	Rules       []SSHRule `mapstructure:"rules"`
+}
+
+type CompletionConfig struct {
+	// MaxResults limits the number of hostnames offered per completion; 0 = unlimited.
+	MaxResults int `mapstructure:"max_results"`
 }
 
 type ShortcutsConfig struct {
@@ -71,7 +88,7 @@ func Load() (*Config, error) {
 	v.SetEnvPrefix("NETSSH")
 	v.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))
 	v.AutomaticEnv()
-	for _, key := range []string{"netbox.url", "netbox.token", "netbox.token_version", "resolver.strategies", "resolver.management_subnets", "resolver.interface_name", "cache.ttl", "cache.path", "ssh.default_user", "ssh.default_port", "shortcuts.domains", "shortcuts.strip_hyphens"} {
+	for _, key := range []string{"netbox.url", "netbox.token", "netbox.token_version", "resolver.strategies", "resolver.management_subnets", "resolver.interface_name", "cache.ttl", "cache.path", "ssh.default_user", "ssh.default_port", "shortcuts.domains", "shortcuts.strip_hyphens", "shell.alias", "ssh.proxy_jump", "ssh.host_key_checking", "ssh.target", "ssh.address_family", "completion.max_results"} {
 		if err := v.BindEnv(key); err != nil {
 			return nil, err
 		}
@@ -87,6 +104,15 @@ func Load() (*Config, error) {
 	if err := v.Unmarshal(&cfg); err != nil {
 		return nil, fmt.Errorf("parsing config: %w", err)
 	}
+	// Legacy environment variables must not invent an additional unnamed source
+	// when a file explicitly configures named instances (including wizard migration).
+	if len(cfg.NetBoxes) > 0 && !v.InConfig("netbox.url") {
+		cfg.NetBox = NetBoxConfig{}
+	}
+
+	if err := ValidateCommandAlias(cfg.Shell.Alias); err != nil {
+		return nil, err
+	}
 
 	if cfg.NetBox.TokenVersion == 0 && cfg.NetBox.Token != "" {
 		if strings.HasPrefix(cfg.NetBox.Token, "nbt_") {
@@ -96,6 +122,23 @@ func Load() (*Config, error) {
 		}
 	}
 
+	if err := cfg.ValidateNetBoxes(); err != nil {
+		return nil, err
+	}
+	if err := cfg.ValidateSSH(); err != nil {
+		return nil, err
+	}
+	for i := range cfg.NetBoxes {
+		source := &cfg.NetBoxes[i]
+		source.Name = strings.ToLower(source.Name)
+		if source.TokenVersion == 0 && source.Token != "" {
+			source.TokenVersion = 1
+			if strings.HasPrefix(source.Token, "nbt_") {
+				source.TokenVersion = 2
+			}
+		}
+	}
+
 	if cfg.Cache.Path == "" {
 		cacheDir, err := os.UserCacheDir()
 		if err != nil {
@@ -106,3 +149,18 @@ func Load() (*Config, error) {
 
 	return &cfg, nil
 }
+
+// ValidateCommandAlias restricts aliases to portable shell identifiers.
+func ValidateCommandAlias(name string) error {
+	if name == "" {
+		return nil
+	}
+	if !regexp.MustCompile(`^[a-zA-Z_][a-zA-Z0-9_]*$`).MatchString(name) {
+		return fmt.Errorf("shell.alias must be a shell identifier (e.g. j)")
+	}
+	switch name {
+	case "netssh", "alias", "unalias", "source", "eval", "exec", "command", "builtin", "if", "then", "else", "elif", "fi", "for", "while", "until", "do", "done", "case", "esac", "in", "function", "select", "time", "coproc", "end", "begin", "switch", "set", "export", "return", "break", "continue", "not", "and", "or":
+		return fmt.Errorf("shell.alias %q is reserved; choose another name", name)
+	}
+	return nil
+}

internal/config/config_test.go

@@ -157,3 +157,23 @@ func TestEnvironmentOverridesWithoutConfigKeys(t *testing.T) {
 		t.Fatalf("env ignored: %+v", cfg)
 	}
 }
+
+func TestCommandAliasEnvironmentAndValidation(t *testing.T) {
+	t.Setenv("XDG_CONFIG_HOME", t.TempDir())
+	t.Setenv("NETSSH_SHELL_ALIAS", "j")
+	cfg, err := Load()
+	if err != nil || cfg.Shell.Alias != "j" {
+		t.Fatalf("alias env: %+v, %v", cfg, err)
+	}
+	for _, name := range []string{"netssh", "if", "alias", "j;touch /tmp/bad", "a b", "1bad"} {
+		t.Setenv("NETSSH_SHELL_ALIAS", name)
+		if _, err := Load(); err == nil {
+			t.Errorf("unsafe alias accepted: %q", name)
+		}
+	}
+	for _, name := range []string{"", "j", "jump_server", "goSSH"} {
+		if err := ValidateCommandAlias(name); err != nil {
+			t.Errorf("valid alias rejected: %s: %v", name, err)
+		}
+	}
+}

internal/config/instances.go

@@ -0,0 +1,56 @@
+package config
+
+import (
+	"crypto/sha256"
+	"fmt"
+	"net/url"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+var instanceName = regexp.MustCompile(`^[a-zA-Z0-9][a-zA-Z0-9_-]*$`)
+
+// ValidateNetBoxes keeps source names usable as instance/hostname selectors.
+func (c *Config) ValidateNetBoxes() error {
+	if len(c.NetBoxes) > 0 && c.NetBox.URL != "" {
+		return fmt.Errorf("configure either netbox or netboxes, not both")
+	}
+	seen := make(map[string]bool)
+	for _, source := range c.NetBoxes {
+		if !instanceName.MatchString(source.Name) {
+			return fmt.Errorf("netboxes.name %q must contain only letters, digits, underscores, or hyphens", source.Name)
+		}
+		name := strings.ToLower(source.Name)
+		if seen[name] {
+			return fmt.Errorf("duplicate NetBox instance name %q", source.Name)
+		}
+		seen[name] = true
+		u, err := url.Parse(source.URL)
+		if err != nil || (u.Scheme != "http" && u.Scheme != "https") || u.Host == "" || u.RawQuery != "" || u.Fragment != "" {
+			return fmt.Errorf("NetBox %q requires an HTTP(S) URL without query or fragment", source.Name)
+		}
+		if source.TokenVersion < 0 || source.TokenVersion > 2 {
+			return fmt.Errorf("NetBox %q: token_version must be 0, 1, or 2", source.Name)
+		}
+	}
+	return nil
+}
+
+func (c *Config) HasNetBox() bool { return c.NetBox.URL != "" || len(c.NetBoxes) > 0 }
+
+// CachePath isolates named sources from legacy caches and from changed endpoints.
+// Rotating a token or reordering the sources does not discard usage history.
+func (c *Config) CachePath() string {
+	if len(c.NetBoxes) == 0 {
+		return c.Cache.Path
+	}
+	var identities []string
+	for _, source := range c.NetBoxes {
+		identities = append(identities, strings.ToLower(source.Name)+"\x00"+strings.TrimRight(source.URL, "/"))
+	}
+	sort.Strings(identities)
+	sum := sha256.Sum256([]byte(strings.Join(identities, "\x00")))
+	return filepath.Join(filepath.Dir(c.Cache.Path), fmt.Sprintf("instances-%x", sum[:8]), filepath.Base(c.Cache.Path))
+}

internal/config/instances_test.go

@@ -0,0 +1,79 @@
+package config
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestLoadNamedNetBoxes(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("XDG_CONFIG_HOME", dir)
+	t.Setenv("NETSSH_NETBOX_URL", "https://legacy-env.example")
+	t.Setenv("NETSSH_NETBOX_TOKEN", "legacy-env-token")
+	data := `netboxes:
+  - name: Office
+    url: https://office.example/netbox
+    token: nbt_office
+  - name: lab
+    url: https://lab.example
+    token: legacy-token
+cache:
+  path: /tmp/netssh-tests/hosts.json
+`
+	if err := os.WriteFile(filepath.Join(dir, "netssh.yaml"), []byte(data), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	cfg, err := Load()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !cfg.HasNetBox() || len(cfg.NetBoxes) != 2 || cfg.NetBoxes[0].Name != "office" || cfg.NetBoxes[0].TokenVersion != 2 || cfg.NetBoxes[1].TokenVersion != 1 {
+		t.Fatalf("bad instances: %+v", cfg.NetBoxes)
+	}
+	if cfg.NetBox.URL != "" {
+		t.Fatal("legacy environment variables added an unnamed instance")
+	}
+	first := cfg.CachePath()
+	if first == cfg.Cache.Path {
+		t.Fatal("named sources reuse legacy cache")
+	}
+	cfg.NetBoxes[0], cfg.NetBoxes[1] = cfg.NetBoxes[1], cfg.NetBoxes[0]
+	cfg.NetBoxes[0].Token = "rotated"
+	if cfg.CachePath() != first {
+		t.Fatal("reordering/rotating credentials discarded cache")
+	}
+	cfg.NetBoxes[0].URL = "https://other.example"
+	if cfg.CachePath() == first {
+		t.Fatal("changed endpoint reuses old hosts")
+	}
+}
+
+func TestValidateNetBoxes(t *testing.T) {
+	good := NetBoxConfig{Name: "office", URL: "https://office.example"}
+	for _, tc := range []struct {
+		name string
+		cfg  Config
+	}{
+		{"duplicate", Config{NetBoxes: []NetBoxConfig{good, {Name: "OFFICE", URL: "https://other.example"}}}},
+		{"empty name", Config{NetBoxes: []NetBoxConfig{{URL: "https://office.example"}}}},
+		{"invalid name", Config{NetBoxes: []NetBoxConfig{{Name: "a/b", URL: "https://office.example"}}}},
+		{"missing URL", Config{NetBoxes: []NetBoxConfig{{Name: "office"}}}},
+		{"invalid URL", Config{NetBoxes: []NetBoxConfig{{Name: "office", URL: "file:///tmp/netbox"}}}},
+		{"conflicting config", Config{NetBox: good, NetBoxes: []NetBoxConfig{good}}},
+		{"invalid token version", Config{NetBoxes: []NetBoxConfig{{Name: "office", URL: good.URL, TokenVersion: 3}}}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			if err := tc.cfg.ValidateNetBoxes(); err == nil {
+				t.Fatal("invalid configuration accepted")
+			}
+		})
+	}
+	legacy := Config{NetBox: good, Cache: CacheConfig{Path: "hosts.json"}}
+	if err := legacy.ValidateNetBoxes(); err != nil {
+		t.Fatal(err)
+	}
+	if !legacy.HasNetBox() || legacy.CachePath() != "hosts.json" {
+		t.Fatal("legacy behavior changed")
+	}
+}

internal/config/ssh.go

@@ -0,0 +1,181 @@
+package config
+
+import (
+	"fmt"
+	"path"
+	"regexp"
+	"strings"
+)
+
+// SSHOptions are connection settings that can be set globally, per NetBox
+// instance, and per rule. More specific layers override less specific ones.
+type SSHOptions struct {
+	// ProxyJump is passed as -J; "none" disables a jump host set by a broader layer.
+	ProxyJump string `mapstructure:"proxy_jump"`
+	// HostKeyChecking is strict, accept-new, or off. Empty keeps ssh's own setting.
+	HostKeyChecking string `mapstructure:"host_key_checking"`
+	// Target selects the ssh destination: ip (default), name, or hostname.
+	Target string `mapstructure:"target"`
+	// AddressFamily is any, inet, or inet6.
+	AddressFamily string `mapstructure:"address_family"`
+	// ExtraArgs are inserted verbatim before the destination.
+	ExtraArgs []string `mapstructure:"extra_args"`
+	// Options are passed as -o Key=Value.
+	Options map[string]string `mapstructure:"options"`
+}
+
+// SSHRule applies SSH options to hosts that match every non-empty field.
+type SSHRule struct {
+	Match      SSHMatch `mapstructure:"match"`
+	SSHOptions `mapstructure:",squash"`
+}
+
+// SSHMatch selects hosts by NetBox attributes available in the cache.
+type SSHMatch struct {
+	Tag      string `mapstructure:"tag"`
+	Instance string `mapstructure:"instance"`
+	Kind     string `mapstructure:"kind"`
+	Name     string `mapstructure:"name"` // shell-style glob, e.g. "*.dmz.example.com"
+}
+
+// SSHHost identifies the resolved host that SSH options are computed for.
+type SSHHost struct {
+	Instance string
+	Name     string // NetBox name without the instance prefix
+	Kind     string
+	Tags     []string
+}
+
+var sshOptionKey = regexp.MustCompile(`^[A-Za-z][A-Za-z0-9]*$`)
+
+// ValidateSSH rejects values that would be passed to ssh in an unexpected form.
+func (c *Config) ValidateSSH() error {
+	if err := c.SSH.SSHOptions.validate("ssh"); err != nil {
+		return err
+	}
+	for i, rule := range c.SSH.Rules {
+		if err := rule.SSHOptions.validate(fmt.Sprintf("ssh.rules[%d]", i)); err != nil {
+			return err
+		}
+		if rule.Match == (SSHMatch{}) {
+			return fmt.Errorf("ssh.rules[%d]: match must set at least one of tag, instance, kind, name", i)
+		}
+		if _, err := path.Match(rule.Match.Name, ""); err != nil {
+			return fmt.Errorf("ssh.rules[%d]: invalid name pattern %q", i, rule.Match.Name)
+		}
+	}
+	if err := c.NetBox.SSH.validate("netbox.ssh"); err != nil {
+		return err
+	}
+	for _, source := range c.NetBoxes {
+		if err := source.SSH.validate("netboxes." + source.Name + ".ssh"); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func (o SSHOptions) validate(scope string) error {
+	switch o.HostKeyChecking {
+	case "", "strict", "accept-new", "off":
+	default:
+		return fmt.Errorf("%s.host_key_checking must be strict, accept-new, or off", scope)
+	}
+	switch o.Target {
+	case "", "ip", "name", "hostname":
+	default:
+		return fmt.Errorf("%s.target must be ip, name, or hostname", scope)
+	}
+	switch o.AddressFamily {
+	case "", "any", "inet", "inet6":
+	default:
+		return fmt.Errorf("%s.address_family must be any, inet, or inet6", scope)
+	}
+	if strings.HasPrefix(o.ProxyJump, "-") || strings.ContainsAny(o.ProxyJump, " \t\n") {
+		return fmt.Errorf("%s.proxy_jump %q is not a valid jump host", scope, o.ProxyJump)
+	}
+	for key, value := range o.Options {
+		if !sshOptionKey.MatchString(key) || strings.ContainsAny(value, "\n\r") {
+			return fmt.Errorf("%s.options: invalid option %q", scope, key)
+		}
+	}
+	return nil
+}
+
+// SSHOptionsFor merges global, instance, and matching rule options for host.
+func (c *Config) SSHOptionsFor(host SSHHost) SSHOptions {
+	merged := c.SSH.SSHOptions.merge(SSHOptions{})
+	if host.Instance == "" {
+		merged = merged.merge(c.NetBox.SSH)
+	}
+	for _, source := range c.NetBoxes {
+		if strings.EqualFold(source.Name, host.Instance) {
+			merged = merged.merge(source.SSH)
+		}
+	}
+	for _, rule := range c.SSH.Rules {
+		if rule.Match.matches(host) {
+			merged = merged.merge(rule.SSHOptions)
+		}
+	}
+	return merged
+}
+
+// merge returns o overridden by the non-empty fields of override.
+// Extra arguments accumulate; options override per key.
+func (o SSHOptions) merge(override SSHOptions) SSHOptions {
+	out := o
+	out.ExtraArgs = append(append([]string(nil), o.ExtraArgs...), override.ExtraArgs...)
+	out.Options = make(map[string]string, len(o.Options)+len(override.Options))
+	for key, value := range o.Options {
+		out.Options[strings.ToLower(key)] = value
+	}
+	for key, value := range override.Options {
+		out.Options[strings.ToLower(key)] = value
+	}
+	if override.ProxyJump != "" {
+		out.ProxyJump = override.ProxyJump
+	}
+	if override.HostKeyChecking != "" {
+		out.HostKeyChecking = override.HostKeyChecking
+	}
+	if override.Target != "" {
+		out.Target = override.Target
+	}
+	if override.AddressFamily != "" {
+		out.AddressFamily = override.AddressFamily
+	}
+	return out
+}
+
+func (m SSHMatch) matches(host SSHHost) bool {
+	if m.Instance != "" && !strings.EqualFold(m.Instance, host.Instance) {
+		return false
+	}
+	if m.Kind != "" && !strings.EqualFold(m.Kind, host.Kind) {
+		return false
+	}
+	if m.Name != "" {
+		if ok, _ := path.Match(strings.ToLower(m.Name), strings.ToLower(host.Name)); !ok {
+			return false
+		}
+	}
+	if m.Tag != "" {
+		found := false
+		for _, tag := range host.Tags {
+			if strings.EqualFold(tag, m.Tag) || strings.EqualFold(tagSlug(tag), m.Tag) {
+				found = true
+				break
+			}
+		}
+		if !found {
+			return false
+		}
+	}
+	return true
+}
+
+// tagSlug approximates NetBox's slug so rules may use either the tag name or slug.
+func tagSlug(name string) string {
+	return strings.Join(strings.Fields(strings.ToLower(name)), "-")
+}

internal/config/ssh_test.go

@@ -0,0 +1,90 @@
+package config
+
+import (
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+func loadYAML(t *testing.T, data string) (*Config, error) {
+	t.Helper()
+	dir := t.TempDir()
+	t.Setenv("XDG_CONFIG_HOME", dir)
+	t.Setenv("HOME", t.TempDir())
+	if err := os.WriteFile(filepath.Join(dir, "netssh.yaml"), []byte(data), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	return Load()
+}
+
+func TestSSHOptionsLayering(t *testing.T) {
+	cfg, err := loadYAML(t, `
+netboxes:
+  - name: prod
+    url: https://prod.example.com
+    ssh:
+      proxy_jump: jh-prod.example.com
+      host_key_checking: strict
+  - name: staging
+    url: https://staging.example.com
+    ssh:
+      host_key_checking: off
+ssh:
+  proxy_jump: jh.example.com
+  extra_args: ["-4"]
+  options:
+    ServerAliveInterval: 60
+    ServerAliveCountMax: 5
+  rules:
+    - match: {tag: dmz}
+      proxy_jump: jh-dmz.example.com
+      options: {ServerAliveInterval: 10}
+    - match: {instance: prod, name: "db*"}
+      proxy_jump: none
+completion:
+  max_results: 200
+`)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if cfg.Completion.MaxResults != 200 {
+		t.Fatalf("max_results: %d", cfg.Completion.MaxResults)
+	}
+	for _, tc := range []struct {
+		host              SSHHost
+		jump, keys, alive string
+	}{
+		{SSHHost{Name: "web"}, "jh.example.com", "", "60"},
+		{SSHHost{Instance: "prod", Name: "web"}, "jh-prod.example.com", "strict", "60"},
+		{SSHHost{Instance: "staging", Name: "web", Tags: []string{"DMZ"}}, "jh-dmz.example.com", "off", "10"},
+		{SSHHost{Instance: "prod", Name: "db01", Tags: []string{"dmz"}}, "none", "strict", "10"},
+	} {
+		got := cfg.SSHOptionsFor(tc.host)
+		if got.ProxyJump != tc.jump || got.HostKeyChecking != tc.keys || got.Options["serveraliveinterval"] != tc.alive || got.Options["serveralivecountmax"] != "5" {
+			t.Errorf("%+v: got %+v", tc.host, got)
+		}
+		if !reflect.DeepEqual(got.ExtraArgs, []string{"-4"}) {
+			t.Errorf("extra args: %v", got.ExtraArgs)
+		}
+	}
+}
+
+func TestSSHOptionsValidation(t *testing.T) {
+	for _, data := range []string{
+		"ssh:\n  host_key_checking: maybe\n",
+		"ssh:\n  target: dns\n",
+		"ssh:\n  address_family: ipx\n",
+		"ssh:\n  proxy_jump: \"-oProxyCommand=x\"\n",
+		"ssh:\n  options:\n    \"bad key\": 1\n",
+		"ssh:\n  rules:\n    - proxy_jump: jh\n",
+		"netboxes:\n  - name: a\n    url: https://a.example\n    ssh:\n      target: nope\n",
+	} {
+		if _, err := loadYAML(t, data); err == nil {
+			t.Errorf("accepted invalid config:\n%s", data)
+		} else if !strings.Contains(err.Error(), "ssh") {
+			t.Errorf("unclear error %v", err)
+		}
+	}
+}

internal/hook/aliases.go

@@ -4,7 +4,14 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"regexp"
+	"sort"
 	"strings"
+
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/cache"
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/config"
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/shortcuts"
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/storage"
 )
 
 // AliasEntry holds a single shell alias mapping.
@@ -15,9 +22,13 @@ type AliasEntry struct {
 
 // AliasesPath returns the path for the bash/zsh aliases file.
 func AliasesPath() string {
-	cacheDir, err := os.UserCacheDir()
-	if err != nil {
-		cacheDir = filepath.Join(os.Getenv("HOME"), ".cache")
+	cacheDir := os.Getenv("XDG_CACHE_HOME")
+	if cacheDir == "" {
+		var err error
+		cacheDir, err = os.UserCacheDir()
+		if err != nil {
+			cacheDir = filepath.Join(os.Getenv("HOME"), ".cache")
+		}
 	}
 	return filepath.Join(cacheDir, "netssh", "aliases.sh")
 }
@@ -25,11 +36,7 @@ func AliasesPath() string {
 // FishAliasesPath returns the path for the fish conf.d aliases file.
 // Fish auto-sources every file in conf.d, so no explicit source line is needed.
 func FishAliasesPath() string {
-	configDir, err := os.UserConfigDir()
-	if err != nil {
-		configDir = filepath.Join(os.Getenv("HOME"), ".config")
-	}
-	return filepath.Join(configDir, "fish", "conf.d", "netssh.fish")
+	return filepath.Join(FishConfigDir(), "conf.d", "netssh.fish")
 }
 
 // WriteAliasFiles writes alias definitions to disk for all supported shells.
@@ -42,7 +49,14 @@ func WriteAliasFiles(entries []AliasEntry) error {
 		return err
 	}
 	writeFishAliasFile(entries) // best-effort — never blocks the caller on failure
-	return nil
+	alias := ""
+	for _, entry := range entries {
+		if entry.Host == "" {
+			alias = entry.Name
+			break
+		}
+	}
+	return SyncCommandCompletion(alias)
 }
 
 func writeShAliasFile(entries []AliasEntry) error {
@@ -54,18 +68,14 @@ func writeShAliasFile(entries []AliasEntry) error {
 	b.WriteString("# netssh aliases — generated automatically, do not edit\n")
 	b.WriteString("# Regenerated on every shell start and after 'netssh cache refresh'.\n")
 	for _, e := range entries {
-		fmt.Fprintf(&b, "alias %s='netssh %s'\n", e.Name, e.Host)
+		b.WriteString(e.Definition("bash") + "\n")
 	}
-	return os.WriteFile(p, []byte(b.String()), 0o644)
+	return storage.WriteFile(p, []byte(b.String()), 0o600)
 }
 
 func writeFishAliasFile(entries []AliasEntry) {
-	configDir, err := os.UserConfigDir()
-	if err != nil {
-		return
-	}
 	// Only write if fish is configured on this system.
-	if _, err := os.Stat(filepath.Join(configDir, "fish")); err != nil {
+	if _, err := os.Stat(FishConfigDir()); err != nil {
 		return
 	}
 	p := FishAliasesPath()
@@ -76,7 +86,60 @@ func writeFishAliasFile(entries []AliasEntry) {
 	b.WriteString("# netssh aliases — generated automatically, do not edit\n")
 	b.WriteString("# Regenerated on every shell start and after 'netssh cache refresh'.\n")
 	for _, e := range entries {
-		fmt.Fprintf(&b, "alias %s 'netssh %s'\n", e.Name, e.Host)
+		b.WriteString(e.Definition("fish") + "\n")
 	}
-	os.WriteFile(p, []byte(b.String()), 0o644) //nolint:errcheck
+	storage.WriteFile(p, []byte(b.String()), 0o600) //nolint:errcheck
+}
+
+// Empty Host represents an alias for the netssh command itself.
+func (e AliasEntry) Definition(shell string) string {
+	command := "netssh"
+	if e.Host != "" {
+		host := e.Host
+		if !regexp.MustCompile(`^[a-zA-Z0-9_.:-]+$`).MatchString(host) {
+			host = shellQuote(host, shell)
+		}
+		command += " " + host
+	}
+	if shell == "fish" {
+		return fmt.Sprintf("alias %s %s", e.Name, shellQuote(command, shell))
+	}
+	return fmt.Sprintf("alias %s=%s", e.Name, shellQuote(command, shell))
+}
+
+func shellQuote(value, shell string) string {
+	if shell == "fish" {
+		value = strings.ReplaceAll(value, `\`, `\\`)
+		return "'" + strings.ReplaceAll(value, "'", `\'`) + "'"
+	}
+	return "'" + strings.ReplaceAll(value, "'", `'\''`) + "'"
+}
+
+// BuildAliasEntries gives the configured command alias priority over host aliases.
+func BuildAliasEntries(entries []cache.Entry, cfg config.Config) []AliasEntry {
+	sort.Slice(entries, func(i, j int) bool { return entries[i].Name < entries[j].Name })
+	seen := map[string]bool{"netssh": true}
+	var out []AliasEntry
+	if cfg.Shell.Alias != "" && config.ValidateCommandAlias(cfg.Shell.Alias) == nil {
+		seen[cfg.Shell.Alias] = true
+		out = append(out, AliasEntry{Name: cfg.Shell.Alias})
+	}
+	for _, e := range entries {
+		name := shortcuts.AliasName(e.Name, cfg.Shortcuts)
+		if seen[name] || name == "" || !regexp.MustCompile(`^[a-zA-Z_][a-zA-Z0-9_-]*$`).MatchString(name) {
+			continue
+		}
+		seen[name] = true
+		out = append(out, AliasEntry{Name: name, Host: e.Name})
+	}
+	return out
+}
+
+// FishConfigDir follows fish's XDG layout on both Linux and macOS.
+func FishConfigDir() string {
+	dir := os.Getenv("XDG_CONFIG_HOME")
+	if dir == "" {
+		dir = filepath.Join(os.Getenv("HOME"), ".config")
+	}
+	return filepath.Join(dir, "fish")
 }

internal/hook/aliases_test.go

@@ -6,6 +6,8 @@ import (
 	"strings"
 	"testing"
 
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/cache"
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/config"
 	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/hook"
 )
 
@@ -208,3 +210,35 @@ func TestUninstall_AlsoRemovesAliasesSourceLine(t *testing.T) {
 		t.Error("other content should be preserved")
 	}
 }
+
+func TestCommandAliasGenerationAndCollision(t *testing.T) {
+	cfg := config.Config{Shell: config.ShellConfig{Alias: "j"}}
+	entries := hook.BuildAliasEntries([]cache.Entry{{Name: "j"}, {Name: "netssh"}, {Name: "web-01"}}, cfg)
+	if len(entries) != 2 {
+		t.Fatalf("entries: %+v", entries)
+	}
+	if got := entries[0].Definition("bash"); got != "alias j='netssh'" {
+		t.Fatal(got)
+	}
+	if got := entries[0].Definition("fish"); got != "alias j 'netssh'" {
+		t.Fatal(got)
+	}
+	if got := entries[1].Definition("bash"); got != "alias web-01='netssh web-01'" {
+		t.Fatal(got)
+	}
+}
+
+func TestAliasesIncludeInstanceName(t *testing.T) {
+	cfg := config.Config{Shortcuts: config.ShortcutsConfig{Domains: []string{".example.com"}}}
+	entries := hook.BuildAliasEntries([]cache.Entry{{Name: "office/web01.example.com"}, {Name: "lab/web01.example.com"}}, cfg)
+	if len(entries) != 2 {
+		t.Fatalf("missing qualified aliases: %+v", entries)
+	}
+	got := map[string]string{}
+	for _, entry := range entries {
+		got[entry.Name] = entry.Host
+	}
+	if got["office_web01"] != "office/web01.example.com" || got["lab_web01"] != "lab/web01.example.com" {
+		t.Fatalf("alias lost source: %+v", entries)
+	}
+}

internal/hook/completion.go

@@ -0,0 +1,159 @@
+package hook
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/config"
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/storage"
+)
+
+const completionMarker = "# netssh command alias completion — generated automatically"
+
+// SyncCommandCompletion installs lazy loaders for the configured command alias.
+// The loaders obtain the canonical completion from the current netssh binary,
+// so aliases configured by the wizard work without a separate completion install.
+func SyncCommandCompletion(alias string) error {
+	if err := config.ValidateCommandAlias(alias); err != nil {
+		return err
+	}
+	statePath := filepath.Join(filepath.Dir(AliasesPath()), "completion_alias")
+	data, err := os.ReadFile(statePath)
+	if err != nil && !os.IsNotExist(err) {
+		return err
+	}
+	previous := strings.TrimSpace(string(data))
+	if err := config.ValidateCommandAlias(previous); err != nil {
+		return fmt.Errorf("invalid completion alias state: %w", err)
+	}
+	if alias == "" && previous == "" {
+		return nil
+	}
+
+	for _, shell := range []string{"bash", "zsh", "fish"} {
+		if previous != "" && previous != alias {
+			path := commandCompletionPath(shell, previous)
+			data, err := os.ReadFile(path)
+			if err != nil && !os.IsNotExist(err) {
+				return err
+			}
+			// Only delete files owned by netssh; preserve any user replacements.
+			if strings.HasPrefix(string(data), completionMarker+"\n") || strings.HasPrefix(string(data), "#compdef "+previous+"\n"+completionMarker+"\n") {
+				if err := os.Remove(path); err != nil && !os.IsNotExist(err) {
+					return err
+				}
+			}
+		}
+		if alias == "" {
+			continue
+		}
+		if shell == "fish" {
+			if _, err := os.Stat(FishConfigDir()); os.IsNotExist(err) {
+				continue
+			} else if err != nil {
+				return err
+			}
+		}
+		path := commandCompletionPath(shell, alias)
+		script := commandCompletionScript(shell, alias)
+		existing, err := os.ReadFile(path)
+		if err != nil && !os.IsNotExist(err) {
+			return err
+		}
+		if string(existing) == script {
+			continue
+		}
+		if err := storage.WriteFile(path, []byte(script), 0o644); err != nil {
+			return fmt.Errorf("writing %s alias completion: %w", shell, err)
+		}
+	}
+	if alias == "" {
+		if err := os.Remove(statePath); err != nil && !os.IsNotExist(err) {
+			return err
+		}
+		return nil
+	}
+	return storage.WriteFile(statePath, []byte(alias+"\n"), 0o600)
+}
+
+func commandCompletionPath(shell, alias string) string {
+	switch shell {
+	case "bash":
+		return filepath.Join(os.Getenv("HOME"), ".local", "share", "bash-completion", "completions", alias)
+	case "zsh":
+		return filepath.Join(ZshFuncDir(), "_"+alias)
+	default:
+		return filepath.Join(FishConfigDir(), "completions", alias+".fish")
+	}
+}
+
+func commandCompletionScript(shell, alias string) string {
+	switch shell {
+	case "bash":
+		return fmt.Sprintf(`%s
+source <(netssh completion bash)
+if [[ $(type -t compopt) == builtin ]]; then
+    complete -o default -F __start_netssh %s
+else
+    complete -o default -o nospace -F __start_netssh %s
+fi
+`, completionMarker, alias, alias)
+	case "zsh":
+		return fmt.Sprintf(`#compdef %s
+%s
+source <(netssh completion zsh)
+compdef _netssh %s
+_netssh "$@"
+`, alias, completionMarker, alias)
+	default:
+		return fmt.Sprintf(`%s
+netssh completion fish | source
+complete --command %s --wraps netssh
+`, completionMarker, alias)
+	}
+}
+
+// CompletionFiles lists the completion and alias files netssh may have
+// installed for itself and for the given command aliases.
+func CompletionFiles(aliases ...string) []string {
+	files := []string{
+		filepath.Join(os.Getenv("HOME"), ".local", "share", "bash-completion", "completions", "netssh"),
+		filepath.Join(ZshFuncDir(), "_netssh"),
+		filepath.Join(FishConfigDir(), "completions", "netssh.fish"),
+		FishAliasesPath(),
+	}
+	// oh-my-zsh caches generated completions separately.
+	for _, dir := range []string{os.Getenv("ZSH_CACHE_DIR"), filepath.Join(os.Getenv("ZSH"), "cache"), filepath.Join(os.Getenv("HOME"), ".oh-my-zsh", "cache")} {
+		if dir != "" && dir != "cache" {
+			files = append(files, filepath.Join(dir, "completions", "_netssh"))
+		}
+	}
+	for _, alias := range aliases {
+		if config.ValidateCommandAlias(alias) != nil || alias == "" {
+			continue
+		}
+		for _, shell := range []string{"bash", "zsh", "fish"} {
+			files = append(files, commandCompletionPath(shell, alias))
+		}
+	}
+	return files
+}
+
+// CompletionAliasState returns the command alias whose completion files were
+// last generated, or "" when there is none.
+func CompletionAliasState() string {
+	data, err := os.ReadFile(filepath.Join(filepath.Dir(AliasesPath()), "completion_alias"))
+	if err != nil {
+		return ""
+	}
+	return strings.TrimSpace(string(data))
+}
+
+// IsGenerated reports whether a completion file was written by netssh,
+// so uninstall never removes a user's own file of the same name.
+func IsGenerated(path string) bool {
+	data, err := os.ReadFile(path)
+	return err == nil && strings.Contains(string(data), "netssh")
+}

internal/hook/completion_test.go

@@ -0,0 +1,207 @@
+package hook_test
+
+import (
+	"bytes"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/hook"
+	"github.com/spf13/cobra"
+)
+
+func completionEnvironment(t *testing.T) map[string]string {
+	t.Helper()
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+	t.Setenv("XDG_CONFIG_HOME", filepath.Join(home, "config"))
+	t.Setenv("XDG_CACHE_HOME", filepath.Join(home, "cache"))
+	if err := os.MkdirAll(hook.FishConfigDir(), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	return map[string]string{
+		"bash": filepath.Join(home, ".local", "share", "bash-completion", "completions", "j"),
+		"zsh":  filepath.Join(home, ".zfunc", "_j"),
+		"fish": filepath.Join(hook.FishConfigDir(), "completions", "j.fish"),
+	}
+}
+
+func TestCommandCompletionTracksAliasChanges(t *testing.T) {
+	paths := completionEnvironment(t)
+	if err := hook.WriteAliasFiles([]hook.AliasEntry{{Name: "j"}}); err != nil {
+		t.Fatal(err)
+	}
+	for _, path := range paths {
+		if _, err := os.Stat(path); err != nil {
+			t.Fatal(err)
+		}
+	}
+	// A manually replaced completion file must survive removal of the old alias.
+	custom := "# user-owned completion\n"
+	if err := os.WriteFile(paths["bash"], []byte(custom), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := hook.WriteAliasFiles([]hook.AliasEntry{{Name: "k"}}); err != nil {
+		t.Fatal(err)
+	}
+	for shell, path := range paths {
+		if shell == "bash" {
+			data, err := os.ReadFile(path)
+			if err != nil || string(data) != custom {
+				t.Fatal("user completion was removed")
+			}
+		} else if _, err := os.Stat(path); !os.IsNotExist(err) {
+			t.Fatalf("stale %s completion remains: %v", shell, err)
+		}
+	}
+	if err := hook.WriteAliasFiles(nil); err != nil {
+		t.Fatal(err)
+	}
+	for _, path := range []string{
+		filepath.Join(os.Getenv("HOME"), ".local", "share", "bash-completion", "completions", "k"),
+		filepath.Join(os.Getenv("HOME"), ".zfunc", "_k"),
+		filepath.Join(hook.FishConfigDir(), "completions", "k.fish"),
+	} {
+		if _, err := os.Stat(path); !os.IsNotExist(err) {
+			t.Fatalf("disabled completion remains: %s: %v", path, err)
+		}
+	}
+}
+
+func TestCommandAliasCompletesServerNamesAcrossShells(t *testing.T) {
+	for _, shell := range []string{"bash", "zsh", "fish"} {
+		t.Run(shell, func(t *testing.T) {
+			executable, err := exec.LookPath(shell)
+			if err != nil {
+				t.Skipf("%s unavailable", shell)
+			}
+			paths := completionEnvironment(t)
+			if err := hook.SyncCommandCompletion("j"); err != nil {
+				t.Fatal(err)
+			}
+			fixtures := t.TempDir()
+			root := &cobra.Command{Use: "netssh"}
+			var canonical bytes.Buffer
+			switch shell {
+			case "bash":
+				err = root.GenBashCompletionV2(&canonical, true)
+			case "zsh":
+				_, err = canonical.WriteString(hook.ZshCompletionScript)
+			case "fish":
+				err = root.GenFishCompletion(&canonical, true)
+			}
+			if err != nil {
+				t.Fatal(err)
+			}
+			if err := os.WriteFile(filepath.Join(fixtures, shell), canonical.Bytes(), 0o644); err != nil {
+				t.Fatal(err)
+			}
+			// Exercise Cobra's actual generated shell code with a deterministic backend.
+			backend := `#!/bin/bash
+case "$1" in
+ completion) cat "$COMPLETION_FIXTURES/$2" ;;
+ __complete|__completeNoDesc) printf 'server01\n:4\n' ;;
+ *) exit 1 ;;
+esac
+`
+			if err := os.WriteFile(filepath.Join(fixtures, "netssh"), []byte(backend), 0o755); err != nil {
+				t.Fatal(err)
+			}
+			t.Setenv("COMPLETION_FIXTURES", fixtures)
+			t.Setenv("ALIAS_COMPLETION", paths[shell])
+			t.Setenv("PATH", fixtures+string(os.PathListSeparator)+os.Getenv("PATH"))
+			var script string
+			var args []string
+			switch shell {
+			case "bash":
+				library := ""
+				for _, path := range []string{"/usr/share/bash-completion/bash_completion", "/etc/bash_completion"} {
+					if _, err := os.Stat(path); err == nil {
+						library = path
+						break
+					}
+				}
+				if library == "" {
+					t.Skip("bash-completion unavailable")
+				}
+				t.Setenv("BASH_COMPLETION_LIBRARY", library)
+				args = []string{"--noprofile", "--norc", "-c"}
+				script = `source "$BASH_COMPLETION_LIBRARY"
+shopt -s expand_aliases
+alias j=netssh
+_completion_loader j
+COMP_WORDS=(j ser)
+COMP_CWORD=1
+COMP_LINE='j ser'
+COMP_POINT=5
+COMP_TYPE=9
+COMP_KEY=9
+__start_netssh j ser j
+printf '%s\n' "${COMPREPLY[@]}"
+`
+			case "zsh":
+				args = []string{"-f", "-c"}
+				script = `fpath=("$HOME/.zfunc" $fpath)
+autoload -Uz compinit
+compinit -u -D
+alias j=netssh
+autoload -Uz _j
+# Capture matches without requiring an interactive ZLE completion widget.
+_describe() { print -rl -- "${(P)4}"; }
+compadd() { print -rl -- "$@"; }
+words=(j ser)
+CURRENT=2
+_j
+`
+			case "fish":
+				args = []string{"--no-config", "-c"}
+				script = `alias j netssh
+set -p fish_complete_path "$XDG_CONFIG_HOME/fish/completions"
+complete --do-complete 'j ser'
+`
+			}
+			cmd := exec.Command(executable, append(args, script)...)
+			out, err := cmd.CombinedOutput()
+			if err != nil || !strings.Contains(string(out), "server01") {
+				t.Fatalf("%s completion: %v\n%s", shell, err, out)
+			}
+		})
+	}
+}
+
+func TestZshCompletionSplitsHostsAndCommands(t *testing.T) {
+	zsh, err := exec.LookPath("zsh")
+	if err != nil {
+		t.Skip("zsh unavailable")
+	}
+	dir := t.TempDir()
+	backend := "#!/bin/sh\nprintf 'web01\\nweb:02\\ncache\\tManage the cache\\n:36\\n'\n"
+	if err := os.WriteFile(filepath.Join(dir, "netssh"), []byte(backend), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "_netssh"), []byte(hook.ZshCompletionScript), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	script := `compdef() { :; }
+source "$DIR/_netssh"
+_describe() { print -r -- "describe ${(P)4}"; }
+compadd() { print -r -- "compadd $*"; }
+_files() { print -r -- files; }
+words=(netssh "")
+CURRENT=2
+_netssh
+`
+	cmd := exec.Command(zsh, "-f", "-c", script)
+	cmd.Env = append(os.Environ(), "DIR="+dir, "PATH="+dir+string(os.PathListSeparator)+os.Getenv("PATH"))
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		t.Fatalf("%v\n%s", err, out)
+	}
+	// Directive 36 = NoFileComp|KeepOrder: unsorted host group, no file fallback.
+	want := "describe cache:Manage the cache\ncompadd -V hosts -X %Bhosts%b -M l:|=* -- web01 web:02\n"
+	if string(out) != want {
+		t.Fatalf("got:\n%s\nwant:\n%s", out, want)
+	}
+}

internal/hook/hook.go

@@ -4,12 +4,17 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"regexp"
 	"strings"
+
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/storage"
 )
 
 const (
 	// Marker is the unique string used to detect an existing hook line.
-	Marker = "netssh shell-init"
+	Marker     = "netssh shell-init"
+	BlockStart = "# >>> netssh >>>"
+	BlockEnd   = "# <<< netssh <<<"
 	// Line is the full line written into the shell profile.
 	Line = "netssh shell-init  # netssh cache auto-refresh"
 
@@ -25,13 +30,13 @@ func ProfilePath(shell string) (string, error) {
 	case "bash":
 		return filepath.Join(os.Getenv("HOME"), ".bashrc"), nil
 	case "zsh":
-		return filepath.Join(os.Getenv("HOME"), ".zshrc"), nil
-	case "fish":
-		configDir, err := os.UserConfigDir()
-		if err != nil {
-			configDir = filepath.Join(os.Getenv("HOME"), ".config")
+		dir := os.Getenv("ZDOTDIR")
+		if dir == "" {
+			dir = os.Getenv("HOME")
 		}
-		return filepath.Join(configDir, "fish", "config.fish"), nil
+		return filepath.Join(dir, ".zshrc"), nil
+	case "fish":
+		return filepath.Join(FishConfigDir(), "config.fish"), nil
 	default:
 		return "", fmt.Errorf("unsupported shell %q — supported: bash, zsh, fish", shell)
 	}
@@ -49,30 +54,71 @@ func IsInstalled(profilePath string) bool {
 	if err != nil {
 		return false
 	}
-	return strings.Contains(string(data), Marker)
+	for _, line := range strings.Split(string(data), "\n") {
+		if strings.TrimSpace(line) == BlockStart || hookLinePattern.MatchString(strings.TrimSpace(line)) {
+			return true
+		}
+	}
+	return false
 }
 
-// Install appends the hook line to the profile if it is not already present.
-// Returns (true, nil) when newly installed, (false, nil) when already present.
+// Install writes the managed netssh block into the profile. Entries written by
+// older versions without markers are replaced instead of duplicated; an
+// existing managed block (e.g. from install.sh) is left untouched.
+// Returns (true, nil) when the profile changed, (false, nil) when already present.
 // Creates the profile file (and any parent directories) if they do not exist.
-func Install(profilePath string) (installed bool, err error) {
-	if IsInstalled(profilePath) {
-		return false, nil
+func Install(profilePath, shell string) (installed bool, err error) {
+	data, err := os.ReadFile(profilePath)
+	if err != nil && !os.IsNotExist(err) {
+		return false, fmt.Errorf("reading profile: %w", err)
 	}
+	for _, line := range strings.Split(string(data), "\n") {
+		if strings.TrimSpace(line) == BlockStart {
+			return false, nil
+		}
+	}
+	cleaned, _, err := clean(string(data), profilePath)
+	if err != nil {
+		return false, err
+	}
+	if cleaned != "" && !strings.HasSuffix(cleaned, "\n") {
+		cleaned += "\n"
+	}
+	if cleaned != "" {
+		cleaned += "\n"
+	}
+	cleaned += Block(shell)
 	if err := os.MkdirAll(filepath.Dir(profilePath), 0o755); err != nil {
 		return false, fmt.Errorf("creating directory: %w", err)
 	}
-	f, err := os.OpenFile(profilePath, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644)
-	if err != nil {
-		return false, fmt.Errorf("opening profile: %w", err)
-	}
-	defer f.Close()
-	if _, err := fmt.Fprintf(f, "\n%s\n", Line); err != nil {
+	if err := writeProfile(profilePath, cleaned); err != nil {
 		return false, err
 	}
 	return true, nil
 }
 
+// Block returns the managed profile block for shell.
+func Block(shell string) string {
+	var b strings.Builder
+	b.WriteString(BlockStart + "\n")
+	b.WriteString("netssh shell-init\n")
+	if shell != "fish" {
+		aliases := shellQuote(AliasesPath(), "bash")
+		fmt.Fprintf(&b, "[ ! -f %s ] || . %s\n", aliases, aliases)
+	}
+	if shell == "zsh" {
+		b.WriteString(ZshRegistration(ZshFuncDir()))
+	}
+	b.WriteString(BlockEnd + "\n")
+	return b.String()
+}
+
+// ZshRegistration adds dir to fpath and registers the completion even when
+// compinit already ran earlier in .zshrc (e.g. via oh-my-zsh).
+func ZshRegistration(dir string) string {
+	return fmt.Sprintf("fpath=(%s $fpath)\nif (( $+functions[compdef] )); then autoload -Uz _netssh && compdef _netssh netssh; fi\n", shellQuote(dir, "bash"))
+}
+
 // InstallAliasesSource appends the aliases source line to a bash/zsh profile.
 // This is a no-op for fish (which uses conf.d auto-sourcing instead).
 // Returns (true, nil) when newly added, (false, nil) when already present.
@@ -81,23 +127,57 @@ func InstallAliasesSource(profilePath string) (installed bool, err error) {
 	if err != nil && !os.IsNotExist(err) {
 		return false, fmt.Errorf("reading profile: %w", err)
 	}
-	if strings.Contains(string(data), AliasesMarker) {
-		return false, nil
+	for _, line := range strings.Split(string(data), "\n") {
+		if strings.TrimSpace(line) == BlockStart || aliasesLinePattern.MatchString(strings.TrimSpace(line)) {
+			return false, nil
+		}
 	}
 	f, err := os.OpenFile(profilePath, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644)
 	if err != nil {
 		return false, fmt.Errorf("opening profile: %w", err)
 	}
 	defer f.Close()
-	if _, err := fmt.Fprintf(f, "%s\n", AliasesSourceLine); err != nil {
+	if _, err := fmt.Fprintf(f, "%s\n", "source "+shellQuote(AliasesPath(), "bash")+" 2>/dev/null  # netssh aliases"); err != nil {
 		return false, err
 	}
 	return true, nil
 }
 
-// Uninstall removes the hook line and the aliases source line from the profile.
-// Returns (true, nil) when something was removed, (false, nil) when nothing was found.
-// Returns (false, nil) — not an error — when the file does not exist.
+var hookLinePattern = regexp.MustCompile(`^(?:[^\s]*/)?netssh\s+shell-init\s*(?:#.*)?$`)
+var aliasesLinePattern = regexp.MustCompile(`^(?:source|\.)\s+["']?[^;|&]*netssh/aliases\.sh["']?(?:\s+2>/dev/null)?\s*(?:#.*)?$`)
+
+// legacyPatterns match the unmarked lines written by older versions and by
+// manual setup instructions. They mirror the patterns in install.sh.
+var legacyPatterns = []*regexp.Regexp{
+	hookLinePattern,
+	aliasesLinePattern,
+	regexp.MustCompile(`^eval\s+["']?\$\((?:[^\s]*/)?netssh\s+alias(?:\s+--shell\s+(?:bash|zsh))?\)["']?\s*(?:#.*)?$`),
+	regexp.MustCompile(`^(?:[^\s]*/)?netssh\s+alias(?:\s+--shell\s+fish)?\s*\|\s*source\s*(?:#.*)?$`),
+	regexp.MustCompile(`^source\s+<\((?:[^\s]*/)?netssh\s+alias\)\s*(?:#.*)?$`),
+	regexp.MustCompile(`^alias\s+[A-Za-z0-9_.-]+(?:=|\s+)["']netssh(?:\s+[^"']+)?["']\s*(?:#.*)?$`),
+}
+
+func isLegacyLine(line string) bool {
+	for _, pattern := range legacyPatterns {
+		if pattern.MatchString(line) {
+			return true
+		}
+	}
+	return false
+}
+
+// HasEntries reports whether the profile contains a managed block or legacy lines.
+func HasEntries(profilePath string) bool {
+	data, err := os.ReadFile(profilePath)
+	if err != nil {
+		return false
+	}
+	_, removed, err := clean(string(data), profilePath)
+	return removed || err != nil
+}
+
+// Uninstall removes legacy hook lines and complete installer-managed blocks.
+// Missing profiles are a no-op; malformed blocks leave the file unchanged.
 func Uninstall(profilePath string) (removed bool, err error) {
 	data, err := os.ReadFile(profilePath)
 	if os.IsNotExist(err) {
@@ -106,23 +186,95 @@ func Uninstall(profilePath string) (removed bool, err error) {
 	if err != nil {
 		return false, fmt.Errorf("reading profile: %w", err)
 	}
-	content := string(data)
-	if !strings.Contains(content, Marker) && !strings.Contains(content, AliasesMarker) {
-		return false, nil
+	cleaned, removed, err := clean(string(data), profilePath)
+	if err != nil || !removed {
+		return false, err
 	}
+	return true, writeProfile(profilePath, cleaned)
+}
 
+// clean strips managed blocks and legacy lines from profile content.
+func clean(data, profilePath string) (cleaned string, removed bool, err error) {
+	if data == "" {
+		return "", false, nil
+	}
 	var kept []string
-	for _, line := range strings.Split(content, "\n") {
-		if strings.Contains(line, Marker) || strings.Contains(line, AliasesMarker) {
+	inside := false
+	for _, line := range strings.Split(data, "\n") {
+		value := strings.TrimSpace(line)
+		switch value {
+		case BlockStart:
+			if inside {
+				return "", false, fmt.Errorf("nested netssh block in %s", profilePath)
+			}
+			inside = true
+			removed = true
+			continue
+		case BlockEnd:
+			if !inside {
+				return "", false, fmt.Errorf("unmatched netssh block in %s", profilePath)
+			}
+			inside = false
+			continue
+		}
+		if inside {
+			continue
+		}
+		if isLegacyLine(value) {
+			removed = true
 			continue
 		}
 		kept = append(kept, line)
 	}
-	// Collapse triple blank lines that the removal may leave.
-	cleaned := strings.ReplaceAll(strings.Join(kept, "\n"), "\n\n\n", "\n\n")
-
-	if err := os.WriteFile(profilePath, []byte(cleaned), 0o644); err != nil {
-		return false, fmt.Errorf("writing profile: %w", err)
+	if inside {
+		return "", false, fmt.Errorf("unclosed netssh block in %s", profilePath)
 	}
-	return true, nil
+	if !removed {
+		return data, false, nil
+	}
+	cleaned = strings.ReplaceAll(strings.Join(kept, "\n"), "\n\n\n", "\n\n")
+	// Drop the blank separator line Install puts in front of the block.
+	if strings.HasSuffix(cleaned, "\n\n") {
+		cleaned = strings.TrimRight(cleaned, "\n") + "\n"
+	}
+	return cleaned, true, nil
+}
+
+// writeProfile replaces the profile atomically, following dotfile symlinks
+// and keeping the permissions of an existing file.
+func writeProfile(profilePath, content string) error {
+	target, err := filepath.EvalSymlinks(profilePath)
+	if os.IsNotExist(err) {
+		target = profilePath
+	} else if err != nil {
+		return err
+	}
+	mode := os.FileMode(0o644)
+	if info, err := os.Stat(target); err == nil {
+		mode = info.Mode().Perm()
+	}
+	if err := storage.WriteFile(target, []byte(content), mode); err != nil {
+		return fmt.Errorf("writing profile: %w", err)
+	}
+	return nil
+}
+
+// ProfileCandidates lists every shell profile netssh or install.sh may have
+// written to, in the same order as the installer.
+func ProfileCandidates() []string {
+	home := os.Getenv("HOME")
+	zdot := zshDir()
+	paths := []string{
+		filepath.Join(home, ".bashrc"),
+		filepath.Join(home, ".bash_profile"),
+		filepath.Join(home, ".bash_login"),
+		filepath.Join(home, ".profile"),
+		filepath.Join(zdot, ".zshrc"),
+		filepath.Join(zdot, ".zprofile"),
+		filepath.Join(zdot, ".zshenv"),
+	}
+	if zdot != home {
+		paths = append(paths, filepath.Join(home, ".zshrc"), filepath.Join(home, ".zprofile"), filepath.Join(home, ".zshenv"))
+	}
+	return append(paths, filepath.Join(FishConfigDir(), "config.fish"))
 }

internal/hook/hook_test.go

@@ -2,6 +2,7 @@ package hook_test
 
 import (
 	"os"
+	"os/exec"
 	"path/filepath"
 	"strings"
 	"testing"
@@ -87,7 +88,7 @@ func TestIsInstalled_MissingFile(t *testing.T) {
 func TestInstall_Fresh(t *testing.T) {
 	profile := filepath.Join(t.TempDir(), ".bashrc")
 
-	installed, err := hook.Install(profile)
+	installed, err := hook.Install(profile, "bash")
 	if err != nil {
 		t.Fatalf("Install: %v", err)
 	}
@@ -102,8 +103,8 @@ func TestInstall_Fresh(t *testing.T) {
 func TestInstall_Idempotent(t *testing.T) {
 	profile := filepath.Join(t.TempDir(), ".bashrc")
 
-	hook.Install(profile)
-	installed, err := hook.Install(profile)
+	hook.Install(profile, "bash")
+	installed, err := hook.Install(profile, "bash")
 	if err != nil {
 		t.Fatalf("second Install: %v", err)
 	}
@@ -120,7 +121,7 @@ func TestInstall_Idempotent(t *testing.T) {
 func TestInstall_CreatesProfileAndParentDirs(t *testing.T) {
 	profile := filepath.Join(t.TempDir(), "nested", "dir", ".zshrc")
 
-	if _, err := hook.Install(profile); err != nil {
+	if _, err := hook.Install(profile, "bash"); err != nil {
 		t.Fatalf("Install should create missing directories: %v", err)
 	}
 	if _, err := os.Stat(profile); err != nil {
@@ -131,7 +132,7 @@ func TestInstall_CreatesProfileAndParentDirs(t *testing.T) {
 func TestInstall_PreservesExistingContent(t *testing.T) {
 	profile := writeProfile(t, "export PATH=$PATH:/usr/local/bin\n")
 
-	hook.Install(profile)
+	hook.Install(profile, "bash")
 
 	data, _ := os.ReadFile(profile)
 	content := string(data)
@@ -145,13 +146,13 @@ func TestInstall_PreservesExistingContent(t *testing.T) {
 
 func TestInstall_AppendedAtEnd(t *testing.T) {
 	profile := writeProfile(t, "existing line\n")
-	hook.Install(profile)
+	hook.Install(profile, "bash")
 
 	data, _ := os.ReadFile(profile)
 	lines := strings.Split(strings.TrimRight(string(data), "\n"), "\n")
 	last := lines[len(lines)-1]
-	if last != hook.Line {
-		t.Errorf("hook line should be the last line, got %q", last)
+	if last != hook.BlockEnd {
+		t.Errorf("managed block should end the profile, got %q", last)
 	}
 }
 
@@ -226,7 +227,7 @@ func TestUninstall_CollapsesExtraBlankLines(t *testing.T) {
 func TestInstallUninstall_Roundtrip(t *testing.T) {
 	profile := writeProfile(t, "existing content\n")
 
-	hook.Install(profile)
+	hook.Install(profile, "bash")
 	if !hook.IsInstalled(profile) {
 		t.Fatal("should be installed after Install")
 	}
@@ -261,3 +262,96 @@ func writeProfile(t *testing.T, content string) string {
 	}
 	return f
 }
+
+func TestManagedBlockInstallAndUninstall(t *testing.T) {
+	original := "export KEEP=yes\n# netssh shell-init documentation\necho 'netssh shell-init'\n"
+	profile := writeProfile(t, original+hook.BlockStart+"\nexport PATH='/custom/bin':\"$PATH\"\n'/custom/bin/netssh' shell-init\n[ ! -f '/custom/cache/netssh/aliases.sh' ] || . '/custom/cache/netssh/aliases.sh'\n"+hook.BlockEnd+"\n")
+	if installed, err := hook.Install(profile, "bash"); err != nil || installed {
+		t.Fatalf("duplicate install: %v, %v", installed, err)
+	}
+	if installed, err := hook.InstallAliasesSource(profile); err != nil || installed {
+		t.Fatalf("duplicate source: %v, %v", installed, err)
+	}
+	if removed, err := hook.Uninstall(profile); err != nil || !removed {
+		t.Fatalf("uninstall: %v, %v", removed, err)
+	}
+	data, _ := os.ReadFile(profile)
+	if string(data) != original {
+		t.Fatalf("unrelated content changed: %s", data)
+	}
+}
+
+func TestProfilePathRespectsZdotdir(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("ZDOTDIR", dir)
+	path, err := hook.ProfilePath("zsh")
+	if err != nil || path != filepath.Join(dir, ".zshrc") {
+		t.Fatalf("zsh path: %s, %v", path, err)
+	}
+}
+
+func TestInstallReplacesLegacyEntriesWithBlock(t *testing.T) {
+	t.Setenv("XDG_CACHE_HOME", t.TempDir())
+	profile := writeProfile(t, "export KEEP=yes\nnetssh shell-init\nsource ~/.cache/netssh/aliases.sh 2>/dev/null\neval \"$(netssh alias)\"\nalias j='netssh'\necho 'netssh shell-init'\n")
+	installed, err := hook.Install(profile, "zsh")
+	if err != nil || !installed {
+		t.Fatalf("install: %v, %v", installed, err)
+	}
+	data, _ := os.ReadFile(profile)
+	content := string(data)
+	for _, gone := range []string{"\nnetssh shell-init\nsource", "eval ", "alias j="} {
+		if strings.Contains(content, gone) {
+			t.Fatalf("legacy entry %q kept:\n%s", gone, content)
+		}
+	}
+	for _, kept := range []string{"export KEEP=yes", "echo 'netssh shell-init'", hook.BlockStart, "compdef _netssh netssh", "fpath=("} {
+		if !strings.Contains(content, kept) {
+			t.Fatalf("missing %q:\n%s", kept, content)
+		}
+	}
+	if strings.Count(content, hook.BlockStart) != 1 {
+		t.Fatalf("duplicate blocks:\n%s", content)
+	}
+	if removed, err := hook.Uninstall(profile); err != nil || !removed {
+		t.Fatalf("uninstall: %v, %v", removed, err)
+	}
+	data, _ = os.ReadFile(profile)
+	if string(data) != "export KEEP=yes\necho 'netssh shell-init'\n" {
+		t.Fatalf("unexpected remainder: %q", data)
+	}
+}
+
+func TestBlockPerShell(t *testing.T) {
+	if b := hook.Block("fish"); strings.Contains(b, "aliases.sh") || strings.Contains(b, "compdef") {
+		t.Fatalf("fish block: %s", b)
+	}
+	if b := hook.Block("bash"); !strings.Contains(b, "aliases.sh") || strings.Contains(b, "compdef") {
+		t.Fatalf("bash block: %s", b)
+	}
+}
+
+func TestZshBlockRegistersCompletionAfterCompinit(t *testing.T) {
+	zsh, err := exec.LookPath("zsh")
+	if err != nil {
+		t.Skip("zsh unavailable")
+	}
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+	t.Setenv("ZDOTDIR", home)
+	t.Setenv("XDG_CACHE_HOME", filepath.Join(home, "cache"))
+	if err := os.MkdirAll(hook.ZshFuncDir(), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(hook.ZshFuncDir(), "_netssh"), []byte(hook.ZshCompletionScript), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	// compinit runs before the block, as with oh-my-zsh.
+	rc := "autoload -Uz compinit && compinit -u -d \"$HOME/.zcompdump\"\nnetssh() { :; }\n" + hook.Block("zsh")
+	if err := os.WriteFile(filepath.Join(home, ".zshrc"), []byte(rc), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	out, err := exec.Command(zsh, "-i", "-c", `print -r -- $_comps[netssh]`).CombinedOutput()
+	if err != nil || !strings.Contains(string(out), "_netssh") {
+		t.Fatalf("completion not registered: %v\n%s", err, out)
+	}
+}

internal/hook/zsh.go

@@ -0,0 +1,100 @@
+package hook
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+)
+
+// ZshCompletionScript replaces Cobra's generated zsh completion. Cobra's script
+// spawns a subshell per candidate and passes every host through _describe,
+// which takes tens of seconds for thousands of hosts. This script splits the
+// candidates with parameter expansion only: entries with a description
+// (subcommands, flags) go through _describe, plain hostnames through compadd.
+//
+// The file works both from fpath (autoloaded as _netssh) and when sourced.
+const ZshCompletionScript = `#compdef netssh
+compdef _netssh netssh
+
+# netssh zsh completion — generated by netssh, do not edit.
+_netssh() {
+  local -a lines described plain
+  local out directive=0 entry ret=1
+  local -a nospace
+
+  out=$(netssh __complete "${(@)words[2,CURRENT]}" 2>/dev/null) || return 1
+  lines=("${(@f)out}")
+  if [[ ${lines[-1]} == :<-> ]]; then
+    directive=${lines[-1]#:}
+    lines[-1]=()
+  fi
+  # Directive 1: error.
+  (( directive & 1 )) && return 1
+  lines=(${lines:#_activeHelp_*})
+  lines=(${lines:#})
+  # Directive 2: no trailing space.
+  (( directive & 2 )) && nospace=(-S '')
+
+  # Directive 8: the lines are file extensions to filter by.
+  if (( directive & 8 )); then
+    local -a globs
+    for entry in $lines; do globs+=("*.${entry}"); done
+    _files -g "(${(j:|:)globs})"
+    return
+  fi
+  # Directive 16: complete directories only.
+  if (( directive & 16 )); then
+    _files -/
+    return
+  fi
+
+  described=(${(M)lines:#*$'\t'*})
+  plain=(${lines:#*$'\t'*})
+  if (( $#described )); then
+    local -a items
+    for entry in $described; do
+      items+=("${${entry%%$'\t'*}//:/\\:}:${entry#*$'\t'}")
+    done
+    _describe -t commands 'netssh command' items $nospace && ret=0
+  fi
+  if (( $#plain )); then
+    # netssh already filtered the hosts, also by the name after an instance
+    # prefix: "fsn1" offers "prod/fsn1-…". 'l:|=*' lets zsh accept text
+    # before the typed word instead of discarding these matches.
+    local -a group=(-J hosts)
+    # Directive 32: keep the order supplied by netssh.
+    (( directive & 32 )) && group=(-V hosts)
+    compadd $group -X '%Bhosts%b' -M 'l:|=*' $nospace -- $plain && ret=0
+  fi
+  # Directive 4: no file completion as a fallback.
+  if (( ! $#lines && ! (directive & 4) )); then
+    _files && ret=0
+  fi
+  return ret
+}
+
+if [ "$funcstack[1]" = "_netssh" ]; then
+  _netssh "$@"
+fi
+`
+
+// ZshCompletionNote tells the user how zsh picks up a completion file in dir.
+func ZshCompletionNote(dir string) string {
+	dump := filepath.Join(zshDir(), ".zcompdump")
+	return fmt.Sprintf(`zsh loads it from fpath. The netssh block in your .zshrc adds %s
+(netssh hook install). Otherwise add this before compinit:
+  fpath=(%s $fpath)
+Then refresh the completion cache: rm -f %s* && exec zsh`, dir, dir, dump)
+}
+
+func zshDir() string {
+	if dir := os.Getenv("ZDOTDIR"); dir != "" {
+		return dir
+	}
+	return os.Getenv("HOME")
+}
+
+// ZshFuncDir is the user directory netssh installs zsh completion files into.
+func ZshFuncDir() string {
+	return filepath.Join(os.Getenv("HOME"), ".zfunc")
+}

internal/netbox/client.go

@@ -15,6 +15,7 @@ import (
 )
 
 type Client struct {
+	sources      map[string]*Client
 	baseURL      string
 	token        string
 	tokenVersion int
@@ -38,6 +39,9 @@ func NewClient(baseURL, token string, tokenVersion int) *Client {
 // Search queries up to 50 devices and VMs in parallel and merges the results.
 // Use SearchOptions to restrict by kind or tag.
 func (c *Client) Search(ctx context.Context, query string, opts SearchOptions) ([]HostEntry, error) {
+	if c.sources != nil {
+		return c.searchSources(ctx, query, opts, false)
+	}
 	if opts.Kind != "" && opts.Kind != "device" && opts.Kind != "vm" {
 		return nil, fmt.Errorf("invalid host kind %q", opts.Kind)
 	}
@@ -95,6 +99,9 @@ func (c *Client) Search(ctx context.Context, query string, opts SearchOptions) (
 // SearchAll paginates through all matching devices and VMs, fetching every page.
 // Intended for cache refresh; use Search for interactive queries.
 func (c *Client) SearchAll(ctx context.Context, query string, opts SearchOptions) ([]HostEntry, error) {
+	if c.sources != nil {
+		return c.searchSources(ctx, query, opts, true)
+	}
 	if opts.Kind != "" && opts.Kind != "device" && opts.Kind != "vm" {
 		return nil, fmt.Errorf("invalid host kind %q", opts.Kind)
 	}
@@ -146,6 +153,13 @@ func (c *Client) SearchAll(ctx context.Context, query string, opts SearchOptions
 // GetIPs returns all IP addresses assigned to a host, used by resolver strategies
 // that need more than just the primary IP.
 func (c *Client) GetIPs(ctx context.Context, entry HostEntry) ([]string, error) {
+	if c.sources != nil {
+		source, host, err := c.sourceForHost(entry)
+		if err != nil {
+			return nil, err
+		}
+		return source.GetIPs(ctx, host)
+	}
 	var apiURL string
 	switch entry.Kind {
 	case "device":
@@ -170,6 +184,9 @@ func (c *Client) GetIPs(ctx context.Context, entry HostEntry) ([]string, error)
 
 // GetIPsWithFilter calls /api/ipam/ip-addresses/ with arbitrary filter query parameters.
 func (c *Client) GetIPsWithFilter(ctx context.Context, filterParams string) ([]string, error) {
+	if c.sources != nil {
+		return nil, fmt.Errorf("IP filters require a host instance; use GetIPsWithFilterForHost")
+	}
 	apiURL := fmt.Sprintf("%s/api/ipam/ip-addresses/?%s&limit=100", c.baseURL, filterParams)
 	var resp netboxIPListResponse
 	if err := c.get(ctx, apiURL, &resp); err != nil {
@@ -351,22 +368,32 @@ func stripPrefix(cidr string) string {
 	return cidr
 }
 
+// ErrHostNotFound distinguishes a missing exact match from API failures or ambiguity.
+var ErrHostNotFound = errors.New("host not found")
+
 // FindHost refuses ambiguous names so writes cannot target an arbitrary server.
 func (c *Client) FindHost(ctx context.Context, name, kind string) (HostEntry, error) {
 	if kind != "" && kind != "device" && kind != "vm" {
 		return HostEntry{}, fmt.Errorf("invalid kind %q", kind)
 	}
 	entries, err := c.SearchAll(ctx, name, SearchOptions{Kind: kind})
+	_, hostname := SplitTarget(name)
 	if err != nil {
 		return HostEntry{}, err
 	}
 	var matches []HostEntry
 	for _, e := range entries {
-		if strings.EqualFold(e.Name, name) {
+		if strings.EqualFold(e.Name, hostname) {
 			matches = append(matches, e)
 		}
 	}
+	if len(matches) == 0 {
+		return HostEntry{}, fmt.Errorf("%w: %q", ErrHostNotFound, name)
+	}
 	if len(matches) != 1 {
+		if c.sources != nil {
+			return HostEntry{}, fmt.Errorf("host %q: found %d exact matches; use instance/hostname and --kind to select a unique host", name, len(matches))
+		}
 		return HostEntry{}, fmt.Errorf("host %q: found %d exact matches; use --kind or a unique hostname", name, len(matches))
 	}
 	return matches[0], nil
@@ -389,6 +416,13 @@ func (c *Client) hostURL(host HostEntry) (string, error) {
 }
 
 func (c *Client) GetComments(ctx context.Context, host HostEntry) (string, string, error) {
+	if c.sources != nil {
+		source, host, err := c.sourceForHost(host)
+		if err != nil {
+			return "", "", err
+		}
+		return source.GetComments(ctx, host)
+	}
 	u, err := c.hostURL(host)
 	if err != nil {
 		return "", "", err
@@ -401,6 +435,13 @@ func (c *Client) GetComments(ctx context.Context, host HostEntry) (string, strin
 }
 
 func (c *Client) SetComments(ctx context.Context, host HostEntry, comments, etag string) error {
+	if c.sources != nil {
+		source, host, err := c.sourceForHost(host)
+		if err != nil {
+			return err
+		}
+		return source.SetComments(ctx, host, comments, etag)
+	}
 	u, err := c.hostURL(host)
 	if err != nil {
 		return err

internal/netbox/models.go

@@ -1,5 +1,7 @@
 package netbox
 
+import "strings"
+
 // SearchOptions filters a Search or SearchAll query.
 // Zero value means no filtering (return all kinds, no tag filter).
 type SearchOptions struct {
@@ -9,6 +11,7 @@ type SearchOptions struct {
 
 // HostEntry is a unified model for both devices and virtual machines from NetBox.
 type HostEntry struct {
+	Source     string // named NetBox instance; empty for the legacy single-instance config
 	ID         int
 	Name       string
 	Kind       string // "device" | "vm"
@@ -58,3 +61,19 @@ type netboxIPListResponse struct {
 		} `json:"assigned_object"`
 	} `json:"results"`
 }
+
+// Target returns an unambiguous selector for cache, completion, and SSH.
+func (h HostEntry) Target() string {
+	if h.Source == "" {
+		return h.Name
+	}
+	return h.Source + "/" + h.Name
+}
+
+// SplitTarget separates an optional instance prefix from a hostname.
+func SplitTarget(target string) (source, name string) {
+	if source, name, ok := strings.Cut(target, "/"); ok {
+		return strings.ToLower(source), name
+	}
+	return "", target
+}

internal/netbox/sources.go

@@ -0,0 +1,113 @@
+package netbox
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"sort"
+	"strings"
+	"sync"
+)
+
+// Source binds a name to its own API client and credentials.
+type Source struct {
+	Name         string
+	URL          string
+	Token        string
+	TokenVersion int
+}
+
+func NewMultiClient(sources []Source) *Client {
+	c := &Client{sources: make(map[string]*Client)}
+	for _, source := range sources {
+		c.sources[strings.ToLower(source.Name)] = NewClient(source.URL, source.Token, source.TokenVersion)
+	}
+	return c
+}
+
+func (c *Client) searchSources(ctx context.Context, query string, opts SearchOptions, all bool) ([]HostEntry, error) {
+	requested, query := SplitTarget(query)
+	if requested != "" {
+		if _, ok := c.sources[requested]; !ok {
+			return nil, fmt.Errorf("unknown NetBox instance %q", requested)
+		}
+	}
+	var mu sync.Mutex
+	var wg sync.WaitGroup
+	var entries []HostEntry
+	var errs []error
+	started := 0
+	for name, client := range c.sources {
+		if requested != "" && name != requested {
+			continue
+		}
+		started++
+		wg.Add(1)
+		go func(name string, client *Client) {
+			defer wg.Done()
+			var found []HostEntry
+			var err error
+			if all {
+				found, err = client.SearchAll(ctx, query, opts)
+			} else {
+				found, err = client.Search(ctx, query, opts)
+			}
+			mu.Lock()
+			defer mu.Unlock()
+			if err != nil {
+				errs = append(errs, fmt.Errorf("NetBox %s: %w", name, err))
+				return
+			}
+			for i := range found {
+				found[i].Source = name
+			}
+			entries = append(entries, found...)
+		}(name, client)
+	}
+	wg.Wait()
+	// Full lookups must see every source to rule out ambiguous hostnames.
+	if len(errs) > 0 && (all || len(errs) == started) {
+		return nil, errors.Join(errs...)
+	}
+	sort.Slice(entries, func(i, j int) bool { return entries[i].Target() < entries[j].Target() })
+	return entries, errors.Join(errs...)
+}
+
+func (c *Client) sourceForHost(host HostEntry) (*Client, HostEntry, error) {
+	prefix, name := SplitTarget(host.Name)
+	if prefix != "" {
+		if host.Source != "" && !strings.EqualFold(prefix, host.Source) {
+			return nil, host, fmt.Errorf("conflicting NetBox instance for %q", host.Name)
+		}
+		host.Source, host.Name = prefix, name
+	}
+	if c.sources == nil {
+		return c, host, nil
+	}
+	source, ok := c.sources[strings.ToLower(host.Source)]
+	if !ok {
+		return nil, host, fmt.Errorf("specify a configured NetBox instance as instance/hostname (got %q)", host.Target())
+	}
+	host.Source = strings.ToLower(host.Source)
+	return source, host, nil
+}
+
+// HostScope identifies a local note by its original NetBox URL and canonical
+// hostname, so renaming an instance does not move or mix its notes.
+func (c *Client) HostScope(host HostEntry) (HostEntry, string, error) {
+	source, host, err := c.sourceForHost(host)
+	if err != nil {
+		return host, "", err
+	}
+	return host, source.baseURL, nil
+}
+
+func (c *Client) GetIPsWithFilterForHost(ctx context.Context, host HostEntry, filters string) ([]string, error) {
+	source, _, err := c.sourceForHost(host)
+	if err != nil {
+		return nil, err
+	}
+	return source.GetIPsWithFilter(ctx, filters)
+}
+
+func (c *Client) MultipleSources() bool { return c.sources != nil }

internal/netbox/sources_test.go

@@ -0,0 +1,192 @@
+package netbox
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+func sourceTestServer(t *testing.T, token, ip, comment string) *httptest.Server {
+	t.Helper()
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if got := r.Header.Get("Authorization"); got != "Token "+token {
+			t.Errorf("credentials crossed sources: %q, want %q", got, token)
+			http.Error(w, "bad token", 401)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		switch r.URL.Path {
+		case "/api/dcim/devices/":
+			json.NewEncoder(w).Encode(deviceListResponse(netboxDevice{ID: 1, Name: "web", PrimaryIP4: &netboxIP{Address: ip + "/24"}}))
+		case "/api/virtualization/virtual-machines/":
+			json.NewEncoder(w).Encode(vmListResponse())
+		case "/api/ipam/ip-addresses/":
+			if r.URL.Query().Get("device_id") != "1" {
+				t.Errorf("wrong host ID: %s", r.URL.RawQuery)
+			}
+			json.NewEncoder(w).Encode(ipListResponse(ip + "/24"))
+		case "/api/dcim/devices/1/":
+			if r.Method == http.MethodPatch {
+				var data map[string]string
+				if err := json.NewDecoder(r.Body).Decode(&data); err != nil {
+					t.Error(err)
+				}
+				if data["comments"] != comment+" updated" {
+					t.Errorf("comment write crossed sources: %v", data)
+				}
+			}
+			json.NewEncoder(w).Encode(map[string]string{"comments": comment})
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	t.Cleanup(srv.Close)
+	return srv
+}
+
+func TestMultiSourceSearchAndRouting(t *testing.T) {
+	office := sourceTestServer(t, "office-token", "10.0.0.1", "office note")
+	lab := sourceTestServer(t, "lab-token", "10.0.0.2", "lab note")
+	c := NewMultiClient([]Source{{Name: "office", URL: office.URL, Token: "office-token"}, {Name: "lab", URL: lab.URL, Token: "lab-token"}})
+	ctx := context.Background()
+	entries, err := c.Search(ctx, "web", SearchOptions{})
+	if err != nil || len(entries) != 2 {
+		t.Fatalf("combined search: %+v, %v", entries, err)
+	}
+	if entries[0].Target() != "lab/web" || entries[1].Target() != "office/web" {
+		t.Fatalf("source lost: %+v", entries)
+	}
+	if _, err := c.FindHost(ctx, "web", ""); err == nil {
+		t.Fatal("ambiguous unqualified hostname accepted")
+	}
+	for _, tc := range []struct{ name, ip, note string }{{"office", "10.0.0.1", "office note"}, {"lab", "10.0.0.2", "lab note"}} {
+		t.Run(tc.name, func(t *testing.T) {
+			host, err := c.FindHost(ctx, tc.name+"/web", "")
+			if err != nil {
+				t.Fatal(err)
+			}
+			if host.Source != tc.name || host.Name != "web" || host.ID != 1 {
+				t.Fatalf("wrong host identity: %+v", host)
+			}
+			ips, err := c.GetIPs(ctx, host)
+			if err != nil || len(ips) != 1 || ips[0] != tc.ip {
+				t.Fatalf("wrong IP source: %v, %v", ips, err)
+			}
+			ips, err = c.GetIPsWithFilterForHost(ctx, host, "device_id=1&interface_name=mgmt0")
+			if err != nil || len(ips) != 1 || ips[0] != tc.ip {
+				t.Fatalf("wrong interface source: %v, %v", ips, err)
+			}
+			text, _, err := c.GetComments(ctx, host)
+			if err != nil || text != tc.note {
+				t.Fatalf("wrong comment source: %q, %v", text, err)
+			}
+			// TUI cache items carry a qualified name rather than a separate source.
+			qualified := HostEntry{Name: tc.name + "/web", ID: 1, Kind: "device"}
+			if err := c.SetComments(ctx, qualified, tc.note+" updated", ""); err != nil {
+				t.Fatal(err)
+			}
+		})
+	}
+	if _, err := c.Search(ctx, "missing/web", SearchOptions{}); err == nil {
+		t.Fatal("unknown source accepted")
+	}
+	if _, _, err := c.HostScope(HostEntry{Name: "web", Kind: "device"}); err == nil {
+		t.Fatal("unqualified note namespace accepted")
+	}
+	if _, err := c.GetIPsWithFilter(ctx, "device_id=1"); err == nil {
+		t.Fatal("IP filter without instance accepted")
+	}
+}
+
+func TestMultiSourceSearchRunsConcurrently(t *testing.T) {
+	var wg sync.WaitGroup
+	wg.Add(2)
+	makeServer := func() *httptest.Server {
+		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			wg.Done()
+			both := make(chan struct{})
+			go func() { wg.Wait(); close(both) }()
+			select {
+			case <-both:
+				fmt.Fprint(w, `{"count":0,"results":[]}`)
+			case <-r.Context().Done():
+			}
+		}))
+		t.Cleanup(srv.Close)
+		return srv
+	}
+	a, b := makeServer(), makeServer()
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+	defer cancel()
+	c := NewMultiClient([]Source{{Name: "a", URL: a.URL}, {Name: "b", URL: b.URL}})
+	if _, err := c.Search(ctx, "web", SearchOptions{Kind: "device"}); err != nil {
+		t.Fatalf("sources did not run concurrently: %v", err)
+	}
+}
+
+func TestMultiSourcePartialFailure(t *testing.T) {
+	good := sourceTestServer(t, "good-token", "10.0.0.1", "note")
+	failed := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { http.Error(w, "unavailable", 503) }))
+	defer failed.Close()
+	c := NewMultiClient([]Source{{Name: "good", URL: good.URL, Token: "good-token"}, {Name: "offline", URL: failed.URL}})
+	ctx := context.Background()
+	entries, err := c.Search(ctx, "web", SearchOptions{})
+	if len(entries) != 1 || err == nil || !strings.Contains(err.Error(), "offline") {
+		t.Fatalf("partial search lost results or warning: %+v, %v", entries, err)
+	}
+	if _, err := c.SearchAll(ctx, "web", SearchOptions{}); err == nil {
+		t.Fatal("incomplete full search succeeded")
+	}
+	if _, err := c.FindHost(ctx, "web", ""); err == nil {
+		t.Fatal("incomplete search claimed unique host")
+	}
+	if host, err := c.FindHost(ctx, "good/web", ""); err != nil || host.Source != "good" {
+		t.Fatalf("qualified lookup blocked by unrelated outage: %+v, %v", host, err)
+	}
+}
+
+func TestMultiSourceKeepsIndependentDeviceAndVMInventories(t *testing.T) {
+	office := newTestServer(t, map[string]any{
+		"/api/dcim/devices/":                    deviceListResponse(netboxDevice{ID: 1, Name: "office-router", PrimaryIP4: &netboxIP{Address: "10.1.0.1/24"}}),
+		"/api/virtualization/virtual-machines/": vmListResponse(netboxVM{ID: 2, Name: "office-vm", PrimaryIP4: &netboxIP{Address: "10.1.0.2/24"}}),
+	})
+	defer office.Close()
+	lab := newTestServer(t, map[string]any{
+		"/api/dcim/devices/":                    deviceListResponse(netboxDevice{ID: 1, Name: "lab-switch", PrimaryIP4: &netboxIP{Address: "10.2.0.1/24"}}),
+		"/api/virtualization/virtual-machines/": vmListResponse(netboxVM{ID: 2, Name: "lab-vm", PrimaryIP4: &netboxIP{Address: "10.2.0.2/24"}}),
+	})
+	defer lab.Close()
+	client := NewMultiClient([]Source{{Name: "office", URL: office.URL}, {Name: "lab", URL: lab.URL}})
+	entries, err := client.SearchAll(context.Background(), "", SearchOptions{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := map[string]string{"office/office-router": "device", "office/office-vm": "vm", "lab/lab-switch": "device", "lab/lab-vm": "vm"}
+	if len(entries) != len(want) {
+		t.Fatalf("independent inventories missing: %+v", entries)
+	}
+	for _, entry := range entries {
+		if want[entry.Target()] != entry.Kind {
+			t.Fatalf("inventory crossed source or kind: %+v", entry)
+		}
+	}
+	vms, err := client.Search(context.Background(), "", SearchOptions{Kind: "vm"})
+	if err != nil || len(vms) != 2 {
+		t.Fatalf("VM filter across instances: %+v, %v", vms, err)
+	}
+	for _, host := range vms {
+		if host.Kind != "vm" {
+			t.Fatalf("device leaked into VM filter: %+v", host)
+		}
+	}
+	host, err := client.FindHost(context.Background(), "lab/lab-vm", "vm")
+	if err != nil || host.Source != "lab" || host.ID != 2 || host.PrimaryIP4 != "10.2.0.2" {
+		t.Fatalf("wrong VM selected: %+v, %v", host, err)
+	}
+}

internal/notes/notes.go

@@ -52,7 +52,11 @@ func (s *Service) Read(ctx context.Context, host netbox.HostEntry, remote bool)
 		note.Text, note.ETag, err = s.Client.GetComments(ctx, note.Host)
 		return note, err
 	}
-	data, err := os.ReadFile(s.path(host))
+	path, err := s.localPath(host)
+	if err != nil {
+		return note, err
+	}
+	data, err := os.ReadFile(path)
 	if os.IsNotExist(err) {
 		return note, nil
 	}
@@ -67,5 +71,22 @@ func (s *Service) Write(ctx context.Context, note Note, remote bool) error {
 		}
 		return s.Client.SetComments(ctx, note.Host, note.Text, note.ETag)
 	}
-	return storage.WriteFile(s.path(note.Host), []byte(note.Text), 0o600)
+	path, err := s.localPath(note.Host)
+	if err != nil {
+		return err
+	}
+	return storage.WriteFile(path, []byte(note.Text), 0o600)
+}
+
+func (s *Service) localPath(host netbox.HostEntry) (string, error) {
+	if s.Client == nil {
+		return s.path(host), nil
+	}
+	host, namespace, err := s.Client.HostScope(host)
+	if err != nil {
+		return "", err
+	}
+	scoped := *s
+	scoped.Namespace = namespace
+	return scoped.path(host), nil
 }

internal/notes/notes_test.go

@@ -11,7 +11,7 @@ func TestLocalNotesPersistAndStayIsolated(t *testing.T) {
 	ctx := context.Background()
 	s := &Service{Dir: t.TempDir(), Namespace: "https://netbox.example"}
 	host := netbox.HostEntry{Name: "web01", Kind: "device"}
-	n := Note{Host: host, Text: "Wartung\nGrüße 🔧"}
+	n := Note{Host: host, Text: "Maintenance\nReady 🔧"}
 	if err := s.Write(ctx, n, false); err != nil {
 		t.Fatal(err)
 	}
@@ -50,3 +50,35 @@ func TestUnreadableNoteIsNotTreatedAsEmpty(t *testing.T) {
 		t.Fatal("expected read error")
 	}
 }
+
+func TestLocalNotesSeparateInstancesAndSurviveRename(t *testing.T) {
+	ctx := context.Background()
+	client := netbox.NewMultiClient([]netbox.Source{{Name: "office", URL: "https://office.example"}, {Name: "lab", URL: "https://lab.example"}})
+	service := &Service{Dir: t.TempDir(), Client: client}
+	for _, source := range []string{"office", "lab"} {
+		note := Note{Host: netbox.HostEntry{Name: source + "/web", Kind: "device"}, Text: source + " private note"}
+		if err := service.Write(ctx, note, false); err != nil {
+			t.Fatal(err)
+		}
+	}
+	for _, source := range []string{"office", "lab"} {
+		note, err := service.Read(ctx, netbox.HostEntry{Name: source + "/web", Kind: "device"}, false)
+		if err != nil || note.Text != source+" private note" {
+			t.Fatalf("notes crossed instances: %+v, %v", note, err)
+		}
+	}
+	service.Client = netbox.NewMultiClient([]netbox.Source{{Name: "renamed", URL: "https://office.example"}})
+	note, err := service.Read(ctx, netbox.HostEntry{Name: "renamed/web", Kind: "device"}, false)
+	if err != nil || note.Text != "office private note" {
+		t.Fatalf("renaming source lost note: %+v, %v", note, err)
+	}
+	// This is also the namespace used before migrating a legacy single NetBox.
+	legacy := &Service{Dir: service.Dir, Namespace: "https://office.example"}
+	note, err = legacy.Read(ctx, netbox.HostEntry{Name: "web", Kind: "device"}, false)
+	if err != nil || note.Text != "office private note" {
+		t.Fatalf("legacy note namespace changed: %+v, %v", note, err)
+	}
+	if err := service.Write(ctx, Note{Host: netbox.HostEntry{Name: "web", Kind: "device"}}, false); err == nil {
+		t.Fatal("unqualified notes accepted for multiple sources")
+	}
+}

internal/resolver/instances_test.go

@@ -0,0 +1,43 @@
+package resolver
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/netbox"
+)
+
+func TestVMResolversStayWithinTheirNetBoxInstance(t *testing.T) {
+	sources := make([]netbox.Source, 0, 2)
+	for i, name := range []string{"office", "lab"} {
+		ip := fmt.Sprintf("10.0.0.%d", i+1)
+		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			if r.URL.Query().Get("virtual_machine_id") != "7" {
+				t.Errorf("wrong VM filter: %s", r.URL.RawQuery)
+			}
+			if r.Header.Get("Authorization") != "Token "+name {
+				t.Error("VM lookup used another instance's credentials")
+			}
+			fmt.Fprintf(w, `{"count":1,"results":[{"address":%q}]}`, ip+"/24")
+		}))
+		t.Cleanup(srv.Close)
+		sources = append(sources, netbox.Source{Name: name, URL: srv.URL, Token: name})
+	}
+	client := netbox.NewMultiClient(sources)
+	management, err := NewManagementSubnetStrategy([]string{"10.0.0.0/8"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	for i, source := range sources {
+		host := &netbox.HostEntry{Source: source.Name, Name: "vm", Kind: "vm", ID: 7}
+		for _, strategy := range []Strategy{management, &InterfaceNameStrategy{name: "mgmt0"}} {
+			ip, err := strategy.Resolve(context.Background(), host, client)
+			if want := fmt.Sprintf("10.0.0.%d", i+1); err != nil || ip != want {
+				t.Fatalf("%s VM resolved through wrong instance: %q, %v", strategy.Name(), ip, err)
+			}
+		}
+	}
+}

internal/resolver/interface_name.go

@@ -27,7 +27,7 @@ func (s *InterfaceNameStrategy) Resolve(ctx context.Context, entry *netbox.HostE
 		return "", fmt.Errorf("unknown kind %q", entry.Kind)
 	}
 
-	ips, err := client.GetIPsWithFilter(ctx, filterParam)
+	ips, err := client.GetIPsWithFilterForHost(ctx, *entry, filterParam)
 	if err != nil {
 		return "", fmt.Errorf("fetching IPs for interface %q: %w", s.name, err)
 	}

internal/setup/instances.go

@@ -0,0 +1,112 @@
+package setup
+
+import (
+	"fmt"
+	"os"
+	"strings"
+
+	"charm.land/huh/v2"
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/config"
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/netbox"
+)
+
+// configureInstances edits a copy; nothing is written until the whole wizard succeeds.
+func configureInstances(cfg *config.Config) ([]config.NetBoxConfig, error) {
+	sources := append([]config.NetBoxConfig(nil), cfg.NetBoxes...)
+	if len(sources) == 0 && cfg.NetBox.URL != "" {
+		source := cfg.NetBox
+		source.Name = "default"
+		sources = append(sources, source)
+	}
+	for {
+		if len(sources) == 0 {
+			source, err := editInstance(config.NetBoxConfig{Name: "default"}, sources, "")
+			if err != nil {
+				return nil, err
+			}
+			sources = append(sources, source)
+		}
+		action := "done"
+		var options []huh.Option[string]
+		for _, source := range sources {
+			options = append(options, huh.NewOption("Edit "+source.Name+" ("+source.URL+")", "edit:"+source.Name))
+			options = append(options, huh.NewOption("Remove "+source.Name, "remove:"+source.Name))
+		}
+		options = append(options, huh.NewOption("Add another NetBox", "add"), huh.NewOption("Continue with these instances", "done"))
+		err := huh.NewForm(huh.NewGroup(huh.NewSelect[string]().Title("NetBox instances").Description("All configured instances are searched together.").Options(options...).Value(&action))).Run()
+		if err != nil {
+			return nil, err
+		}
+		if action == "done" {
+			return sources, nil
+		}
+		if action == "add" {
+			source, err := editInstance(config.NetBoxConfig{}, sources, "")
+			if err != nil {
+				return nil, err
+			}
+			sources = append(sources, source)
+			continue
+		}
+		verb, name, _ := strings.Cut(action, ":")
+		for i, source := range sources {
+			if source.Name != name {
+				continue
+			}
+			if verb == "edit" {
+				edited, err := editInstance(source, sources, name)
+				if err != nil {
+					return nil, err
+				}
+				sources[i] = edited
+			} else {
+				remove := false
+				if err := huh.NewConfirm().Title("Remove " + name + "?").Value(&remove).Run(); err != nil {
+					return nil, err
+				}
+				if remove {
+					sources = append(sources[:i], sources[i+1:]...)
+				}
+			}
+			break
+		}
+	}
+}
+
+func editInstance(source config.NetBoxConfig, sources []config.NetBoxConfig, original string) (config.NetBoxConfig, error) {
+	err := huh.NewForm(huh.NewGroup(
+		huh.NewInput().Title("Instance name").Description("Used in selectors such as office/web01.").Value(&source.Name).Validate(func(name string) error {
+			name = strings.ToLower(strings.TrimSpace(name))
+			candidate := config.Config{NetBoxes: []config.NetBoxConfig{{Name: name, URL: "https://example.invalid"}}}
+			if err := candidate.ValidateNetBoxes(); err != nil {
+				return err
+			}
+			for _, existing := range sources {
+				if strings.EqualFold(existing.Name, name) && !strings.EqualFold(existing.Name, original) {
+					return fmt.Errorf("instance name %q is already used", name)
+				}
+			}
+			return nil
+		}),
+		huh.NewInput().Title("NetBox URL").Placeholder("https://netbox.example.com").Value(&source.URL).Validate(func(value string) error {
+			return (&config.Config{NetBoxes: []config.NetBoxConfig{{Name: "instance", URL: strings.TrimSpace(value)}}}).ValidateNetBoxes()
+		}),
+		huh.NewInput().Title("NetBox API token").EchoMode(huh.EchoModePassword).Value(&source.Token).Validate(func(value string) error {
+			if strings.TrimSpace(value) == "" {
+				return fmt.Errorf("required")
+			}
+			return nil
+		}),
+	).Title("NetBox connection")).Run()
+	if err != nil {
+		return source, err
+	}
+	source.Name = strings.ToLower(strings.TrimSpace(source.Name))
+	source.URL = strings.TrimRight(strings.TrimSpace(source.URL), "/")
+	source.Token = strings.TrimSpace(source.Token)
+	source.TokenVersion = netbox.TokenVersion(source.Token)
+	if source.TokenVersion == 1 {
+		fmt.Fprintf(os.Stderr, "Note: NetBox %s uses a legacy v1 token. A v2 token starts with nbt_.\n", source.Name)
+	}
+	return source, nil
+}

internal/setup/wizard.go

@@ -5,20 +5,29 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"sort"
 	"strconv"
 	"strings"
 
-	"github.com/charmbracelet/huh"
+	"charm.land/huh/v2"
 
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/cache"
 	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/config"
-	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/netbox"
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/hook"
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/storage"
 )
 
 // RunWizard runs the interactive setup form, pre-filled with any existing cfg values.
 // It saves the result to the config file on success.
 func RunWizard(cfg *config.Config) error {
-	url := cfg.NetBox.URL
-	token := cfg.NetBox.Token
+	sources, err := configureInstances(cfg)
+	if err != nil {
+		if errors.Is(err, huh.ErrUserAborted) {
+			fmt.Fprintln(os.Stderr, "Setup cancelled.")
+			os.Exit(0)
+		}
+		return err
+	}
 	defaultUser := cfg.SSH.DefaultUser
 	defaultPort := ""
 	if cfg.SSH.DefaultPort > 0 {
@@ -30,6 +39,7 @@ func RunWizard(cfg *config.Config) error {
 	cacheTTL := strconv.Itoa(cfg.Cache.TTL)
 	shortcutDomains := strings.Join(cfg.Shortcuts.Domains, ", ")
 	stripHyphens := cfg.Shortcuts.StripHyphens
+	commandAlias := cfg.Shell.Alias
 
 	if strategiesRaw == "" {
 		strategiesRaw = "primary_ip"
@@ -39,30 +49,6 @@ func RunWizard(cfg *config.Config) error {
 	}
 
 	form := huh.NewForm(
-		huh.NewGroup(
-			huh.NewInput().
-				Title("NetBox URL").
-				Description("e.g. https://netbox.example.com").
-				Placeholder("https://").
-				Value(&url).
-				Validate(func(s string) error {
-					if strings.TrimSpace(s) == "" {
-						return errors.New("required")
-					}
-					return nil
-				}),
-			huh.NewInput().
-				Title("NetBox API token").
-				EchoMode(huh.EchoModePassword).
-				Value(&token).
-				Validate(func(s string) error {
-					if strings.TrimSpace(s) == "" {
-						return errors.New("required")
-					}
-					return nil
-				}),
-		).Title("NetBox connection"),
-
 		huh.NewGroup(
 			huh.NewInput().
 				Title("Default SSH user").
@@ -122,6 +108,12 @@ func RunWizard(cfg *config.Config) error {
 				Title("Strip hyphens").
 				Description("When enabled, fsn1-web01.example.com can be accessed as fsn1web01.\nOnly works for hosts already in the cache.").
 				Value(&stripHyphens),
+			huh.NewInput().
+				Title("Command alias").
+				Description("Optional alias for netssh itself, e.g. j. Leave empty to disable.").
+				Placeholder("j").
+				Value(&commandAlias).
+				Validate(func(s string) error { return config.ValidateCommandAlias(strings.TrimSpace(s)) }),
 		).Title("Shortcuts"),
 	)
 
@@ -134,11 +126,6 @@ func RunWizard(cfg *config.Config) error {
 	}
 
 	strategies := parseStrategies(strategiesRaw)
-	tokenVersion := netbox.TokenVersion(token)
-	if tokenVersion == 1 {
-		fmt.Fprintln(os.Stderr, "\nHinweis: Du verwendest einen Legacy-Token (v1). Erstelle in NetBox einen v2-Token (beginnt mit nbt_) für bessere Kompatibilität.")
-		fmt.Fprintln(os.Stderr, "  NetBox → Admin → API Tokens → Add Token")
-	}
 
 	ttl, _ := strconv.Atoi(cacheTTL)
 
@@ -165,11 +152,8 @@ func RunWizard(cfg *config.Config) error {
 	}
 
 	out := config.Config{
-		NetBox: config.NetBoxConfig{
-			URL:          strings.TrimRight(strings.TrimSpace(url), "/"),
-			Token:        strings.TrimSpace(token),
-			TokenVersion: tokenVersion,
-		},
+		Shell:    config.ShellConfig{Alias: strings.TrimSpace(commandAlias)},
+		NetBoxes: sources,
 		SSH: config.SSHConfig{
 			DefaultUser: strings.TrimSpace(defaultUser),
 			DefaultPort: port,
@@ -180,7 +164,8 @@ func RunWizard(cfg *config.Config) error {
 			InterfaceName:     strings.TrimSpace(interfaceName),
 		},
 		Cache: config.CacheConfig{
-			TTL: ttl,
+			TTL:  ttl,
+			Path: cfg.Cache.Path,
 		},
 		Shortcuts: config.ShortcutsConfig{
 			Domains:      domainList,
@@ -188,7 +173,33 @@ func RunWizard(cfg *config.Config) error {
 		},
 	}
 
-	return save(out)
+	if err := save(out); err != nil {
+		return err
+	}
+	loaded, err := config.Load()
+	if err != nil {
+		return err
+	}
+	c := cache.New(loaded.CachePath(), loaded.Cache.TTL)
+	if err := c.Load(); err != nil {
+		return fmt.Errorf("updating aliases: %w", err)
+	}
+	if err := hook.WriteAliasFiles(hook.BuildAliasEntries(c.All(), *loaded)); err != nil {
+		return err
+	}
+	if loaded.Shell.Alias != "" {
+		shell := filepath.Base(os.Getenv("SHELL"))
+		profile, err := hook.ProfilePath(shell)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "Run 'netssh hook install --shell bash|zsh|fish' to activate your alias.\n")
+			return nil
+		}
+		if _, err := hook.Install(profile, shell); err != nil {
+			return err
+		}
+		fmt.Fprintln(os.Stderr, hook.ReloadNote(profile))
+	}
+	return nil
 }
 
 var knownStrategies = map[string]bool{
@@ -220,16 +231,35 @@ func parseStrategies(s string) []string {
 }
 
 func save(cfg config.Config) error {
+	if err := config.ValidateCommandAlias(cfg.Shell.Alias); err != nil {
+		return err
+	}
+	if err := cfg.ValidateNetBoxes(); err != nil {
+		return err
+	}
 	path := config.Path()
 	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
 		return fmt.Errorf("creating config dir: %w", err)
 	}
 
 	var b strings.Builder
-	b.WriteString("netbox:\n")
-	b.WriteString(fmt.Sprintf("  url: %q\n", cfg.NetBox.URL))
-	b.WriteString(fmt.Sprintf("  token: %q\n", cfg.NetBox.Token))
-	fmt.Fprintf(&b, "  token_version: %d\n", cfg.NetBox.TokenVersion)
+	if len(cfg.NetBoxes) > 0 {
+		b.WriteString("netboxes:\n")
+		for _, source := range cfg.NetBoxes {
+			fmt.Fprintf(&b, "  - name: %q\n    url: %q\n    token: %q\n    token_version: %d\n", source.Name, source.URL, source.Token, source.TokenVersion)
+			if !sshOptionsEmpty(source.SSH) {
+				b.WriteString("    ssh:\n")
+				writeSSHOptions(&b, "      ", source.SSH)
+			}
+		}
+	} else {
+		b.WriteString("netbox:\n")
+		fmt.Fprintf(&b, "  url: %q\n  token: %q\n  token_version: %d\n", cfg.NetBox.URL, cfg.NetBox.Token, cfg.NetBox.TokenVersion)
+		if !sshOptionsEmpty(cfg.NetBox.SSH) {
+			b.WriteString("  ssh:\n")
+			writeSSHOptions(&b, "    ", cfg.NetBox.SSH)
+		}
+	}
 
 	b.WriteString("\nresolver:\n")
 	b.WriteString("  strategies:\n")
@@ -248,6 +278,9 @@ func save(cfg config.Config) error {
 
 	b.WriteString("\ncache:\n")
 	fmt.Fprintf(&b, "  ttl: %d\n", cfg.Cache.TTL)
+	if cfg.Cache.Path != "" {
+		fmt.Fprintf(&b, "  path: %q\n", cfg.Cache.Path)
+	}
 
 	b.WriteString("\nssh:\n")
 	if cfg.SSH.DefaultUser != "" {
@@ -256,6 +289,23 @@ func save(cfg config.Config) error {
 	if cfg.SSH.DefaultPort > 0 {
 		fmt.Fprintf(&b, "  default_port: %d\n", cfg.SSH.DefaultPort)
 	}
+	writeSSHOptions(&b, "  ", cfg.SSH.SSHOptions)
+	if len(cfg.SSH.Rules) > 0 {
+		b.WriteString("  rules:\n")
+		for _, rule := range cfg.SSH.Rules {
+			b.WriteString("    - match:\n")
+			for _, field := range [][2]string{{"tag", rule.Match.Tag}, {"instance", rule.Match.Instance}, {"kind", rule.Match.Kind}, {"name", rule.Match.Name}} {
+				if field[1] != "" {
+					fmt.Fprintf(&b, "        %s: %q\n", field[0], field[1])
+				}
+			}
+			writeSSHOptions(&b, "      ", rule.SSHOptions)
+		}
+	}
+
+	if cfg.Completion.MaxResults > 0 {
+		fmt.Fprintf(&b, "\ncompletion:\n  max_results: %d\n", cfg.Completion.MaxResults)
+	}
 
 	if len(cfg.Shortcuts.Domains) > 0 || cfg.Shortcuts.StripHyphens {
 		b.WriteString("\nshortcuts:\n")
@@ -270,10 +320,44 @@ func save(cfg config.Config) error {
 		}
 	}
 
-	if err := os.WriteFile(path, []byte(b.String()), 0o600); err != nil {
+	if cfg.Shell.Alias != "" {
+		fmt.Fprintf(&b, "\nshell:\n  alias: %q\n", cfg.Shell.Alias)
+	}
+
+	if err := storage.WriteFile(path, []byte(b.String()), 0o600); err != nil {
 		return fmt.Errorf("writing config: %w", err)
 	}
 
 	fmt.Printf("\nConfig saved → %s\n", path)
 	return nil
 }
+
+func sshOptionsEmpty(o config.SSHOptions) bool {
+	return o.ProxyJump == "" && o.HostKeyChecking == "" && o.Target == "" && o.AddressFamily == "" && len(o.ExtraArgs) == 0 && len(o.Options) == 0
+}
+
+// writeSSHOptions keeps settings the wizard does not ask for when it rewrites the config.
+func writeSSHOptions(b *strings.Builder, indent string, o config.SSHOptions) {
+	for _, field := range [][2]string{{"proxy_jump", o.ProxyJump}, {"host_key_checking", o.HostKeyChecking}, {"target", o.Target}, {"address_family", o.AddressFamily}} {
+		if field[1] != "" {
+			fmt.Fprintf(b, "%s%s: %q\n", indent, field[0], field[1])
+		}
+	}
+	if len(o.ExtraArgs) > 0 {
+		fmt.Fprintf(b, "%sextra_args:\n", indent)
+		for _, arg := range o.ExtraArgs {
+			fmt.Fprintf(b, "%s  - %q\n", indent, arg)
+		}
+	}
+	if len(o.Options) > 0 {
+		keys := make([]string, 0, len(o.Options))
+		for key := range o.Options {
+			keys = append(keys, key)
+		}
+		sort.Strings(keys)
+		fmt.Fprintf(b, "%soptions:\n", indent)
+		for _, key := range keys {
+			fmt.Fprintf(b, "%s  %s: %q\n", indent, key, o.Options[key])
+		}
+	}
+}

internal/setup/wizard_test.go

@@ -3,6 +3,7 @@ package setup
 import (
 	"os"
 	"path/filepath"
+	"reflect"
 	"strings"
 	"testing"
 
@@ -366,3 +367,91 @@ func TestSave_RoundtripViaLoad(t *testing.T) {
 		t.Errorf("TTL: got %d, want %d", loaded.Cache.TTL, original.Cache.TTL)
 	}
 }
+
+func TestSaveCommandAliasRoundtripAndDisable(t *testing.T) {
+	t.Setenv("XDG_CONFIG_HOME", t.TempDir())
+	cfg := config.Config{Shell: config.ShellConfig{Alias: "j"}, Cache: config.CacheConfig{Path: filepath.Join(t.TempDir(), "hosts.json")}}
+	if err := save(cfg); err != nil {
+		t.Fatal(err)
+	}
+	loaded, err := config.Load()
+	if err != nil || loaded.Shell.Alias != "j" || loaded.Cache.Path != cfg.Cache.Path {
+		t.Fatalf("roundtrip: %+v, %v", loaded, err)
+	}
+	cfg.Shell.Alias = ""
+	if err := save(cfg); err != nil {
+		t.Fatal(err)
+	}
+	loaded, err = config.Load()
+	if err != nil || loaded.Shell.Alias != "" {
+		t.Fatalf("disable: %+v, %v", loaded, err)
+	}
+}
+
+func TestSaveMultipleNetBoxesRoundTrip(t *testing.T) {
+	t.Setenv("XDG_CONFIG_HOME", t.TempDir())
+	cfg := config.Config{
+		NetBoxes: []config.NetBoxConfig{
+			{Name: "office", URL: "https://office.example/netbox", Token: "nbt_secret: office", TokenVersion: 2},
+			{Name: "lab", URL: "https://lab.example", Token: "legacy#token", TokenVersion: 1},
+		},
+		Resolver: config.ResolverConfig{Strategies: []string{"primary_ip"}},
+		Cache:    config.CacheConfig{TTL: 3600},
+	}
+	if err := save(cfg); err != nil {
+		t.Fatal(err)
+	}
+	loaded, err := config.Load()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(loaded.NetBoxes) != 2 || loaded.NetBox.URL != "" {
+		t.Fatalf("instances lost during save: %+v", loaded)
+	}
+	for i, want := range cfg.NetBoxes {
+		if !reflect.DeepEqual(loaded.NetBoxes[i], want) {
+			t.Fatalf("instance changed: %+v, want %+v", loaded.NetBoxes[i], want)
+		}
+	}
+	info, err := os.Stat(config.Path())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if info.Mode().Perm() != 0o600 {
+		t.Fatal("credentials are not private")
+	}
+}
+
+func TestSaveKeepsSSHOptions(t *testing.T) {
+	t.Setenv("XDG_CONFIG_HOME", t.TempDir())
+	t.Setenv("HOME", t.TempDir())
+	opts := config.SSHOptions{
+		ProxyJump:       "jh.example.com",
+		HostKeyChecking: "accept-new",
+		Target:          "name",
+		AddressFamily:   "inet",
+		ExtraArgs:       []string{"-A"},
+		Options:         map[string]string{"serveraliveinterval": "60"},
+	}
+	cfg := config.Config{
+		NetBoxes: []config.NetBoxConfig{{Name: "prod", URL: "https://prod.example", Token: "t", TokenVersion: 1, SSH: config.SSHOptions{HostKeyChecking: "off"}}},
+		Resolver: config.ResolverConfig{Strategies: []string{"primary_ip"}},
+		Cache:    config.CacheConfig{TTL: 3600},
+		SSH: config.SSHConfig{
+			DefaultUser: "root",
+			SSHOptions:  opts,
+			Rules:       []config.SSHRule{{Match: config.SSHMatch{Tag: "dmz", Name: "*.dmz"}, SSHOptions: config.SSHOptions{ProxyJump: "none"}}},
+		},
+		Completion: config.CompletionConfig{MaxResults: 100},
+	}
+	if err := save(cfg); err != nil {
+		t.Fatal(err)
+	}
+	loaded, err := config.Load()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !reflect.DeepEqual(loaded.SSH, cfg.SSH) || !reflect.DeepEqual(loaded.NetBoxes[0].SSH, cfg.NetBoxes[0].SSH) || loaded.Completion != cfg.Completion {
+		t.Fatalf("ssh settings lost:\n%+v\n%+v", loaded.SSH, loaded.NetBoxes[0].SSH)
+	}
+}

internal/shortcuts/shortcuts.go

@@ -38,5 +38,5 @@ func MakeNormalizer(cfg config.ShortcutsConfig) func(string) string {
 // replaces any remaining dots with underscores so the result is a valid identifier.
 func AliasName(name string, cfg config.ShortcutsConfig) string {
 	s := Normalize(name, cfg)
-	return strings.ReplaceAll(s, ".", "_")
+	return strings.NewReplacer(".", "_", "/", "_").Replace(s)
 }

internal/ssh/args.go

@@ -4,7 +4,7 @@ import "strings"
 
 // flagsWithArg lists all SSH flags that consume the following argument.
 var flagsWithArg = map[byte]bool{
-	'b': true, 'c': true, 'D': true, 'E': true, 'e': true,
+	'B': true, 'P': true, 'b': true, 'c': true, 'D': true, 'E': true, 'e': true,
 	'F': true, 'I': true, 'i': true, 'J': true, 'L': true,
 	'l': true, 'm': true, 'o': true, 'O': true, 'p': true,
 	'Q': true, 'R': true, 'S': true, 'w': true, 'W': true,
@@ -32,18 +32,16 @@ func Parse(args []string) *ParsedArgs {
 		}
 
 		if strings.HasPrefix(arg, "-") && len(arg) > 1 {
-			flag := arg[1]
-			if flagsWithArg[flag] {
-				if len(arg) > 2 {
-					// argument is attached, e.g. -p2222
-					i++
-				} else {
-					// argument is the next element, e.g. -p 2222
-					i += 2
+			// OpenSSH accepts clusters such as -vp 2222 and -vladmin.
+			for j := 1; j < len(arg); j++ {
+				if flagsWithArg[arg[j]] {
+					if j == len(arg)-1 {
+						i++
+					}
+					break
 				}
-			} else {
-				i++
 			}
+			i++
 			continue
 		}
 
@@ -86,35 +84,41 @@ func ReplaceHost(args []string, destIdx int, newHost string) []string {
 	return result
 }
 
-// HasPortFlag reports whether a port was specified via -p in args.
-func HasPortFlag(args []string) bool {
-	if parsed := Parse(args); parsed != nil {
-		args = args[:parsed.DestIdx]
-	}
-	for i, a := range args {
-		if a == "-p" && i+1 < len(args) {
-			return true
-		}
-		if len(a) > 2 && a[0] == '-' && a[1] == 'p' {
-			return true
-		}
-	}
-	return false
-}
+// HasPortFlag reports whether a port was explicitly supplied.
+func HasPortFlag(args []string) bool { return hasOption(args, 'p', "Port") }
 
-// HasUserFlag reports whether a user was specified via -l in args.
-// Used to avoid overriding an explicit -l with the configured default user.
-func HasUserFlag(args []string) bool {
-	if parsed := Parse(args); parsed != nil {
-		args = args[:parsed.DestIdx]
-	}
-	for i, a := range args {
-		if a == "-l" && i+1 < len(args) {
-			return true
+// HasUserFlag reports whether a login user was explicitly supplied.
+func HasUserFlag(args []string) bool { return hasOption(args, 'l', "User") }
+
+func hasOption(args []string, wanted byte, keyword string) bool {
+	for i := 0; i < len(args); i++ {
+		arg := args[i]
+		if arg == "--" || len(arg) < 2 || arg[0] != '-' {
+			break
 		}
-		// handle attached form: -lroot
-		if len(a) > 2 && a[0] == '-' && a[1] == 'l' {
-			return true
+		for j := 1; j < len(arg); j++ {
+			flag := arg[j]
+			if !flagsWithArg[flag] {
+				continue
+			}
+			value := arg[j+1:]
+			if value == "" {
+				i++
+				if i >= len(args) {
+					return false
+				}
+				value = args[i]
+			}
+			if flag == wanted {
+				return true
+			}
+			if flag == 'o' {
+				fields := strings.FieldsFunc(value, func(r rune) bool { return r == '=' || r == ' ' || r == '\t' })
+				if len(fields) >= 2 && strings.EqualFold(fields[0], keyword) {
+					return true
+				}
+			}
+			break
 		}
 	}
 	return false

internal/ssh/args_regression_test.go

@@ -0,0 +1,46 @@
+package ssh
+
+import "testing"
+
+func TestParseOptionClusters(t *testing.T) {
+	for _, args := range [][]string{
+		{"-vp", "2222", "server"},
+		{"-vp2222", "server"},
+		{"-vAl", "admin", "server"},
+		{"-vladmin", "server"},
+		{"-B", "eth0", "server"},
+		{"-P", "production", "server"},
+	} {
+		t.Run(args[0], func(t *testing.T) {
+			assertParsed(t, Parse(args), "server", "", len(args)-1)
+		})
+	}
+}
+
+func TestExplicitSSHOptions(t *testing.T) {
+	for _, tc := range []struct {
+		name       string
+		args       []string
+		user, port bool
+	}{
+		{"cluster port separated", []string{"-vp", "2222", "server"}, false, true},
+		{"cluster user attached", []string{"-vladmin", "server"}, true, false},
+		{"o separated", []string{"-o", "User=admin", "-o", "Port=2222", "server"}, true, true},
+		{"o attached and case insensitive", []string{"-ouSeR=admin", "-oport=2222", "server"}, true, true},
+		{"o whitespace", []string{"-o", " User = admin", "-o", "Port\t2222", "server"}, true, true},
+		{"cluster o", []string{"-voUser=admin", "server"}, true, false},
+		{"option value looks like flag", []string{"-i", "-lroot", "-F", "-p2222", "server"}, false, false},
+		{"remote flags", []string{"server", "-p2222", "-o", "User=admin"}, false, false},
+		{"after double dash", []string{"--", "-lroot", "-p2222"}, false, false},
+		{"missing value", []string{"-vp"}, false, false},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := HasUserFlag(tc.args); got != tc.user {
+				t.Errorf("HasUserFlag(%v) = %v, want %v", tc.args, got, tc.user)
+			}
+			if got := HasPortFlag(tc.args); got != tc.port {
+				t.Errorf("HasPortFlag(%v) = %v, want %v", tc.args, got, tc.port)
+			}
+		})
+	}
+}

internal/ssh/options.go

@@ -0,0 +1,200 @@
+package ssh
+
+import (
+	"fmt"
+	"regexp"
+	"sort"
+	"strings"
+
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/config"
+)
+
+// WrapperFlags are netssh's own long options. OpenSSH has no long options,
+// so these never collide with flags meant for ssh.
+type WrapperFlags struct {
+	DryRun bool
+	Jump   string // --jump HOST overrides the configured jump host
+	NoJump bool   // --no-jump disables any jump host, including ~/.ssh/config
+}
+
+// ExtractWrapperFlags removes netssh's long options that appear before the
+// destination. Anything after the destination belongs to the remote command.
+func ExtractWrapperFlags(args []string) (WrapperFlags, []string, error) {
+	var flags WrapperFlags
+	out := make([]string, 0, len(args))
+	for i := 0; i < len(args); i++ {
+		arg := args[i]
+		switch {
+		case arg == "--dry-run":
+			flags.DryRun = true
+		case arg == "--no-jump":
+			flags.NoJump = true
+		case arg == "--jump":
+			if i+1 >= len(args) {
+				return flags, nil, fmt.Errorf("--jump requires a host")
+			}
+			i++
+			flags.Jump = args[i]
+		case strings.HasPrefix(arg, "--jump="):
+			flags.Jump = strings.TrimPrefix(arg, "--jump=")
+		case arg == "--" || !strings.HasPrefix(arg, "-") || len(arg) < 2:
+			// Destination or end of options: keep the rest unchanged.
+			return flags, append(out, args[i:]...), validateJump(flags)
+		case strings.HasPrefix(arg, "--"):
+			return flags, nil, fmt.Errorf("unknown option %s", arg)
+		default:
+			out = append(out, arg)
+			// Keep the value of an ssh option such as -l USER together with it.
+			if takesSeparateValue(arg) && i+1 < len(args) {
+				i++
+				out = append(out, args[i])
+			}
+		}
+	}
+	return flags, out, validateJump(flags)
+}
+
+func validateJump(flags WrapperFlags) error {
+	if flags.Jump == "" && flags.NoJump {
+		return nil
+	}
+	if flags.Jump != "" && flags.NoJump {
+		return fmt.Errorf("--jump and --no-jump are mutually exclusive")
+	}
+	if strings.HasPrefix(flags.Jump, "-") {
+		return fmt.Errorf("--jump: invalid host %q", flags.Jump)
+	}
+	return nil
+}
+
+// takesSeparateValue reports whether a short option cluster ends with a flag
+// whose value is the next argument (e.g. "-l" or "-vp").
+func takesSeparateValue(arg string) bool {
+	for j := 1; j < len(arg); j++ {
+		if flagsWithArg[arg[j]] {
+			return j == len(arg)-1
+		}
+	}
+	return false
+}
+
+// Host is a resolved NetBox host.
+type Host struct {
+	Name string // NetBox name without the instance prefix
+	IP   string
+}
+
+// Result is the final ssh argument list and an optional notice for stderr.
+type Result struct {
+	Args   []string
+	Notice string
+}
+
+var plainHostname = regexp.MustCompile(`^[A-Za-z0-9]([A-Za-z0-9._-]*[A-Za-z0-9])?$`)
+
+// Apply replaces the destination at destIdx and inserts the configured -o
+// options directly before it. Explicit options given by the user come first,
+// and ssh uses the first -o value it obtains, so the user's choice wins.
+func Apply(args []string, destIdx int, host Host, opts config.SSHOptions, flags WrapperFlags) Result {
+	var inserted []string
+	add := func(keyword, value string) {
+		if !hasOption(args[:destIdx], 0, keyword) {
+			inserted = append(inserted, "-o", keyword+"="+value)
+		}
+	}
+
+	dest := host.IP
+	if opts.Target == "name" || opts.Target == "hostname" {
+		if plainHostname.MatchString(host.Name) {
+			dest = host.Name
+			if opts.Target == "name" {
+				add("HostName", host.IP)
+				add("HostKeyAlias", host.Name)
+			}
+		}
+	}
+
+	userJump := hasOption(args[:destIdx], 'J', "ProxyJump") || hasOption(args[:destIdx], 0, "ProxyCommand")
+	switch {
+	case userJump:
+	case flags.NoJump:
+		inserted = append(inserted, "-o", "ProxyJump=none")
+	case flags.Jump != "":
+		inserted = append(inserted, "-J", flags.Jump)
+	case opts.ProxyJump != "" && opts.ProxyJump != "none":
+		inserted = append(inserted, "-J", opts.ProxyJump)
+	}
+
+	var notice string
+	switch opts.HostKeyChecking {
+	case "strict":
+		add("StrictHostKeyChecking", "yes")
+	case "accept-new":
+		add("StrictHostKeyChecking", "accept-new")
+	case "off":
+		if !hasOption(args[:destIdx], 0, "StrictHostKeyChecking") {
+			add("StrictHostKeyChecking", "no")
+			add("UserKnownHostsFile", "/dev/null")
+			add("LogLevel", "ERROR")
+			notice = "host key checking is disabled for this connection (ssh.host_key_checking: off)"
+		}
+	}
+
+	if opts.AddressFamily != "" && !hasBoolFlag(args[:destIdx], '4') && !hasBoolFlag(args[:destIdx], '6') {
+		add("AddressFamily", opts.AddressFamily)
+	}
+
+	keys := make([]string, 0, len(opts.Options))
+	for key := range opts.Options {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	for _, key := range keys {
+		add(key, opts.Options[key])
+	}
+
+	// Extra arguments go first: short flags such as -4 or -A take the last
+	// value given, so the user's own flags later on the line still win.
+	replaced := ReplaceHost(args, destIdx, dest)
+	out := make([]string, 0, len(opts.ExtraArgs)+len(replaced)+len(inserted))
+	out = append(out, opts.ExtraArgs...)
+	out = append(out, replaced[:destIdx]...)
+	out = append(out, inserted...)
+	out = append(out, replaced[destIdx:]...)
+	return Result{Args: out, Notice: notice}
+}
+
+// hasBoolFlag reports whether a flag without a value, such as -4, was given.
+func hasBoolFlag(args []string, wanted byte) bool {
+	for i := 0; i < len(args); i++ {
+		arg := args[i]
+		if arg == "--" || len(arg) < 2 || arg[0] != '-' {
+			break
+		}
+		for j := 1; j < len(arg); j++ {
+			if arg[j] == wanted {
+				return true
+			}
+			if flagsWithArg[arg[j]] {
+				if j == len(arg)-1 {
+					i++
+				}
+				break
+			}
+		}
+	}
+	return false
+}
+
+// Quote renders an argument list as a copy-pasteable POSIX shell command.
+func Quote(argv []string) string {
+	quoted := make([]string, len(argv))
+	for i, arg := range argv {
+		if arg != "" && strings.Trim(arg, "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789@%+=:,./_-") == "" {
+			quoted[i] = arg
+			continue
+		}
+		quoted[i] = "'" + strings.ReplaceAll(arg, "'", `'\''`) + "'"
+	}
+	return strings.Join(quoted, " ")
+}

internal/ssh/options_test.go

@@ -0,0 +1,130 @@
+package ssh
+
+import (
+	"reflect"
+	"strings"
+	"testing"
+
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/config"
+)
+
+func TestExtractWrapperFlags(t *testing.T) {
+	for _, tc := range []struct {
+		args  []string
+		flags WrapperFlags
+		rest  []string
+	}{
+		{[]string{"--dry-run", "web"}, WrapperFlags{DryRun: true}, []string{"web"}},
+		{[]string{"-l", "--dry-run", "--jump", "jh", "web"}, WrapperFlags{Jump: "jh"}, []string{"-l", "--dry-run", "web"}},
+		{[]string{"--jump=jh", "-vp", "22", "web", "--dry-run"}, WrapperFlags{Jump: "jh"}, []string{"-vp", "22", "web", "--dry-run"}},
+		{[]string{"--no-jump", "--", "web"}, WrapperFlags{NoJump: true}, []string{"--", "web"}},
+	} {
+		flags, rest, err := ExtractWrapperFlags(tc.args)
+		if err != nil || flags != tc.flags || !reflect.DeepEqual(rest, tc.rest) {
+			t.Errorf("%v: got %+v %v %v", tc.args, flags, rest, err)
+		}
+	}
+	for _, args := range [][]string{{"--jump"}, {"--jump", "-x", "web"}, {"--jump=a", "--no-jump", "web"}, {"--version-typo", "web"}} {
+		if _, _, err := ExtractWrapperFlags(args); err == nil {
+			t.Errorf("%v accepted", args)
+		}
+	}
+}
+
+func apply(args []string, opts config.SSHOptions, flags WrapperFlags) Result {
+	return Apply(args, len(args)-1, Host{Name: "web.example.com", IP: "192.0.2.10"}, opts, flags)
+}
+
+func TestApplyDefaultConnectsToIP(t *testing.T) {
+	got := apply([]string{"-l", "root", "web"}, config.SSHOptions{}, WrapperFlags{})
+	if want := []string{"-l", "root", "192.0.2.10"}; !reflect.DeepEqual(got.Args, want) {
+		t.Fatalf("got %v", got.Args)
+	}
+}
+
+func TestApplyTargetName(t *testing.T) {
+	got := apply([]string{"admin@web"}, config.SSHOptions{Target: "name"}, WrapperFlags{})
+	want := []string{"-o", "HostName=192.0.2.10", "-o", "HostKeyAlias=web.example.com", "admin@web.example.com"}
+	if !reflect.DeepEqual(got.Args, want) {
+		t.Fatalf("got %v", got.Args)
+	}
+	got = apply([]string{"web"}, config.SSHOptions{Target: "hostname"}, WrapperFlags{})
+	if want := []string{"web.example.com"}; !reflect.DeepEqual(got.Args, want) {
+		t.Fatalf("got %v", got.Args)
+	}
+	// Names that are not plain hostnames fall back to the IP address.
+	got = Apply([]string{"x"}, 0, Host{Name: "rack 1 switch", IP: "192.0.2.1"}, config.SSHOptions{Target: "name"}, WrapperFlags{})
+	if want := []string{"192.0.2.1"}; !reflect.DeepEqual(got.Args, want) {
+		t.Fatalf("got %v", got.Args)
+	}
+}
+
+func TestApplyJumpPrecedence(t *testing.T) {
+	opts := config.SSHOptions{ProxyJump: "jh.example.com"}
+	for _, tc := range []struct {
+		args  []string
+		flags WrapperFlags
+		want  string
+	}{
+		{[]string{"web"}, WrapperFlags{}, "-J jh.example.com 192.0.2.10"},
+		{[]string{"web"}, WrapperFlags{Jump: "other"}, "-J other 192.0.2.10"},
+		{[]string{"web"}, WrapperFlags{NoJump: true}, "-o ProxyJump=none 192.0.2.10"},
+		{[]string{"-J", "mine", "web"}, WrapperFlags{}, "-J mine 192.0.2.10"},
+		{[]string{"-oProxyCommand=nc %h %p", "web"}, WrapperFlags{}, "-oProxyCommand=nc %h %p 192.0.2.10"},
+	} {
+		if got := strings.Join(apply(tc.args, opts, tc.flags).Args, " "); got != tc.want {
+			t.Errorf("%v %+v: got %q, want %q", tc.args, tc.flags, got, tc.want)
+		}
+	}
+	if got := apply([]string{"web"}, config.SSHOptions{ProxyJump: "none"}, WrapperFlags{}); len(got.Args) != 1 {
+		t.Fatalf("proxy_jump none still jumps: %v", got.Args)
+	}
+}
+
+func TestApplyHostKeyChecking(t *testing.T) {
+	got := apply([]string{"web"}, config.SSHOptions{HostKeyChecking: "off"}, WrapperFlags{})
+	want := "-o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -o LogLevel=ERROR 192.0.2.10"
+	if strings.Join(got.Args, " ") != want || got.Notice == "" {
+		t.Fatalf("got %v, notice %q", got.Args, got.Notice)
+	}
+	// An explicit user choice disables the whole "off" bundle.
+	got = apply([]string{"-o", "StrictHostKeyChecking=yes", "web"}, config.SSHOptions{HostKeyChecking: "off"}, WrapperFlags{})
+	if strings.Join(got.Args, " ") != "-o StrictHostKeyChecking=yes 192.0.2.10" || got.Notice != "" {
+		t.Fatalf("user choice overridden: %v", got.Args)
+	}
+	got = apply([]string{"web"}, config.SSHOptions{HostKeyChecking: "accept-new"}, WrapperFlags{})
+	if strings.Join(got.Args, " ") != "-o StrictHostKeyChecking=accept-new 192.0.2.10" {
+		t.Fatalf("got %v", got.Args)
+	}
+}
+
+func TestApplyOptionsAndExtraArgs(t *testing.T) {
+	opts := config.SSHOptions{
+		AddressFamily: "inet",
+		ExtraArgs:     []string{"-A"},
+		Options:       map[string]string{"serveraliveinterval": "60", "user": "ignored"},
+	}
+	got := apply([]string{"-o", "User=me", "web"}, opts, WrapperFlags{})
+	want := "-A -o User=me -o AddressFamily=inet -o serveraliveinterval=60 192.0.2.10"
+	if strings.Join(got.Args, " ") != want {
+		t.Fatalf("got %q", strings.Join(got.Args, " "))
+	}
+	got = apply([]string{"-v6", "web"}, config.SSHOptions{AddressFamily: "inet"}, WrapperFlags{})
+	if strings.Join(got.Args, " ") != "-v6 192.0.2.10" {
+		t.Fatalf("address family overrides -6: %v", got.Args)
+	}
+}
+
+func TestApplyKeepsRemoteCommand(t *testing.T) {
+	got := Apply([]string{"web", "uptime", "-o", "x"}, 0, Host{Name: "web", IP: "192.0.2.1"}, config.SSHOptions{ProxyJump: "jh"}, WrapperFlags{})
+	if want := []string{"-J", "jh", "192.0.2.1", "uptime", "-o", "x"}; !reflect.DeepEqual(got.Args, want) {
+		t.Fatalf("got %v", got.Args)
+	}
+}
+
+func TestQuote(t *testing.T) {
+	got := Quote([]string{"ssh", "-o", "ProxyCommand=nc %h %p", "it's", "", "a@b:22"})
+	if want := `ssh -o 'ProxyCommand=nc %h %p' 'it'\''s' '' a@b:22`; got != want {
+		t.Fatalf("got %s", got)
+	}
+}

internal/tui/instances_test.go

@@ -0,0 +1,81 @@
+package tui
+
+import (
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	tea "charm.land/bubbletea/v2"
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/cache"
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/netbox"
+)
+
+func tuiSourceServer(t *testing.T, fail bool) *httptest.Server {
+	t.Helper()
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if fail {
+			http.Error(w, "offline", 503)
+			return
+		}
+		if r.URL.Path == "/api/dcim/devices/" {
+			fmt.Fprint(w, `{"count":1,"results":[{"id":1,"name":"web","primary_ip4":{"address":"10.0.0.1/24"}}]}`)
+		} else {
+			fmt.Fprint(w, `{"count":0,"results":[]}`)
+		}
+	}))
+	t.Cleanup(srv.Close)
+	return srv
+}
+
+func TestCombinedSearchDoesNotStopAtFirstCachedInstance(t *testing.T) {
+	office, lab := tuiSourceServer(t, false), tuiSourceServer(t, false)
+	client := netbox.NewMultiClient([]netbox.Source{{Name: "office", URL: office.URL}, {Name: "lab", URL: lab.URL}})
+	c := cache.New("", 3600)
+	c.Upsert(cache.Entry{Name: "office/web", Kind: "device", IP: "10.0.0.9"})
+	m := New(client, c, "")
+	msg := m.doSearch("web", 1)().(searchResultMsg)
+	if msg.err != nil || len(msg.entries) != 2 {
+		t.Fatalf("cache hid another instance: %+v, %v", msg.entries, msg.err)
+	}
+	m.input.SetValue("web")
+	m.seq = 1
+	m.Update(msg)
+	if len(m.list.Items()) != 2 {
+		t.Fatal("combined results not displayed")
+	}
+	for _, item := range m.list.Items() {
+		if !strings.Contains(item.(hostItem).name, "/") {
+			t.Fatal("instance not visible in results")
+		}
+	}
+	m.list.Select(0)
+	m.Update(tea.KeyPressMsg{Code: tea.KeyEnter})
+	if m.selected == nil || m.selected.Name != "lab/web" {
+		t.Fatalf("selection lost source: %+v", m.selected)
+	}
+}
+
+func TestPartialOutageKeepsLiveAndCachedResultsVisible(t *testing.T) {
+	office, lab := tuiSourceServer(t, false), tuiSourceServer(t, true)
+	client := netbox.NewMultiClient([]netbox.Source{{Name: "office", URL: office.URL}, {Name: "lab", URL: lab.URL}})
+	c := cache.New("", 3600)
+	c.Upsert(cache.Entry{Name: "lab/web", Kind: "device", IP: "10.0.0.2"})
+	m := New(client, c, "")
+	m.input.SetValue("web")
+	m.seq = 1
+	m.Update(tea.WindowSizeMsg{Width: 100, Height: 24})
+	msg := m.doSearch("web", 1)().(searchResultMsg)
+	if len(msg.entries) != 2 || msg.err == nil {
+		t.Fatalf("partial outage lost cache or warning: %+v, %v", msg.entries, msg.err)
+	}
+	m.Update(msg)
+	view := m.View().Content
+	if !strings.Contains(view, "warning:") || !strings.Contains(view, "lab/web") || !strings.Contains(view, "office/web") {
+		t.Fatalf("partial results hidden: %s", view)
+	}
+	if rows := strings.Count(view, "\n"); rows > 24 {
+		t.Fatalf("outage warning overflowed view: %d", rows)
+	}
+}

internal/tui/model.go

@@ -4,19 +4,20 @@ import (
 	"context"
 	"fmt"
 	"io"
+	"sort"
 	"strconv"
 	"strings"
 	"time"
 
-	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/notes"
-	"github.com/charmbracelet/bubbles/list"
-	"github.com/charmbracelet/bubbles/textarea"
-	"github.com/charmbracelet/bubbles/textinput"
-	tea "github.com/charmbracelet/bubbletea"
-	"github.com/charmbracelet/lipgloss"
+	"charm.land/bubbles/v2/list"
+	"charm.land/bubbles/v2/textarea"
+	"charm.land/bubbles/v2/textinput"
+	tea "charm.land/bubbletea/v2"
+	"charm.land/lipgloss/v2"
 
 	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/cache"
 	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/netbox"
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/notes"
 )
 
 // SelectedHost is returned when the user confirms a host in the TUI.
@@ -78,7 +79,7 @@ func (d compactDelegate) Render(w io.Writer, m list.Model, index int, item list.
 	if index == m.Index() {
 		line = lipgloss.NewStyle().Bold(true).Foreground(lipgloss.Color("86")).Render("> " + strings.TrimPrefix(line, "  "))
 	}
-	fmt.Fprintln(w, line)
+	fmt.Fprint(w, line)
 }
 
 // --- filter ---
@@ -158,7 +159,7 @@ type Model struct {
 	height                         int
 	recentMode                     bool // true when showing recent hosts (empty search, initial state)
 	filterOpen                     bool // Ctrl+F toggles
-	editMode                       bool // 'e' on selected item
+	editMode                       bool // Ctrl+E on the selected item
 }
 
 func New(client *netbox.Client, c *cache.Cache, defaultUser string, defaultPorts ...int) *Model {
@@ -221,6 +222,7 @@ func (m *Model) loadRecent() tea.Cmd {
 }
 
 func (m *Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
+	defer m.resizeList()
 	switch msg := msg.(type) {
 	case noteResultMsg:
 		m.noteBusy = false
@@ -240,18 +242,13 @@ func (m *Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 	case tea.WindowSizeMsg:
 		m.width = msg.Width
 		m.height = msg.Height
-		extraRows := 4
-		if m.filterOpen {
-			extraRows++
-		}
-		if m.editMode {
-			extraRows += 2
-		}
-		m.list.SetSize(msg.Width, max(1, msg.Height-extraRows))
+		m.input.SetWidth(max(1, msg.Width-lipgloss.Width(m.input.Prompt)))
+		m.filterInput.SetWidth(max(1, msg.Width-lipgloss.Width(m.filterInput.Prompt)))
+		m.editInput.SetWidth(max(1, msg.Width-lipgloss.Width("Connect as: ")))
 		m.noteInput.SetWidth(max(10, msg.Width-4))
 		return m, nil
 
-	case tea.KeyMsg:
+	case tea.KeyPressMsg:
 		if msg.String() == "ctrl+c" {
 			return m, tea.Quit
 		}
@@ -416,21 +413,33 @@ func (m *Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 			return m, nil // discard stale result
 		}
 		m.loading = false
-		if msg.err != nil {
-			m.err = msg.err
-			return m, nil
-		}
+		m.err = msg.err
 		m.lastResults = msg.entries
 		m.updateListItems(msg.entries)
-		m.err = nil
 		return m, nil
 	}
 
 	if m.noteMode {
+		if m.noteBusy {
+			return m, nil
+		}
 		var cmd tea.Cmd
 		m.noteInput, cmd = m.noteInput.Update(msg)
 		return m, cmd
 	}
+	// Paste and cursor events are separate from key presses in Bubble Tea v2.
+	// Route them to the focused editor as well.
+	if m.editMode {
+		var cmd tea.Cmd
+		m.editInput, cmd = m.editInput.Update(msg)
+		return m, cmd
+	}
+	if m.filterOpen {
+		var cmd tea.Cmd
+		m.filterInput, cmd = m.filterInput.Update(msg)
+		m.updateListItems(m.lastResults)
+		return m, cmd
+	}
 	// Forward to search input and restart debounce timer.
 	var cmds []tea.Cmd
 	var inputCmd tea.Cmd
@@ -449,7 +458,13 @@ func (m *Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 	return m, tea.Batch(cmds...)
 }
 
-func (m *Model) View() string {
+func (m *Model) View() tea.View {
+	view := tea.NewView(m.viewContent())
+	view.AltScreen = true
+	return view
+}
+
+func (m *Model) viewContent() string {
 	if m.noteMode {
 		target := "local"
 		if m.noteRemote {
@@ -477,9 +492,15 @@ func (m *Model) View() string {
 
 	if m.loading {
 		sb.WriteString(lipgloss.NewStyle().Foreground(lipgloss.Color("240")).Render("  searching…") + "\n")
-	} else if m.err != nil {
-		sb.WriteString(lipgloss.NewStyle().Foreground(lipgloss.Color("9")).Render("  error: "+m.err.Error()) + "\n")
 	} else {
+		if m.err != nil {
+			warning := "  warning: " + strings.ReplaceAll(m.err.Error(), "\n", "; ")
+			style := lipgloss.NewStyle().Foreground(lipgloss.Color("9"))
+			if m.width > 0 {
+				style = style.MaxWidth(m.width)
+			}
+			sb.WriteString(style.Render(warning) + "\n")
+		}
 		if m.recentMode && m.input.Value() == "" {
 			if len(m.list.Items()) > 0 {
 				sb.WriteString(lipgloss.NewStyle().Foreground(lipgloss.Color("240")).Render("  Recent connections") + "\n")
@@ -516,25 +537,30 @@ func (m *Model) startDebounce() tea.Cmd {
 func (m *Model) doSearch(query string, seq int) tea.Cmd {
 	opts := m.netboxSearchOpts()
 	return func() tea.Msg {
-		// Return cache hits immediately without a network round-trip.
+		var cached []netbox.HostEntry
 		if m.cache != nil {
-			if cached := m.cache.Search(query); len(cached) > 0 {
-				entries := make([]netbox.HostEntry, len(cached))
-				for i, c := range cached {
-					entries[i] = netbox.HostEntry{Name: c.Name, PrimaryIP4: c.IP, Kind: c.Kind, Tags: c.Tags}
-				}
-				return searchResultMsg{query: query, seq: seq, entries: entries}
+			for _, entry := range m.cache.Search(query) {
+				source, name := netbox.SplitTarget(entry.Name)
+				cached = append(cached, netbox.HostEntry{Source: source, Name: name, PrimaryIP4: entry.IP, Kind: entry.Kind, Tags: entry.Tags})
 			}
 		}
-
-		if m.client == nil {
-			return searchResultMsg{query: query, seq: seq, entries: nil}
+		if m.client == nil || (len(cached) > 0 && !m.client.MultipleSources()) {
+			return searchResultMsg{query: query, seq: seq, entries: cached}
 		}
-
 		ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 		defer cancel()
-
 		entries, err := m.client.Search(ctx, query, opts)
+		// A cached hit in one instance must not hide live hosts in other instances.
+		seen := make(map[string]bool)
+		for _, e := range entries {
+			seen[e.Target()+"\x00"+e.Kind] = true
+		}
+		for _, e := range cached {
+			if !seen[e.Target()+"\x00"+e.Kind] {
+				entries = append(entries, e)
+			}
+		}
+		sort.SliceStable(entries, func(i, j int) bool { return entries[i].Target() < entries[j].Target() })
 		return searchResultMsg{query: query, seq: seq, entries: entries, err: err}
 	}
 }
@@ -559,9 +585,34 @@ func (m *Model) updateListItems(entries []netbox.HostEntry) {
 		if ip == "" {
 			ip = e.PrimaryIP6
 		}
-		items[i] = hostItem{id: e.ID, name: e.Name, ip: ip, kind: e.Kind, tags: e.Tags}
+		items[i] = hostItem{id: e.ID, name: e.Target(), ip: ip, kind: e.Kind, tags: e.Tags}
 	}
 	m.list.SetItems(items)
+	m.resizeList()
+}
+
+// resizeList keeps the footer visible when the recent heading or editors change.
+func (m *Model) resizeList() {
+	if m.width <= 0 || m.height <= 0 {
+		return
+	}
+	extraRows := 5 // title, blank line, search, footer separator, footer
+	if m.err != nil {
+		extraRows++
+	}
+	if m.recentMode && m.input.Value() == "" && len(m.list.Items()) > 0 {
+		extraRows++
+	}
+	if m.filterOpen {
+		extraRows++
+	}
+	if m.editMode {
+		extraRows++
+	}
+	height := max(1, m.height-extraRows)
+	if m.list.Width() != m.width || m.list.Height() != height {
+		m.list.SetSize(m.width, height)
+	}
 }
 
 // openEdit switches to edit mode for the given list item.

internal/tui/model_test.go

@@ -1,16 +1,18 @@
 package tui
 
 import (
+	"testing"
+
+	tea "charm.land/bubbletea/v2"
+
 	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/netbox"
 	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/notes"
-	tea "github.com/charmbracelet/bubbletea"
-	"testing"
 )
 
 func TestTypingEDoesNotOpenConnectionEditor(t *testing.T) {
 	m := New(nil, nil, "")
 	m.updateListItems([]netbox.HostEntry{{Name: "server"}})
-	m.Update(tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune{'e'}})
+	m.Update(tea.KeyPressMsg{Code: 'e', Text: "e"})
 	if m.editMode || m.input.Value() != "e" {
 		t.Fatal("e intercepted")
 	}
@@ -52,7 +54,7 @@ func TestFailedNoteLoadCannotBeSaved(t *testing.T) {
 	m := New(nil, nil, "")
 	m.SetNotes(&notes.Service{Dir: t.TempDir()})
 	m.noteMode = true
-	_, cmd := m.Update(tea.KeyMsg{Type: tea.KeyCtrlS})
+	_, cmd := m.Update(tea.KeyPressMsg{Code: 's', Mod: tea.ModCtrl})
 	if cmd != nil {
 		t.Fatal("save allowed before successful load")
 	}
@@ -63,7 +65,7 @@ func TestConnectionEditorKeepsOriginalHost(t *testing.T) {
 	first := hostItem{name: "first", ip: "10.0.0.1"}
 	m.openEdit(first)
 	m.updateListItems([]netbox.HostEntry{{Name: "second", PrimaryIP4: "10.0.0.2"}})
-	m.Update(tea.KeyMsg{Type: tea.KeyEnter})
+	m.Update(tea.KeyPressMsg{Code: tea.KeyEnter})
 	if m.selected == nil || m.selected.Name != "first" {
 		t.Fatalf("edited host changed: %+v", m.selected)
 	}

internal/tui/v2_test.go

@@ -0,0 +1,123 @@
+package tui
+
+import (
+	"strings"
+	"testing"
+
+	tea "charm.land/bubbletea/v2"
+
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/netbox"
+)
+
+func TestV2PasteFollowsFocusedEditor(t *testing.T) {
+	t.Run("search", func(t *testing.T) {
+		m := New(nil, nil, "")
+		_, cmd := m.Update(tea.PasteMsg{Content: "web-ä"})
+		if m.input.Value() != "web-ä" || m.seq != 1 || cmd == nil {
+			t.Fatalf("paste did not start search: %q, seq %d", m.input.Value(), m.seq)
+		}
+	})
+	t.Run("connection editor", func(t *testing.T) {
+		m := New(nil, nil, "")
+		m.openEdit(hostItem{name: "web", ip: "10.0.0.1"})
+		m.editInput.SetValue("")
+		m.Update(tea.PasteMsg{Content: "ops@web:2222"})
+		m.Update(tea.KeyPressMsg{Code: tea.KeyEnter})
+		if m.selected == nil || m.selected.User != "ops" || m.selected.Port != "2222" {
+			t.Fatalf("paste lost in editor: %+v", m.selected)
+		}
+		if m.input.Value() != "" {
+			t.Fatal("editor paste changed search")
+		}
+	})
+	t.Run("filter", func(t *testing.T) {
+		m := New(nil, nil, "")
+		m.lastResults = []netbox.HostEntry{{Name: "vm", Kind: "vm"}, {Name: "device", Kind: "device"}}
+		m.updateListItems(m.lastResults)
+		m.Update(tea.KeyPressMsg{Code: 'f', Mod: tea.ModCtrl})
+		m.Update(tea.PasteMsg{Content: "kind:vm"})
+		if m.filterInput.Value() != "kind:vm" || len(m.list.Items()) != 1 {
+			t.Fatalf("paste did not filter: %q, %d results", m.filterInput.Value(), len(m.list.Items()))
+		}
+		if m.input.Value() != "" {
+			t.Fatal("filter paste changed search")
+		}
+	})
+	t.Run("notes", func(t *testing.T) {
+		m := New(nil, nil, "")
+		m.noteMode = true
+		m.input.Blur()
+		m.noteInput.Focus()
+		m.Update(tea.PasteMsg{Content: "First line\nSecond line"})
+		if m.noteInput.Value() != "First line\nSecond line" {
+			t.Fatalf("multiline paste lost: %q", m.noteInput.Value())
+		}
+		m.noteBusy = true
+		m.Update(tea.PasteMsg{Content: "must not change busy note"})
+		if m.noteInput.Value() != "First line\nSecond line" {
+			t.Fatal("paste edited note while loading/saving")
+		}
+	})
+}
+
+func TestV2ViewKeepsAlternateScreenInEachMode(t *testing.T) {
+	for _, mode := range []string{"search", "edit", "notes"} {
+		t.Run(mode, func(t *testing.T) {
+			m := New(nil, nil, "")
+			m.Update(tea.WindowSizeMsg{Width: 80, Height: 24})
+			if mode == "edit" {
+				m.openEdit(hostItem{name: "web"})
+			}
+			if mode == "notes" {
+				m.noteMode = true
+			}
+			view := m.View()
+			if !view.AltScreen || strings.TrimSpace(view.Content) == "" {
+				t.Fatalf("invalid %s view: %+v", mode, view)
+			}
+		})
+	}
+}
+
+func TestV2KeyReleaseDoesNotTypeTwice(t *testing.T) {
+	m := New(nil, nil, "")
+	m.Update(tea.KeyPressMsg{Code: 'e', Text: "e"})
+	m.Update(tea.KeyReleaseMsg{Code: 'e', Text: "e"})
+	if m.input.Value() != "e" {
+		t.Fatalf("key release changed input: %q", m.input.Value())
+	}
+	m.Update(tea.KeyPressMsg{Code: ' ', Text: " "})
+	if m.input.Value() != "e " {
+		t.Fatalf("space not inserted: %q", m.input.Value())
+	}
+}
+
+func TestV2ResizeShowsFullSearchPromptAndFooter(t *testing.T) {
+	m := New(nil, nil, "")
+	m.Update(tea.WindowSizeMsg{Width: 100, Height: 24})
+	var entries []netbox.HostEntry
+	for range 30 {
+		entries = append(entries, netbox.HostEntry{Name: "web", Kind: "device"})
+	}
+	m.updateListItems(entries)
+	view := m.View()
+	if m.input.Width() != 98 || m.filterInput.Width() != 92 || m.editInput.Width() != 88 {
+		t.Fatalf("editors were not sized for terminal: search=%d filter=%d edit=%d", m.input.Width(), m.filterInput.Width(), m.editInput.Width())
+	}
+	if !strings.Contains(view.Content, "earch hostname") || !strings.Contains(view.Content, "ctrl+c quit") {
+		t.Fatalf("search prompt or footer missing: %s", view.Content)
+	}
+	assertFits := func() {
+		t.Helper()
+		if rows := strings.Count(m.View().Content, "\n"); rows > 24 {
+			t.Fatalf("view overflows terminal: %d rows", rows)
+		}
+	}
+	assertFits()
+	m.lastResults = entries
+	m.Update(tea.KeyPressMsg{Code: 'f', Mod: tea.ModCtrl})
+	assertFits()
+	m.Update(tea.KeyPressMsg{Code: 'f', Mod: tea.ModCtrl})
+	m.Update(tea.KeyPressMsg{Code: 'e', Mod: tea.ModCtrl})
+	assertFits()
+}

release_notes_test.go

@@ -0,0 +1,57 @@
+package netssh_test
+
+import (
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestReleaseNotesUseReleaseAssetAndVersionRange(t *testing.T) {
+	script, err := filepath.Abs("scripts/release-notes.sh")
+	if err != nil {
+		t.Fatal(err)
+	}
+	repo := t.TempDir()
+	git := func(args ...string) {
+		t.Helper()
+		cmd := exec.Command("git", args...)
+		cmd.Dir = repo
+		cmd.Env = append(os.Environ(), "GIT_AUTHOR_NAME=Release Test", "GIT_AUTHOR_EMAIL=release@example.com", "GIT_COMMITTER_NAME=Release Test", "GIT_COMMITTER_EMAIL=release@example.com", "GIT_CONFIG_NOSYSTEM=1", "GIT_CONFIG_GLOBAL=/dev/null")
+		if out, err := cmd.CombinedOutput(); err != nil {
+			t.Fatalf("git %v: %v\n%s", args, err, out)
+		}
+	}
+	git("init")
+	git("-c", "commit.gpgsign=false", "commit", "--allow-empty", "-m", "Initial version")
+	git("tag", "v0.0.1")
+	render := func(tag string) string {
+		t.Helper()
+		cmd := exec.Command("bash", script, tag, "https://git.example.com/team/netssh/")
+		cmd.Dir = repo
+		out, err := cmd.CombinedOutput()
+		if err != nil {
+			t.Fatalf("render: %v\n%s", err, out)
+		}
+		return string(out)
+	}
+	initial := render("v0.0.1")
+	if !strings.Contains(initial, "Initial release:") || !strings.Contains(initial, "Initial version") {
+		t.Fatalf("first release: %s", initial)
+	}
+	git("-c", "commit.gpgsign=false", "commit", "--allow-empty", "-m", `Add installer and "quoted" release notes`)
+	git("tag", "v0.0.2")
+	git("-c", "commit.gpgsign=false", "commit", "--allow-empty", "-m", "Unreleased changes")
+	notes := render("v0.0.2")
+	for _, want := range []string{"https://git.example.com/team/netssh/releases/download/v0.0.2/install.sh", "Changes since `v0.0.1`:", `Add installer and "quoted" release notes`, "checksums.txt"} {
+		if !strings.Contains(notes, want) {
+			t.Errorf("missing %q:\n%s", want, notes)
+		}
+	}
+	for _, excluded := range []string{"Initial version", "Unreleased changes", "raw/branch/main"} {
+		if strings.Contains(notes, excluded) {
+			t.Errorf("unexpected %q:\n%s", excluded, notes)
+		}
+	}
+}

renovate.json

@@ -2,5 +2,41 @@
   "$schema": "https://docs.renovatebot.com/renovate-schema.json",
   "extends": [
     "config:recommended"
+  ],
+  "dependencyDashboard": true,
+  "postUpdateOptions": [
+    "gomodTidy"
+  ],
+  "packageRules": [
+    {
+      "description": "Keep GitHub Actions in the Gitea release workflow up to date",
+      "matchManagers": [
+        "github-actions"
+      ],
+      "enabled": true
+    },
+    {
+      "description": "Include indirect Go modules in dependency updates",
+      "matchManagers": [
+        "gomod"
+      ],
+      "matchDepTypes": [
+        "indirect"
+      ],
+      "enabled": true
+    },
+    {
+      "description": "Update the Go version declared in go.mod",
+      "matchManagers": [
+        "gomod"
+      ],
+      "matchDepNames": [
+        "go"
+      ],
+      "matchDepTypes": [
+        "golang"
+      ],
+      "rangeStrategy": "bump"
+    }
   ]
 }

scripts/release-notes.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ $# -ne 2 ]]; then
+  printf 'Usage: %s TAG REPOSITORY_URL\n' "$0" >&2
+  exit 1
+fi
+
+TAG=$1
+REPOSITORY_URL=${2%/}
+git rev-parse --verify "$TAG^{commit}" >/dev/null
+# Start at the parent so the release being built cannot match itself.
+PREVIOUS_TAG=$(git describe --tags --abbrev=0 --match 'v[0-9]*' "$TAG^" 2>/dev/null || true)
+
+printf '## Installation / Update\n\n'
+printf '```sh\ncurl -fsSL %s/releases/download/%s/install.sh | bash\n```\n\n' "$REPOSITORY_URL" "$TAG"
+printf 'The installer is attached to this release. It checks dependencies and verifies binary SHA-256 checksums before installation. Python is not required.\n\n'
+printf 'Download `checksums.txt` to verify the attached binaries and `install.sh`.\n\n'
+printf '## Changes\n\n'
+if [[ -n "$PREVIOUS_TAG" ]]; then
+  printf 'Changes since `%s`:\n\n' "$PREVIOUS_TAG"
+  git log --no-merges --format='- %s (%h)' "$PREVIOUS_TAG..$TAG"
+else
+  printf 'Initial release:\n\n'
+  git log --no-merges --format='- %s (%h)' "$TAG"
+fi