Quickstart

The first five minutes with sshelf.

1. Launch

sshelf

The first run writes a commented config.toml under ~/.config/sshelf/. You land in the (empty) host list. F1 shows every key at any time.

2. Add a host, or import the ones you already have

Press Ctrl-a: the add form opens with sensible defaults, so typing a Name and a Hostname and pressing Ctrl-s is enough for a first host. Auth, jump hosts, tags, and the rest are covered in Adding & editing hosts.

Already have hosts in ~/.ssh/config? Import them. The import is read-only: sshelf copies them into its own database and never writes your config:

sshelf import --dry-run    # preview what would be imported
sshelf import              # do it (or press Ctrl-o in the TUI)

On a Tailscale tailnet, sshelf import --tailscale brings in every machine in one go, with the same rules and the same read-only, add-only promise.

3. Connect

Type a few characters to fuzzy-filter, Enter to connect. sshelf records your usage and then execs into ssh. The TUI is gone and it’s a plain ssh session; when it ends you’re back at your shell. The hosts you use most float to the top of the idle list.

4. Connect even faster

sshelf prod-web            # straight to a saved host by name, no TUI
sshelf -                   # reconnect to the most recently used host

5. Know where your data lives

Your hosts are one human-readable TOML file, ~/.config/sshelf/hosts.toml, safe to hand-edit and to keep in your dotfiles. Secrets are not in it: they live in your OS keyring or an encrypted vault (Passwords, keys & 2FA).

Where to next

• Searching & connecting: tag:/site: filters, frecency, yanking the generated command.
• Transferring files: the dual-pane SFTP browser (Ctrl-t).
• Port forwarding: background tunnels that outlive the TUI (Ctrl-f).
• Exporting to SSH config: let plain ssh/scp and VS Code Remote use your hosts by name.
• CLI reference: scripting with add, list --json, print-command, completions.