All 22 apps

CandySshLauncher

TUI directory of SSH endpoints

inspired by charmbracelet/wishlist ssh launcher yaml-config

CandySshLauncher code coverage

Launch candy-ssh-launcher, pick a host, hit Enter — the current process is replaced with ssh connecting to it. Reads YAML or JSON; supports identity files, ssh options, ProxyJump.

Install

composer require sugarcraft/candy-ssh-launcher

The package publishes its dev branch until the first candy-ssh-launcher/v* tag is cut, so projects on Composer's default minimum-stability need the root "minimum-stability": "dev", "prefer-stable": true pair. A single-file .phar is built from tools/build-phar.php (see the README); release download URLs appear with the tags.

Quickstart

# ~/.config/wishlist.yml
- name: production
  host: prod.example.com
  port: 2222
  user: deploy
  identity_file: ~/.ssh/prod-deploy

- name: staging
  host: stage.example.com
  user: deploy

- name: jumpbox
  host: bastion.example.com
  options:
    - ServerAliveInterval=30
    - ProxyJump=gw.example.com

What's in the box

Config discovery--config ▸ ./wishlist.{yml,yaml,json} ▸ ~/.config/wishlist.{yml,yaml,json} — first file that exists wins at each tier.
YAML schemaname, host, port, user, description, identityFiles[] (or the singular identity_file / identityFile aliases), proxyJump, options[].
Type-filterType to fuzzy-narrow the list (sugar-fuzzy Smith–Waterman scoring, live match count, 16 locales).
ProxyJump / OptionsPass any ssh option through the entry's options array.
pcntl_execReplaces the launcher process — no double-shell — so signals + exit codes propagate cleanly.
Composer-installableSingle binary at vendor/bin/candy-ssh-launcher, plus a self-contained .phar built by tools/build-phar.php.
Keys↑/↓, Home/End, PgUp/PgDn move; type to narrow; Enter connects; Ctrl+U/W/H edit the query; Esc quits with 130. Bracketed paste is text, never a command.
RequirementsPHP 8.3+ with ext-pcntl, Unix only, UTF-8 terminal. Honors NO_COLOR/CLICOLOR=0 and TERM=dumb.
AccessibilityKeyboard-only with glyph-marked selection and zero animation; screen-reader path is --list plus direct named dispatch (candy-ssh-launcher home).

Security

Your config file is trusted input — exactly like ~/.ssh/config itself. Whatever a config declares, the launcher passes to ssh: options: entries become real -o settings verbatim, and OpenSSH options such as ProxyCommand / LocalCommand execute arbitrary commands at connect time. Keep config files (and ~/.ssh/config) owned by you with 0600/0644 permissions and do not accept endpoint files from strangers; see the fleet-wide trust boundary.

Source & demos

Try the quickstart →

API

ClassMethodDescription
Endpointnew(name, host)Create SSH endpoint (port, user, identityFiles, description, proxyJump, options optional)
EndpointwithName(name) · withHost(host) · withPort(port) · withUser(user)Fluent setters — each returns a new endpoint
EndpointwithIdentityFiles(paths[])Set identity files, in order, each passed to ssh as its own -i
EndpointwithDescription(text) · withProxyJump(host) · withOptions(options[])Fluent setters — each returns a new endpoint
EndpointparsePort(host, raw)Validate a port value (1–65535); junk is refused naming the endpoint
Configload(path)Load endpoints from YAML/JSON (format auto-detected)
Configparse(raw, hintPath)Parse config text directly (extension hint, else JSON when the payload opens with [ or {)
ConfigimportFromSshConfig(path)Import endpoints from ~/.ssh/config
Pickerpick(endpoints)Interactive selection (null on cancel or empty endpoint list)
Launcher__construct(executor)Optional callable executor seam for embedding and tests
Launcherdispatch(endpoint, binary)pcntl_exec handoff — never returns on success; the default executor throws a RuntimeException naming the binary when exec fails

Demos.

VHS-recorded GIF of the endpoint picker, regenerated automatically on every push that touches the source.

The endpoint picker listing three hosts under the wishlist banner while a typed filter narrows the list

Picker

Type-filtered SSH endpoint picker — Enter to launch.