Skip to content

Getting Started

Jump to bottom
Eric Kochen edited this page Sep 17, 2026 · 20 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.

After an upgrade

When you upgrade to a newer version, purple shows a sticky toast inviting you to press n to see what's new. The What's New overlay lists recent releases with feature, change and fix bullets per version. See Whats New for the full behaviour, or run purple whats-new from the CLI.

Adding hosts

From the TUI

Press a to open the add host form. The form starts with just two fields: name (a short alias you use to connect, e.g. webserver) and hostname (IP address or domain name). Press Enter to save, or press Tab / Down from the hostname field to expand the form and set optional fields like user, port, SSH key and password source.

Multi-alias Host lines

If your SSH config uses multi-alias Host lines like Host web-01 web-01.prod, purple lists each alias separately but keeps them bound. Edit, rename or delete from any alias and the shared directives survive. See Host Patterns#multi-alias-host-lines.

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. Separate words with spaces to require all of them, in any order.

  • web prod - match both terms, in any field and any order
  • tag:web - substring 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)

purple runs the system ssh for the login. See Getting Started#using-a-different-ssh-command to swap in a wrapper such as kitty's kitten ssh.

Using a different ssh command

purple can run another program instead of ssh for interactive logins. Any wrapper that accepts ssh's own arguments works: kitty's kitten ssh, sshpass -f <file> ssh, a company wrapper script. purple appends -F ~/.ssh/config -- <alias> (and -t <command> for container shells) after the words you configure.

Two ways to set it, the environment variable wins:

  • Per terminal with PURPLE_SSH_COMMAND. For kitty, add this line to kitty.conf and restart kitty, so the wrapper is only used inside kitty:

    env PURPLE_SSH_COMMAND=kitten ssh

  • Everywhere with a line in ~/.purple/preferences:

    ssh_command=kitten ssh

Quote a path with spaces: ssh_command="/Applications/kitty.app/Contents/MacOS/kitten" ssh. Extra flags stay attached: ssh_command=kitten ssh --kitten interpreter=python.

What it covers: Enter on a host, container shells from the Containers tab and the command copied with y. What stays on plain ssh: tunnels, snippets, key push, file transfer and the MCP server, since wrappers like kitten need an interactive terminal.

Check it works: connect with Enter. With purple --verbose the log shows ssh launcher from PURPLE_SSH_COMMAND: kitten ssh. An unparseable value (unbalanced quote) is logged and ignored, so plain ssh keeps working. Kitty notes: kitten must be on your PATH (kitty installs it next to kitty), it only runs inside a kitty window and inside tmux it depends on tmux passing kitty's escape codes through.

Using an alternate config

purple --config ~/other/ssh_config

Where purple keeps its files

Your hosts live in ~/.ssh/config. Everything else purple writes falls into four categories, following the XDG Base Directory specification:

Category Files Default Override XDG
config preferences, snippets, providers, themes/ ~/.purple PURPLE_CONFIG_DIR $XDG_CONFIG_HOME/purple
data certs/, config.original ~/.purple PURPLE_DATA_DIR $XDG_DATA_HOME/purple
state history.tsv, recents.json, key_activity.json, snippet_runs.json, sync_history.tsv, purple.log, mcp-audit.log, .askpass_* ~/.purple PURPLE_STATE_DIR $XDG_STATE_HOME/purple
cache container_cache.jsonl, last_version_check ~/.purple PURPLE_CACHE_DIR $XDG_CACHE_HOME/purple

Each category resolves on its own, highest wins: the PURPLE_*_DIR override when set, then $XDG_*_HOME/purple when that variable is set to an absolute path, else ~/.purple. Set only XDG_CONFIG_HOME and only the config files move; state, data and cache stay in ~/.purple until you set their variables too. Without any of these variables nothing changes.

The first time a category resolves outside ~/.purple, purple copies that category's files into the new directory (directories mode 0700, file modes kept), as long as the new directory holds none of them yet. A category is copied as a whole: if one file fails, purple removes what it copied for that category, logs the failure and tries again on the next start. ~/.purple stays as it is, so unsetting the variables rolls you back. Once you are happy, remove ~/.purple yourself. Hosts that already carry a CertificateFile pointing into ~/.purple/certs keep using that path; edit the directive if you want those certs to move too.

purple logs prints the resolved log path and the startup banner in that log lists all four directories.

Navigating the TUI

Key Action
j / k Navigate down and up
PgDn / PgUp Page down / up
/ Search the current tab
: Find any host, tunnel, container, snippet or action by name. See Jump
Enter Connect
Tab / Shift+Tab Cycle to next / previous top tab (Hosts -> Tunnels -> Containers -> Keys -> Hosts)
? Help (context-sensitive)
q Quit
Esc Cancel selection, search or group filter. Never quits; the first idle press surfaces a one-shot toast pointing to q

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