sshepherd

Visão Geral

sshepherd é uma CLI compilada em Bun/TypeScript que permite que um agente opere um servidor remoto real via SSH — verificações de integridade, controle de serviços docker/systemd, rastreamento de logs, edição de arquivos de configuração, introspecção Postgres somente leitura e implantações declarativas — sem nunca ver uma senha, chave privada, nome de host, nome de usuário ou porta. Cada operação é executada no binário ssh do sistema através de um único caminho de transporte e retorna o mesmo Envelope<T> tipado (ok, alias, data, error), nunca um dump de terminal bruto. O agente passa apenas um nome — um alias SSH, um alvo Postgres ou uma receita de implantação — que é resolvido inteiramente fora do processo.

Quando Usar Esta Habilidade

• Use quando precisar verificar a integridade de um servidor remoto (disco, memória, CPU, portas, histórico de OOM) sem fornecer credenciais SSH ao agente.
• Use ao trabalhar com serviços remotos docker ou systemd — listando, inspecionando ou reiniciando-os — ou rastreando seus logs.
• Use quando o usuário pedir para ler ou editar um arquivo de configuração remoto, executar uma implantação declarativa a partir de uma receita nomeada, inspecionar um banco de dados Postgres remoto somente leitura ou auditar a postura de segurança/SSH em uma máquina.

Como Funciona

Passo 1: Declare os alvos uma vez, fora de qualquer prompt

Todos os detalhes de conexão são declarados com antecedência e nunca aparecem na linha de comando: aliases SSH em ~/.ssh/config, alvos Postgres em ~/.config/sshepherd/targets.toml, receitas de implantação em arquivos TOML de receita. O OpenSSH resolve internamente o HostName/User/Port/IdentityFile real.

Passo 2: Invoque um grupo + ação por nome

Este repositório não envia o executável sshepherd. O usuário deve instalar ou compilar uma versão upstream revisada fora do espaço de trabalho atual e fornecer seu caminho absoluto explícito. Verifique se é um arquivo regular executável, não um link simbólico, antes de usar. Nunca descubra ou execute automaticamente ./dist/sshepherd do repositório que está sendo operado.

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

Nove grupos de comandos — hosts, check, logs, services, deploy, config, db, files, security — 52 operações no total. A saída é JSON para stdout por padrão; adicione --pretty para uma visualização de tabela/chave-valor legível por humanos. A resposta apenas ecoa de volta o alias que foi dado — não há campo de host/usuário/porta/ip em nenhum lugar do tipo de resposta, estruturalmente.

Passo 3: Descubra a superfície de comando

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

Exemplos

Exemplo 1: Visão geral da integridade do servidor

"/absolute/path/to/sshepherd" check overview lms-server

Retorna um envelope JSON com disco, memória, CPU, portas de escuta e histórico de OOM para o host por trás do alias lms-server — o agente nunca descobre o endereço do host.

Exemplo 2: Reiniciar um serviço docker e rastrear seus logs

"/absolute/path/to/sshepherd" services restart lms-server --name api
"/absolute/path/to/sshepherd" logs tail lms-server --name api --lines 100

Exemplo 3: Introspecção Postgres somente leitura

"/absolute/path/to/sshepherd" db tables prod

prod é um nome de alvo pg que se resolve para como alcançar psql em um host — nunca uma senha de banco de dados. psql é executado dentro do contêiner de destino, autenticado por peer/trust/.pgpass já no remoto.

Melhores Práticas

• ✅ Declare cada alias/alvo/receita com antecedência em ~/.ssh/config / targets.toml / TOML de receita — nunca incorpore detalhes de conexão.
• ✅ Passe apenas nomes (alias, alvo pg, receita) para a CLI; deixe o OpenSSH gerenciar a autenticação.
• ✅ Use --pretty para revisão humana e saída JSON padrão para análise de máquina.
• ❌ Não tente injetar um nome de host, usuário, porta ou senha em um comando — a CLI não tem campo para eles.
• ❌ Não use a biblioteca npm ssh2 ou SSH feito manualmente; o objetivo é delegar ao binário ssh do sistema confiável.

Limitações

• Esta habilidade não substitui a validação específica do ambiente, testes ou revisão de especialistas.
• Pare e peça esclarecimentos se os inputs, permissões ou limites de segurança necessários estiverem faltando.
• Requer o cliente OpenSSH do sistema e aliases/alvos/receitas pré-declarados; não pode se conectar a um host que não foi configurado fora do agente.
• O acesso Postgres é introspecção somente leitura por design.

Notas de Segurança e Proteção

…