Command Snippets

Save frequently used commands and run them across your fleet from a dedicated Snippets tab. Snippets are stored in ~/.purple/snippets in INI format (a simple key=value configuration format with [section] headers), and every run is recorded in ~/.purple/snippet_runs.json so each snippet builds a track record.

The Snippets tab

Press Tab from the Hosts page to cycle to the Snippets tab (the order is Hosts, Tunnels, Containers, Snippets, Keys). It lists every snippet with NAME, PARAMS and DESCRIPTION columns and an animated detail panel on the right.

Key	Action
j / k ↑↓	Navigate
g / G	First / last
PgDn / PgUp	Page down / up
/	Search (scoped to snippets)
Esc	Clear filter
Enter / r	Run on hosts (captured output)
!	Run on hosts (raw terminal)
a	Add snippet
e	Edit snippet
d	Delete snippet (confirms first)
v	Toggle the detail panel

Detail panel

With the detail panel open (v), the selected snippet shows:

• Overview: the description and the snippet's default hosts
• Track record: a reliability percentage, a trend chart of past runs and the most recent outcome
• Command: the full command with parameters highlighted
• Parameters: each {{name}} placeholder and its default
• Impact: a blast-radius verdict and targeted callouts (see Impact analysis)

Running across multiple hosts

From the Snippets tab press Enter or r to run the selected snippet with captured output, or ! to run it in a live terminal. Either opens a multi-select host picker.

Key	Action
j / k ↑↓	Navigate
Space	Toggle the focused host
Space on a group header	Toggle the whole group
a / A	Select or deselect all visible hosts
/	Filter hosts (fuzzy)
Enter	Confirm (captured output)
!	Confirm (raw terminal)
Esc	Clear the filter, then leave

Hosts are grouped the same way as your host list (by provider, tag or flat), so group headers carry an aggregate checkbox. Confirming shows a dialog with the snippet name and the host count before the run starts.

Default hosts

A snippet can remember which hosts it usually targets. In the add or edit form, focus the Default hosts field and press Space to open the host picker. The next time you run the snippet those hosts come pre-selected. An empty selection clears the defaults.

Impact analysis

Before you fan a snippet out, purple analyses its command and shows a blast-radius verdict in the detail panel:

Verdict	Meaning
read-only, safe to fan out	The command only reads state
writes state on each host	The command changes state
elevated: read carefully	Runs as root, fetches remote code or similar
irreversible or takes hosts offline	Destructive or availability-impacting

It also surfaces targeted callouts, for example runs as root (sudo), fetches and runs remote code, reboots or powers off the host or may expose secrets in captured output. The analysis is static (it never runs the command), quote-aware (so echo "rm -rf" is not flagged) and recurses one level into ${...} and bash -c "..." to catch hidden payloads.

Track record

Every run is recorded with a timestamp, the host count and the success count, capped to the 30 most recent runs per snippet in ~/.purple/snippet_runs.json. The detail panel turns this into a reliability percentage (green above 90%, amber above 60%, red below), a trend chart and the last outcome, so you can judge a snippet before trusting it across a fleet. Renaming a snippet carries its history along. Deleting a snippet clears its history.

Running from the host list

Snippets also run straight from the Hosts page. Press r to run a snippet on the selected host. To run on several hosts, select them first with Space (or 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
Space / 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 in parallel from the TUI (up to 20 concurrent SSH sessions); the CLI runs hosts sequentially unless you pass --parallel.

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 a command field, an optional description and an optional hosts line that holds the default hosts (comma-separated, with commas inside an alias escaped):

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

[deploy]
command=cd /opt/{{app}} && git pull && docker compose up -d {{service:web}}
description=Pull and roll a service
hosts=prod-eu1,prod-eu2,aws-api-prod

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). Run history lives separately in ~/.purple/snippet_runs.json.