remmina-mac/docs/USAGE.md

Usage

Layout (Remmina-style)

• Left: group dropdown, search, profile list. Right-click: Connect / Duplicate / Edit / Delete. Double-click connects.
• Right: tabs for open sessions + connection details (copyable command) + info box.
• Bottom: status bar with profile/session counts.
• Toolbar: + New, pencil Edit, copy Duplicate, key SSH keys, ⓘ About, ▶ Connect, ⚡ Quick-Connect.

Creating a profile

1. + → name, group, protocol (SSH/SFTP/RDP/VNC), host, port, username, password right below (check Keychain to save it).
2. The editor warns live about common mistakes: user@host in the host field, ssh:// prefix, whitespace, empty username, invalid port. Values are trimmed on save.
3. Pick an SSH key (optional, section below — import it first via the key icon).
4. Save → stored immediately in profiles.json.
5. If a connection fails: red banner → Copy report and send it in for debugging (contains no password).

Connecting

• Select a profile → ▶ Connect or double-click.
• SSH/SFTP: full terminal tab (SwiftTerm, Dracula theme). Flow: TCP pre-check (wrong port/host → instant plain-language message instead of a cryptic exit code) → host-key fingerprint popup on first connect → auto-connect. Type directly in the terminal: Tab completion, arrows, Ctrl+C, copy/paste, scrollback, vim/htop all work. Buttons: Disconnect/Reconnect, Clear, Close tab. On failure: red banner with last message + Diagnose button.
• Alternative: Open in Terminal.app (opens a .command file, no automation permission needed) or Copy command.
• RDP: launches xfreerdp (if present) or opens Microsoft Remote Desktop.
• VNC: opens vnc://host:port.

Managing SSH keys (key icon)

• Import from ~/.ssh: picks up all private keys (skips *.pub, known_hosts, config).
• Choose…: file picker for a key file.
• Generate new key: runs /usr/bin/ssh-keygen -t ed25519 -f ~/.ssh/remminamac_<timestamp>.
• Passphrase → Keychain (sshkey-<UUID>).

Host-key verification (popup)

• On first connect the app shows a popup with the SHA256/MD5 fingerprint (fetched via ssh-keyscan) — compare it with Terminal output or the server admin's value, then Accept & connect (stored in ~/.ssh/known_hosts, shared with Terminal.app).
• On CHANGED key: red warning (possible MITM!) — only replace if expected (freshly provisioned server). Manual reset: ssh-keygen -R HOST.
• Tech note: Sources/ctty-run/ctty-run.c gives ssh a controlling terminal (without it all interactive prompts fail silently).

Saving passwords & auto-login

• Profile editor: enter password + check Keychain. A saved password is indicated (✓) and can be deleted. profiles.json holds only the reference, never the password.
• Order at connect time: profile password first, key passphrase second.
• Auto-login without typing: needs sshpass (brew install sshpass). ssh logs in with the Keychain secret (password only in the SSHPASS process env, never on the command line or in logs). Status shows auto-login state.
• Without sshpass: password/key passphrase is asked interactively in the terminal.

Quick-Connect

• With selection: connects directly. Without: opens the editor with a “Quick-Connect” template.

Export / Import (manual until GUI buttons land)

PROFILE_DIR=~/Library/Application\ Support/RemminaMac
cp "$PROFILE_DIR/profiles.json" ~/Desktop/remminamac-backup.json
# Import:
cp ~/Desktop/remminamac-backup.json "$PROFILE_DIR/profiles.json"