dial/dial-brief.md

Project Brief: Interactive SSH Host Picker CLI ("dial")

Overview

A fast, interactive command-line tool that reads ~/.ssh/config, lets the user fuzzy-select a host, and execs the system ssh binary into it. Cross-platform (macOS Apple Silicon/M4, Linux, Windows). Optional YubiKey gate before the app will run. App-specific data lives inside the .ssh tree so it rides along on existing Syncthing sync across machines.

Goals

• Parse ~/.ssh/config, including Include directives.
• Present an interactive, fuzzy-searchable list of Host entries.
• On selection, exec the real ssh binary (not a wrapped subprocess) so the terminal/tty, ProxyJump, agent forwarding, etc. all just work.
• Cold start fast enough to feel instant (target: comfortably under 100ms).
• Ship as a single static binary per platform — no runtime dependency.
• Optional YubiKey challenge-response gate required before the picker unlocks.
• Store app data (recents, favorites, tags, settings) under ~/.ssh/ so it syncs automatically via the existing Syncthing setup — no new sync config needed.

Core Features

1. Config parsing

   • Read ~/.ssh/config, follow Include lines.
   • Surface Hostname, User, Port, ProxyJump as preview info.
   • Optional lightweight tagging via comment convention, e.g. # tag: prod, riedel above a Host block — used for filtering/grouping.
   • Never write to ~/.ssh/config — strictly read-only.

2. Interactive picker

   • Static, numbered list — not a live fuzzy-filter-as-you-type interface. Explicitly avoid the cramped/fuzzy-filter style seen in tools like the rclone installer, which is hard to read in low light. Prioritize legibility: larger clear text, generous spacing between entries, high contrast, no small dense text packed together.
   • Navigate with arrow keys or number keys, enter to connect, esc to quit.
   • Optional / to jump into a search/filter mode on demand (not the default view) if the host list gets long — but the resting state should always be a clean, static, readable list.
   • Sort by most-recently-used or most-frequently-used, toggleable.
   • Show a small preview area (Hostname/User/Port/Jump host) for the highlighted entry, in equally readable, high-contrast text.

3. Connect

   • exec (or platform equivalent) into ssh <alias> so control of the terminal passes cleanly to the ssh session — this app should not remain a parent process wrapping it.

4. YubiKey gate (optional, toggle in settings)

   • HMAC-SHA1 challenge-response (YubiKey slot 2), fully offline — no internet or server dependency.
   • Implemented by shelling out to ykman (Yubico's official CLI) rather than a direct PC/SC library. Trade-off accepted: ykman (and its Python dependency) must be installed separately on every machine this runs on — this breaks the "single static binary, zero deps" goal for the YubiKey feature specifically, but keeps the implementation simple and leans on Yubico's own well-tested tool. dial should check for ykman on PATH at startup and give a clear error if it's missing.
   • Require physical touch to confirm.
   • Backup 2FA code: generate a one-time recovery code when the gate is first enabled, shown once and expected to be stored by the user somewhere separate (password manager, printed, etc.). This code lets the user in once if the YubiKey isn't available, avoiding total lockout. After use it should be invalidated/regenerated, not reusable indefinitely.

5. Sync-safe app data

   • New directory: ~/.ssh/.dial/
     • settings.json — yubikey on/off + slot, theme, sort preference, etc.
     • data.json — recents, favorites, tag cache.
   • Multiple machines may write this concurrently via Syncthing — design for that: last-write-wins is acceptable for v1, but reads should tolerate a mid-sync/partial file without crashing (e.g. read failure just falls back to defaults rather than erroring out).
   • Nothing secret is ever written here — the YubiKey secret never leaves the key itself in challenge-response mode, so there's no key material to accidentally sync.

Non-Functional Requirements

• No telemetry, no network calls (beyond ssh itself).
• Read-only with respect to ~/.ssh/config.
• Graceful degradation if no YubiKey is plugged in and the gate is enabled.
• Works identically on macOS (Apple Silicon), Linux, and Windows — including Windows' different ssh.exe path/behavior.
• Readable in low light: default view is a static list with clear, well-spaced, high-contrast text — not a dense fuzzy-search UI. This is a hard requirement, not a nice-to-have.

Recommended Tech Stack

Go — chosen over your usual Python/Bash default specifically because this needs true single-binary cross-platform distribution and fast cold start; Python's interpreter startup and packaging story (PyInstaller etc.) are a worse fit here.

• TUI: charmbracelet/bubbletea + lipgloss (or simpler: charmbracelet/huh for a lighter list-picker if a full TUI is overkill).
• SSH config parsing: kevinburke/ssh_config.
• YubiKey challenge-response: shell out to ykman (simplest, but adds an external dependency) or use a Go PC/SC library directly for a fully self-contained binary — worth deciding based on how important "zero external deps" is to you.
• Cross-compile via GOOS/GOARCH for the three targets from one machine.

Alternative: Rust would give similar performance/single-binary benefits with a steeper setup cost — mention if you'd rather Claude Code default to that instead.

Out of Scope (v1)

• Editing/managing ~/.ssh/config from within the tool.
• Remote host key (known_hosts) management.
• Any custom ssh-agent handling — rely on the OS-native ssh client already installed.

Future / v2 Considerations

Not in scope for v1, but the architecture should not preclude these — worth keeping the "select a host" logic reusable/decoupled from the "connect via ssh" action so these can be added later without a rewrite:

• SFTP file transfer: after selecting a host, an alternate action to send/receive files instead of opening a shell session.
  • Simplest version: shell out to the system sftp/scp binary, same pattern as the ssh exec flow.
  • Fuller version: an in-app file browser (source/dest picker, remote directory listing, progress) built against a Go SFTP library (e.g. pkg/sftp) rather than shelling out — should follow the same readable, high-contrast, low-light-friendly list UI as the host picker, not the cramped style of a bare sftp prompt.

Open Decisions (Claude Code should confirm before building)

• YubiKey gate: required every launch, or only after an idle timeout?
• Exact format/length of the backup recovery code, and where it should be displayed/stored on generation (e.g. printed to terminal only, once).