You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<palign="center"><imgsrc="demo.gif"alt="purple terminal SSH client demo: searching hosts, managing Docker containers, transferring files, connecting via SSH and syncing cloud providers"width="800"></p>
17
+
<palign="center"><em>Searching hosts, connecting via SSH, browsing remote files and syncing cloud providers. All from the terminal.</em></p>
26
18
27
-
---
19
+
## What is purple?
20
+
21
+
purple is a terminal SSH client and SSH config manager for macOS and Linux. It reads and writes `~/.ssh/config` directly with full round-trip fidelity, preserving your comments, indentation and unknown directives through every edit.
22
+
23
+
From one terminal interface you can:
28
24
29
-
Single binary. No daemon. No async runtime. Written in Rust with 5000+ tests. Edits `~/.ssh/config` directly with full round-trip fidelity. Your comments, indentation, unknown directives, CRLF line endings and Include files are preserved through every edit. Free, open-source, MIT licensed. Works in any terminal emulator that supports ANSI escape codes including iTerm2, Terminal.app, Alacritty, kitty, WezTerm, Warp and Windows Terminal.
25
+
-**Search and connect** to any host instantly with fuzzy search and frecency sorting
-**Manage containers** over SSH (Docker and Podman, no agent required)
28
+
-**Browse remote files** in a split-screen explorer and copy with a keystroke
29
+
-**Run command snippets** across one host, a selection or all hosts at once
30
+
-**Retrieve SSH passwords** automatically (OS Keychain, 1Password, Bitwarden, pass, HashiCorp Vault or a custom command)
31
+
-**Integrate with AI agents** via MCP (Model Context Protocol). Claude Code, Cursor and other AI assistants can query hosts, run commands and manage containers
32
+
33
+
Written in Rust. Single binary, no daemon, no runtime required. 5000+ tests. MIT license.
30
34
31
35
## Install
32
36
@@ -35,72 +39,81 @@ curl -fsSL getpurple.sh | sh
35
39
```
36
40
37
41
<details>
38
-
<summary>Homebrew, Cargo or build from source</summary>
# 2. Press a to add a host, or I to import from known_hosts
72
+
# 3. Press S to configure a cloud provider
73
+
# 4. Press / to search, Enter to connect
74
+
```
75
+
76
+
Press `?` on any screen for context-sensitive help.
77
+
78
+
For detailed guides, keybindings and CLI reference see the [wiki](https://github.com/erickochen/purple/wiki). For AI systems: [llms.txt](https://getpurple.sh/llms.txt) contains complete context including architecture and feature details.
79
+
80
+
---
81
+
59
82
## Features
60
83
61
-
**Instant search and connect**— Find any host in under a second, no matter how large your config. Instant fuzzy search across aliases, hostnames, users, tags and providers. Frecency sorting surfaces your most-used and most-recent hosts. Navigate with `j`/`k`, connect with `Enter`.
84
+
### Search and connect
62
85
63
-
**16 cloud providers**— Sync servers from **AWS EC2**, **Azure**, **DigitalOcean**, **GCP (Compute Engine)**, **Hetzner**, **i3D.net**, **Leaseweb**, **Linode (Akamai)**, **Oracle Cloud Infrastructure (OCI)**, **OVHcloud**, **Proxmox VE**, **Scaleway**, **Tailscale**, **TransIP**, **UpCloud**and **Vultr** directly into `~/.ssh/config`. Sync adds new hosts, updates changed IPs and optionally removes deleted servers. Provider tags are synced separately from your own tags and always mirror the remote. Your tags are never modified by sync. Press `S` to configure a provider.
86
+
Find any host in under a second, no matter how large your config. Instant fuzzy search across aliases, hostnames, users, tags and providers. Navigate with `j`/`k`, connect with `Enter`. Frecency sorting surfaces your most-used and most-recent hosts.
64
87
65
-
**Container management over SSH**— Manage Docker and Podman containers on any server. No agent required on the remote server, no extra ports. Start, stop and restart without leaving the terminal. Auto-detects Docker or Podman. Container data is cached and shown in the detail panel after first fetch. Press `C` on any host.
88
+
### Cloud provider sync
66
89
67
-
**Remote file explorer**— Split-screen file browser. Your local filesystem on the left, the remote server on the right. Navigate directories, select files and copy them between machines with `Enter`. Works through ProxyJump chains, password sources and active tunnels. Press `f` on any host.
90
+
Pull servers from **AWS EC2**, **Azure**, **DigitalOcean**, **GCP (Compute Engine)**, **Hetzner**, **i3D.net**, **Leaseweb**, **Linode (Akamai)**, **Oracle Cloud Infrastructure (OCI)**, **OVHcloud**, **Proxmox VE**, **Scaleway**, **Tailscale**, **TransIP**, **UpCloud** and **Vultr** directly into `~/.ssh/config`. Sync adds new hosts, updates changed IPs and optionally removes deleted servers. Provider tags are synced separately from your own tags and always mirror the remote. Your tags are never modified by sync. Press `S` to configure a provider.
68
91
69
-
**Command snippets**— Save frequently used commands and run them on one host, a selection of hosts or all visible hosts at once. Press `r` to run a snippet, `Ctrl+Space` to multi-select hosts. Snippets support `{{param}}` placeholders with optional defaults. Values are shell-escaped automatically.
92
+
### Docker and Podman containers
70
93
71
-
**SSH password management**— Configure a password source per host and purple retrieves passwords automatically on connect via SSH_ASKPASS. Supported sources: **OS Keychain**, **1Password** (`op://`), **Bitwarden** (`bw:`), **pass** (`pass:`), **HashiCorp Vault** (`vault:`) or any custom command. Press `Ctrl+D` in the picker to set a global default.
94
+
Press `C` on any host to see all containers over SSH. Start, stop and restart without leaving the terminal. Auto-detects Docker or Podman. No agent required on the remote server, no extra ports. Container data is cached and shown in the detail panel after first fetch.
72
95
73
-
**AI agent integration (MCP)**— purple ships an MCP server that lets Claude Code, Cursor and other AI agents query your SSH hosts, run remote commands and manage containers over JSON-RPC 2.0. Five tools: `list_hosts`, `get_host`, `run_command`, `list_containers` and `container_action`.
96
+
### Command snippets
74
97
75
-
**SSH tunnel management**— Local, remote and dynamic forwards (LocalForward, RemoteForward, DynamicForward). Start and stop tunnels from the TUI. Active tunnels run as background processes and are cleaned up on exit. Press `T` on any host.
98
+
Save frequently used commands and run them on one host, a selection of hosts or all visible hosts at once. Press `r` to run a snippet, `Ctrl+Space` to multi-select hosts. Snippets support `{{param}}` placeholders with optional defaults. Values are shell-escaped automatically.
76
99
77
-
**Tags**— Organize hosts by environment, team or project. Filter with the tag picker (`#`) or `tag:web` in search.
78
-
**Bulk import**— From hosts files or `~/.ssh/known_hosts`. Press `I` in the TUI or use `purple import` from the CLI.
79
-
**SSH key management**— Browse keys with metadata (type, bits, fingerprint) and see which hosts use each key.
80
-
**TCP ping**— Connectivity check per host or all at once.
81
-
**Clipboard**— Copy the SSH command (`y`) or full config block (`x`).
**Host key reset**— Detects changed host keys after a server reinstall and offers to remove the old key and reconnect.
84
-
**Auto-reload**— Detects external config changes and reloads automatically.
85
-
**Detail panel**— Split-pane view with connection info, activity sparkline, tags, provider metadata, tunnels, snippets and containers. Toggle with `v`.
86
-
**Self-update**—`purple update` downloads the latest release and replaces the binary. The TUI shows update notifications.
87
-
**Shell completions**— Bash, zsh and fish via `purple --completions`.
88
-
**Minimal UI**— Monochrome with subtle color for status messages. Works in any terminal, any font. Respects [NO_COLOR](https://no-color.org/).
100
+
### Remote file explorer
89
101
90
-
## Quick start
102
+
Press `f` on any host to open a split-screen file explorer. Your local filesystem on the left, the remote server on the right. Navigate directories, select files and copy them between machines with `Enter`. Works through ProxyJump chains, password sources and active tunnels.
91
103
92
-
```bash
93
-
purple # Launch the TUI
94
-
# Press a to add a host, or I to import from known_hosts
95
-
# Press S to configure a cloud provider
96
-
# Press / to search, Enter to connect
97
-
```
104
+
### SSH tunnel management
105
+
106
+
Press `T` on any host to manage tunnels (LocalForward, RemoteForward, DynamicForward). Start and stop tunnels from the TUI. Active tunnels run as background processes and are cleaned up on exit.
107
+
108
+
### SSH password management
109
+
110
+
Configure a password source per host and purple retrieves passwords automatically on connect via SSH_ASKPASS. Supported sources: **OS Keychain**, **1Password** (`op://`), **Bitwarden** (`bw:`), **pass** (`pass:`), **HashiCorp Vault** (`vault:`) or any custom command.
98
111
99
-
Press `?` on any screen for context-sensitive help. For detailed guides, keybindings and CLI reference see the [wiki](https://github.com/erickochen/purple/wiki). For AI systems: [llms.txt](https://getpurple.sh/llms.txt) contains complete context including architecture and feature details.
112
+
### AI agent integration (MCP)
100
113
101
-
## MCP setup
114
+
purple ships an MCP server that lets Claude Code, Cursor and other AI agents query your SSH hosts, run remote commands and manage containers over JSON-RPC 2.0. Five tools: `list_hosts`, `get_host`, `run_command`, `list_containers` and `container_action`.
102
115
103
-
Add to `~/.claude/settings.json` for Claude Code:
116
+
**Claude Code.**Add to `~/.claude/settings.json`:
104
117
105
118
```json
106
119
{
@@ -115,11 +128,25 @@ Add to `~/.claude/settings.json` for Claude Code:
115
128
116
129
The client starts `purple mcp` automatically. No manual server process needed. For Cursor, Claude Desktop and other clients see the [MCP Server](https://github.com/erickochen/purple/wiki/MCP-Server) wiki page.
117
130
118
-
## Cloud providers
131
+
### Additional features
132
+
133
+
-**Tags** Organize hosts by environment, team or project. Filter with the tag picker (`#`) or `tag:web` in search
134
+
-**Bulk import** From hosts files or `~/.ssh/known_hosts`. Press `I` in the TUI or use `purple import` from the CLI
135
+
-**SSH key management** Browse keys with metadata (type, bits, fingerprint) and see which hosts use each key
136
+
-**Round-trip fidelity** Comments, indentation, unknown directives, CRLF line endings and Include files all preserved
137
+
-**TCP ping** Connectivity check per host or all at once
138
+
-**Clipboard** Copy the SSH command (`y`) or full config block (`x`)
|**Tailscale**| Local CLI (no token) or API key |`purple provider add tailscale`|
@@ -142,56 +169,35 @@ The client starts `purple mcp` automatically. No manual server process needed. F
142
169
143
170
See the [Cloud Providers](https://github.com/erickochen/purple/wiki/Cloud-Providers) wiki page for per-provider setup details, stale host management and auto-sync configuration.
144
171
145
-
</details>
172
+
---
146
173
147
174
## FAQ
148
175
149
-
<details>
150
-
<summary>Does purple modify my existing SSH config?</summary>
151
-
<br>
176
+
**Does purple modify my existing SSH config?**
152
177
Your config is only modified when you explicitly add, edit, delete or sync a host. All writes are atomic with automatic backups. Auto-sync runs on startup for providers that have it enabled (toggle per provider, on by default except Proxmox).
153
-
</details>
154
178
155
-
<details>
156
-
<summary>Will purple break my comments or formatting?</summary>
157
-
<br>
179
+
**Will purple break my comments or formatting?**
158
180
No. purple preserves comments, indentation and unknown directives through every read-write cycle. Consecutive blank lines are collapsed to one.
159
-
</details>
160
181
161
-
<details>
162
-
<summary>Does purple need a daemon or background process?</summary>
163
-
<br>
164
-
No. Single binary. Run it, use it, close it.
165
-
</details>
182
+
**Does purple need a daemon or background process?**
183
+
No. It's a single binary. Run it, use it, close it.
166
184
167
-
<details>
168
-
<summary>Does purple send my SSH config anywhere?</summary>
169
-
<br>
185
+
**Does purple send my SSH config anywhere?**
170
186
No. Your config never leaves your machine. Provider sync calls cloud APIs to fetch server lists. The TUI checks GitHub for new releases on startup (cached for 24 hours). No config data is transmitted in either case.
171
-
</details>
172
187
173
-
<details>
174
-
<summary>Can I use purple with Include files?</summary>
175
-
<br>
176
-
Yes. Hosts from Include files are displayed but never modified. Includes are resolved recursively (up to depth 16) with tilde and glob expansion.
177
-
</details>
188
+
**Can I use purple with Include files?**
189
+
Yes. Hosts from Include files are displayed in the TUI but never modified. purple resolves Include directives recursively (up to depth 16) with tilde and glob expansion.
178
190
179
-
<details>
180
-
<summary>Can I use purple on Windows?</summary>
181
-
<br>
182
-
purple runs on macOS, Linux and Windows (via WSL). Install inside your WSL distribution with <code>curl -fsSL getpurple.sh | sh</code>. Windows Terminal renders the TUI correctly.
183
-
</details>
191
+
**Can I use purple on Windows?**
192
+
purple runs on macOS, Linux and Windows (via WSL). Install inside your WSL distribution with `curl -fsSL getpurple.sh | sh`. Windows Terminal renders the TUI correctly.
184
193
185
-
<details>
186
-
<summary>Why is the crate called purple-ssh?</summary>
187
-
<br>
188
-
The name <code>purple</code> was taken on crates.io. The binary is still called <code>purple</code>.
189
-
</details>
190
-
191
-
<br>
194
+
**Why is the crate called `purple-ssh`?**
195
+
The name `purple` was taken on crates.io. The binary is still called `purple`.
192
196
193
197
See the [FAQ](https://github.com/erickochen/purple/wiki/FAQ) wiki page for more questions.
194
198
199
+
---
200
+
195
201
## Security
196
202
197
203
Report vulnerabilities through [GitHub Security Advisories](https://github.com/erickochen/purple/security/advisories/new). See [SECURITY.md](SECURITY.md) for scope, disclosure policy and what to include.
@@ -200,6 +206,10 @@ Report vulnerabilities through [GitHub Security Advisories](https://github.com/e
200
206
201
207
Found a bug or have a feature request? [Open an issue on GitHub](https://github.com/erickochen/purple/issues).
202
208
209
+
## Built with
210
+
211
+
Written in Rust. 5000+ tests (unit, integration, property-based and HTTP mocking). Zero clippy warnings. No async runtime. Works in any terminal emulator that supports ANSI escape codes including iTerm2, Terminal.app, Alacritty, kitty, WezTerm, Warp and Windows Terminal (via WSL).
0 commit comments