Command Snippets

Save frequently used commands and run them on one host, a selection or all visible hosts at once. Snippets are stored in ~/.purple/snippets in INI format (a simple key=value configuration format with [section] headers).

Running snippets

From the host list, press r to run a snippet on the selected host. To run on multiple hosts, select them first with Ctrl+Space, then press r. Press R to run on all visible hosts (respecting the current search filter).

Key	Action
r	Run snippet on selected host(s)
R	Run snippet on all visible hosts
Ctrl+Space	Select / deselect host (multi-select)

This opens the snippet picker where you choose which command to run.

Snippet picker

Key	Action
j / k	Navigate
Enter	Run snippet (captured output)
!	Run snippet (raw terminal mode)
/	Search snippets
a	Add snippet
e	Edit snippet
d	Delete snippet (confirms first)
PgDn / PgUp	Page down / up
q / Esc	Back

Execution modes

• Enter runs the snippet with captured output. Stdout and stderr are collected and shown in a scrollable panel with per-host headers
• ! runs in raw terminal mode. The TUI is paused and the SSH session gets direct terminal access (stdin/stdout are passed through to the remote command). Useful for interactive commands like top or vim

Multi-host execution runs sequentially by default.

Snippet output

After running a snippet, the output panel shows results per host:

Key	Action
j / k	Scroll
g / G	Jump to top / bottom
n / N	Next / previous host output
c	Copy output
PgDn / PgUp	Page down / up
Ctrl+C	Cancel execution (first press cancels, second press force-closes)
q / Esc	Close

Parameterized snippets

Use {{name}} for a required parameter or {{name:default}} for one with a default value.

grep {{pattern}} {{file:/var/log/syslog}}   # two params, one with default
docker logs {{container}}                    # required param, no default

When you run a parameterized snippet, a form appears in the TUI where you fill in the values. A live preview of the resolved command is shown at the bottom. Values are shell-escaped automatically using POSIX single-quote escaping ('value', with internal single quotes escaped as '\'') to prevent command injection (where user input could be interpreted as shell commands).

How execution works

When you run a snippet, purple executes ssh -F <config_path> -o ConnectTimeout=10 <alias> <command> for each target host. Output (stdout and stderr) is captured and displayed in the scrollable output panel. The connection timeout is set to 10 seconds to avoid hanging on unreachable hosts.

If a host has a password source configured, purple sets up the SSH_ASKPASS environment variables automatically during snippet execution, using the same mechanism as regular connections.

CLI alternative

The CLI provides the same functionality for scripting and automation:

purple snippet add check-disk "df -h" --description "Check disk usage"
purple snippet add uptime "uptime"
purple snippet run check-disk myserver             # run on single host
purple snippet run check-disk --tag prod           # run on all hosts with tag
purple snippet run check-disk --all                # run on all hosts
purple snippet run check-disk --all --parallel     # run concurrently (max 20)
purple snippet list                                # list all snippets
purple snippet remove check-disk                   # remove a snippet

Storage format

Snippets are stored as INI sections with command and optional description fields:

[check-disk]
command=df -h
description=Check disk usage

[uptime]
command=uptime

The file is written atomically (writes to a temporary file first, sets permissions to owner-only with chmod 600, then renames into place) to prevent corruption if purple crashes mid-write. Snippet names cannot be empty, contain #, [, ] or control characters. Commands cannot be empty or contain control characters (tabs are allowed).