Skip to content

Getting Started

Jump to bottom
Eric Kochen edited this page Apr 2, 2026 · 7 revisions

Launch

purple

This opens the TUI (terminal user interface, a visual application that runs inside your terminal) with your hosts from ~/.ssh/config.

First launch

On first launch, purple shows a welcome dialog:

  • With existing hosts: shows your host count and lets you start browsing immediately
  • Without hosts but with ~/.ssh/known_hosts: shows importable host count and offers I to import directly
  • Config backup noted if created

The welcome dialog only appears once.

Adding hosts

From the TUI

Press a to open the add host form. Fill in the alias (a short name you use to connect, e.g. webserver), hostname (IP address or domain name), user, port and optionally an SSH key and password source. Press Enter to save.

Quick-add from CLI

purple add deploy@10.0.1.5:22          # user@host:port
purple add user@host --alias name       # custom alias
purple add user@host --key ~/.ssh/id_ed25519  # with key

Import from known_hosts

Press I in the TUI to import hosts from ~/.ssh/known_hosts (a file SSH maintains with fingerprints of servers you've connected to before). Or from the CLI:

purple import --known-hosts

Import from file

purple import hosts.txt

Searching

Press / to open the search bar. Type to filter hosts instantly. Search matches across aliases, hostnames, users, tags and providers.

  • tag:web - fuzzy tag filter
  • tag=prod - exact tag filter
  • Tab / Shift+Tab - next / previous result
  • Enter - connect to selected
  • Esc - cancel search

Connecting

Navigate to a host with j/k and press Enter to connect. Or from the CLI:

purple myserver            # connect if exact match, otherwise open TUI with search
purple -c myserver         # direct connect (skip the TUI)

Using an alternate config

purple --config ~/other/ssh_config

Navigating the TUI

Key Action
j / k Navigate down and up
PgDn / PgUp Page down / up
/ Search
Enter Connect
Tab / Shift+Tab Cycle group tabs (filter by provider or tag)
? Help (context-sensitive)
q / Esc Quit

Press ? on any screen to see the keybindings for that screen. See Keybindings for the full reference.

Host patterns

SSH configs often contain wildcard blocks like Host *.example.com or Host 10.30.0.* that apply settings to groups of hosts. purple shows these in a dedicated Patterns group at the bottom of the host list. Press A to add a new pattern, or use e/d/c to edit, delete and clone existing patterns. See Host Patterns for details.

Next steps

Getting started

Features

Reference

Clone this wiki locally