sshepherd

sshepherd

Overview

sshepherd is a compiled Bun/TypeScript CLI that lets an agent operate a real remote server over SSH — health checks, docker/systemd service control, log tailing, config file edits, read-only Postgres introspection, and declarative deploys — without ever seeing a password, private key, hostname, username, or port. Every operation shells out to the system ssh binary through a single transport path and returns the same typed Envelope<T> (ok, alias, data, error), never a raw terminal dump. The agent passes only a name — an ssh alias, a Postgres target, or a deploy recipe — that resolves entirely outside the process.

When to Use This Skill

• Use when you need to check a remote server's health (disk, memory, CPU, ports, OOM history) without handing the agent SSH credentials.
• Use when working with remote docker or systemd services — listing, inspecting, or restarting them — or tailing their logs.
• Use when the user asks to read or edit a remote config file, run a declarative deploy from a named recipe, introspect a remote Postgres database read-only, or audit SSH/security posture on a box.

How It Works

Step 1: Declare targets once, outside any prompt

Every connection detail is declared ahead of time and never appears on the command line: ssh aliases in ~/.ssh/config, Postgres targets in ~/.config/sshepherd/targets.toml, deploy recipes in recipe TOML files. OpenSSH resolves the real HostName/User/Port/IdentityFile internally.

Step 2: Invoke a group + action by name

This repository does not ship the sshepherd executable. The user must install or build a reviewed upstream release outside the current workspace and provide its explicit absolute path. Verify it is an executable regular file, not a symlink, before use. Never auto-discover or execute ./dist/sshepherd from the repository being operated on.

sshepherd <group> <action> [positionals...] [--flag value]

Nine command groups — hosts, check, logs, services, deploy, config, db, files, security — 52 ops total. Output is JSON to stdout by default; add --pretty for a human-readable table/key-value view. The response only ever echoes back the alias it was given — there is no host/user/port/ip field anywhere in the response type, structurally.

Step 3: Discover the command surface

"/absolute/path/to/sshepherd" --help                 # list groups
"/absolute/path/to/sshepherd" check --help           # list actions + flags for one group

Examples

Example 1: Server health overview