# sshelf

> A terminal UI for your SSH hosts: fuzzy-search and connect, transfer files over SFTP, and run
> background port forwards. It keeps its own host database and never edits `~/.ssh/config`.

sshelf is a single Rust binary for macOS and Linux (OpenSSH 8.4+ at runtime). Hosts live in a
human-readable `hosts.toml` of its own; connecting `exec()`s into your real `ssh`, so there is
no wrapper between you and the session. Passwords, for the hosts that can't use keys, are kept
in the OS keyring or an `age`-encrypted vault and supplied through `SSH_ASKPASS`, never in a
file and never in argv. It has no telemetry, no account, no cloud, holds no API tokens, makes no
network calls of its own, never writes anything under `~/.ssh`, and keeps no secrets in
`hosts.toml`.

## Docs

- [Introduction](https://max-rh.github.io/sshelf/index.html): what sshelf is, what's in the box, and where each piece is documented.
- [Install](https://max-rh.github.io/sshelf/install.html): Homebrew, shell installer, .deb, .rpm, Gentoo, cargo; platform and OpenSSH requirements.
- [Quickstart](https://max-rh.github.io/sshelf/quickstart.html): the first five minutes, adding or importing hosts, connecting, and where your data lives.
- [Adding & editing hosts](https://max-rh.github.io/sshelf/hosts.html): the add/edit form, every field, and the quick-add path.
- [Searching & connecting](https://max-rh.github.io/sshelf/search-connect.html): fuzzy filtering, `tag:`/`site:` tokens, frecency ordering, every key, and what "connect" does.
- [Transferring files](https://max-rh.github.io/sshelf/transfer.html): the dual-pane SFTP screen (`Ctrl-t`), marking, batch sends, `F7` mkdir, and its limits.
- [Port forwarding](https://max-rh.github.io/sshelf/port-forwarding.html): Local/Remote/SOCKS tunnels that outlive the TUI (`Ctrl-f`), and the manager (`F4`).
- [Sites & tags](https://max-rh.github.io/sshelf/sites-tags.html): sites with a shared bastion and inherited defaults, and free-form tags.
- [Passwords, keys & 2FA](https://max-rh.github.io/sshelf/passwords-2fa.html): auth methods, where secrets live, auto-supply, and hosts that need a verification code.
- [Importing hosts](https://max-rh.github.io/sshelf/import.html): read-only import from `~/.ssh/config`, and `--tailscale` for a whole tailnet.
- [Exporting to SSH config](https://max-rh.github.io/sshelf/export.html): the `Include` fragment sshelf writes that lets plain ssh/scp/rsync and VS Code Remote resolve your hosts.
- [CLI reference](https://max-rh.github.io/sshelf/cli.html): every subcommand and flag, non-interactive `add`, `list --json`, and shell completions.
- [Configuration](https://max-rh.github.io/sshelf/configuration.html): `config.toml` keys, the settings screen, and where every file lives.
- [Checking your setup (doctor)](https://max-rh.github.io/sshelf/doctor.html): what `sshelf doctor` checks, what each verdict means, and its exit code.
- [FAQ & troubleshooting](https://max-rh.github.io/sshelf/faq.html): common questions, including why sshelf doesn't use your ssh config.
- [Security & threat model](https://max-rh.github.io/sshelf/security.html): what stored secrets are protected against and what they are not.
- [How the ssh command is built](https://max-rh.github.io/sshelf/ssh-command.html): argv generation, the `exec()` handoff, and the `SSH_ASKPASS` mechanism.

## Development

- [Architecture](https://max-rh.github.io/sshelf/architecture.html): the module layout and how a keystroke becomes an ssh process.
- [Project structure](https://max-rh.github.io/sshelf/structure.html): what lives in which file.
- [Data model & files](https://max-rh.github.io/sshelf/data-model.html): the `hosts.toml` schema and the app-owned state files.
- [Decision log](https://max-rh.github.io/sshelf/decisions.html): every design decision, with the alternatives that were rejected.
- [Progress log](https://max-rh.github.io/sshelf/progress.html): dated entries for every change to the project.

## Repo

- [README](https://github.com/max-rh/sshelf#readme): the overview, install, feature tour, and a comparison with similar tools.
- [PRIVACY.md](https://github.com/max-rh/sshelf/blob/master/PRIVACY.md): exactly what sshelf reads, writes, runs, and sends.
- [SECURITY.md](https://github.com/max-rh/sshelf/blob/master/SECURITY.md): the threat model and how to report a vulnerability.
- [CHANGELOG.md](https://github.com/max-rh/sshelf/blob/master/CHANGELOG.md): user-facing changes per release.
- [CONTRIBUTING.md](https://github.com/max-rh/sshelf/blob/master/CONTRIBUTING.md): how to build, test, and send a change.