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 — 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)

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: add, list --json, print-command, completions.