mtm-ssh-menu/README.md

mtm-ssh-menu

A Bun/TypeScript SSH target picker built around fzf and YAML configuration.

What it does

• Lists SSH targets from grouped YAML files
• Uses the group value from each YAML file as the displayed group name
• Allows the YAML file name to differ from the group name
• Supports global defaults for user, port, and jump hosts
• Supports per-host overrides
• Can also browse entries from ~/.ssh/known_hosts
• Launches ssh directly from the selected entry

Requirements

• bun
• ssh
• fzf

Usage

./mtm-ssh-menu [--config-dir DIR] [-k [user]]

The usage shown by the script is sshm [--config-dir DIR] [-k [user]].

Options:

• -h, --help: show help
• -c, --config-dir DIR: use a custom configuration directory
• -k, --known-hosts [user]: include hosts from ~/.ssh/known_hosts and optionally set the user
• When -k is used without a user, the selected entry uses root

By default, the script reads configuration from:

• ~/.config/mtm-ssh-menu/global.yaml
• ~/.config/mtm-ssh-menu/hosts/*.yaml

Configuration format

global.yaml

ssh:
  default_user: root
  default_port: 22
  default_options: ""
  jump_hosts:
    office: "user@192.168.10.11"
    dev: "user@192.168.10.11:2222"
    backup: "admin@10.0.0.5:2200"

hosts/01_prod.yaml

group: prod
servers:
  - name: web-1
    aliases:
      - frontend
      - web
    host: web-1.prod.internal
    jump_host: office

  - name: db-1
    aliases:
      - database
      - sql
    host: 10.0.0.20
    jump_host: office

hosts/02_staging.yaml

group: staging
servers:
  - name: app-1
    aliases:
      - app
      - application
    host: staging-app.example.com
    user: ubuntu
    port: 22
    ssh_options: ""

  - name: worker-1
    aliases:
      - worker
    host: 10.20.0.15
    user: ubuntu
    port: 22

hosts/03_dev.yaml

group: dev
servers:
  - name: api-1
    aliases:
      - api
      - backend
    host: 192.168.10.11
    user: dev
    port: 2222

  - name: web-1
    aliases:
      - frontend
      - ui
    host: 192.168.10.12
    user: dev
    port: 22

The file name does not need to match the group value. The script reads the group from the YAML content and uses the file path internally to load the selected host.

The sample configuration uses numbered file names: 01_prod.yaml, 02_staging.yaml, and 03_dev.yaml.

Each host entry can define:

• name
• aliases
• host
• user
• port
• jump_host

Sample configuration

A complete sample configuration is available in sample-config/.

Notes

• jump_host values are resolved by name from global.yaml.
• Jump hosts support user@host and user@host:port; if the port is omitted, 22 is used.
• If a host does not define a user or port, global defaults are used.
• default_options is consumed for hosts that do not define their own options, and is appended as raw SSH options.
• ssh_options appears in the sample config but is not used by the current script; only options is read.
• Sample host examples are stored as sample-config/hosts/01_prod.yaml, 02_staging.yaml, and 03_dev.yaml.
• The group key is required for each host config file; the file name is only an internal storage detail.
• When -k is used, entries from known_hosts are shown with the selected user or root by default.
• Known-host entries always use port 22.
• known_hosts entries use port 22.
• The script is implemented in Bun and launches fzf plus ssh from a parsed YAML configuration.
• The current implementation builds the final SSH command as a string and executes it through Bun.
• The script name shown in usage is sshm, while the repository file is mtm-ssh-menu.