Pular para o conteúdo principal

Documentação oficial desta página · v0.20.6

Mandar a saída de um script para plataformas de mensagem

O hermes send é uma CLI pequena e scriptável que empurra uma mensagem para qualquer plataforma de mensagem que o Hermes já tenha configurada. Pense nele como um curl multiplataforma para notificações — você não precisa de um gateway rodando, não precisa de um LLM e não precisa colar de novo os tokens de bot em cada script seu.

Use para:

  • Monitoramento de sistema (memória, disco, temperatura da GPU, job longo que terminou)
  • Notificações de CI/CD (deploy concluído, teste falhando)
  • Scripts de cron que precisam te avisar dos resultados
  • Mensagens rápidas de uma vez, direto do terminal
  • Canalizar a saída de qualquer ferramenta para qualquer lugar (make | hermes send --to slack:#builds)

O comando reaproveita as mesmas credenciais e os mesmos adaptadores de plataforma que o hermes gateway já usa, então não há uma segunda superfície de configuração para manter.

Início rápido​

# Texto simples para o canal padrão de uma plataforma
hermes send --to telegram "deploy concluído"

# Canaliza a saída padrão de qualquer coisa
echo "RAM 92%" | hermes send --to telegram:-1001234567890

# Manda um arquivo
hermes send --to discord:#ops --file /tmp/relatorio.md

# Acrescenta uma linha de assunto/cabeçalho
hermes send --to slack:#eng --subject "[CI] build.log" --file build.log

# Alvo dentro de um tópico (tópico do Telegram, thread do Discord)
hermes send --to telegram:-1001234567890:17585 "resposta no tópico"

# Lista todos os alvos configurados
hermes send --list

# Filtra por plataforma
hermes send --list telegram

Referência de argumentos​

FlagDescrição
-t, --to ALVODestino. Veja formatos de alvo.
message (posicional)Texto da mensagem. Omita para ler de --file ou da entrada padrão.
-f, --file CAMINHOLê o corpo de um arquivo. --file - força a entrada padrão.
-s, --subject LINHAColoca uma linha de cabeçalho/assunto antes do corpo.
-l, --listLista os alvos disponíveis. Aceita um filtro posicional de plataforma.
-q, --quietNada na saída padrão em caso de sucesso (só o código de saída — ideal para scripts).
--jsonEmite o resultado JSON cru do envio.
-h, --helpMostra o texto de ajuda embutido.

Formatos de alvo​

FormatoExemploSignificado
platformtelegramManda para o canal padrão configurado da plataforma
platform:chat_idtelegram:-1001234567890Chat, grupo ou usuário numérico específico
platform:chat_id:thread_idtelegram:-1001234567890:17585Thread específica ou tópico de fórum do Telegram
platform:#channeldiscord:#opsNome de canal legível (resolvido pelo diretório de canais)
platform:+E164signal:+5511987654321Plataformas endereçadas por telefone: Signal, SMS, WhatsApp

Qualquer plataforma para a qual o Hermes traz adaptador funciona como alvo: telegram, discord, slack, signal, sms, whatsapp, matrix, mattermost, feishu, dingtalk, wecom, weixin, email e outras.

Códigos de saída​

CódigoSignificado
0O envio (ou a listagem) deu certo
1A entrega falhou no nível da plataforma (autenticação, permissão, rede)
2Erro de uso, de argumento ou de configuração

Os códigos de saída seguem a convenção padrão do Unix, então os seus scripts podem se ramificar com base neles do mesmo jeito que fariam com curl ou grep.

Como o corpo da mensagem é resolvido​

O hermes send resolve o corpo da mensagem nesta ordem:

  1. Argumento posicional — hermes send --to telegram "oi"
  2. --file CAMINHO — hermes send --to telegram --file msg.txt
  3. Entrada padrão canalizada — echo oi | hermes send --to telegram

Quando a entrada padrão é um TTY (sem pipe), o Hermes não fica esperando entrada — você recebe um erro de uso claro. Isso evita que scripts travem se esquecerem o corpo por acidente.

Exemplos do mundo real​

Monitoramento: alertas de memória e de disco​

Troque as chamadas improvisadas de curl https://api.telegram.org/... dos seus watchdogs por uma linha portátil:

#!/usr/bin/env bash
ram_pct=$(free | awk '/^Mem:/ {printf "%d", $3 * 100 / $2}')
if [ "$ram_pct" -ge 85 ]; then
  hermes send --to telegram --subject "⚠ ALERTA DE MEMÓRIA" \
    "RAM ${ram_pct}% em $(hostname)"
fi

Como o hermes send reaproveita a sua configuração do Hermes, o mesmo script funciona em qualquer host onde o Hermes esteja instalado — sem precisar exportar tokens de bot no ambiente de cada máquina na mão.

Não alerte o gateway sobre ele mesmo

Em watchdogs que podem disparar justamente quando o gateway está sofrendo (alertas de OOM, de disco cheio), continue usando uma chamada mínima de curl em vez do hermes send. Se o interpretador Python não consegue carregar porque a máquina está engasgada, você ainda quer que aquele alerta saia.

CI / CD: resultados de build e de teste​

# Em .github/workflows/deploy.yml ou em qualquer script de CI
if ./scripts/deploy.sh; then
  hermes send --to slack:#deploys "✅ ${CI_COMMIT_SHA:0:7} no ar"
else
  tail -n 100 deploy.log | hermes send \
    --to slack:#deploys --subject "❌ deploy falhou"
  exit 1
fi

Cron: relatório diário​

# Entrada no crontab
0 9 * * * /usr/local/bin/gerar-metricas.sh \
  | /home/eu/.hermes/bin/hermes send \
      --to telegram --subject "Métricas do dia $(date +%Y-%m-%d)"

Tarefas longas: avise quando terminar​

./train.py --epochs 200 && \
  hermes send --to telegram "treino concluído" || \
  hermes send --to telegram "treino falhou (saída $?)"

Scripts com --json e --quiet​

# Faz o script falhar de vez se a entrega falhar; não polui o log em caso de sucesso
hermes send --to telegram --quiet "keepalive" || {
  echo "Entrega no Telegram falhou" >&2
  exit 1
}

# Captura o ID da mensagem para editar / responder depois
msg_id=$(hermes send --to discord:#ops --json "build iniciado" \
  | jq -r .message_id)

O hermes send precisa do gateway rodando?​

Em geral, não. Para qualquer plataforma com token de bot — Telegram, Discord, Slack, Signal, SMS, WhatsApp Cloud API e a maioria das outras — o hermes send chama o endpoint REST da plataforma direto, usando as credenciais de ~/.hermes/.env e de ~/.hermes/config.yaml. É um subprocesso independente que sai assim que a mensagem é entregue.

Um gateway vivo só é necessário para plataformas de plugin que dependem de uma conexão persistente do adaptador (por exemplo, um plugin próprio que mantém um WebSocket aberto por muito tempo). Nesse caso você recebe um erro claro apontando para o gateway; suba-o com hermes gateway start e tente de novo.

Listar e descobrir alvos​

Antes de mandar para um canal específico, dá para inspecionar o que existe:

# Todo alvo de toda plataforma configurada
hermes send --list

# Só os alvos do Telegram
hermes send --list telegram

# Legível por máquina
hermes send --list --json

A listagem é montada a partir de ~/.hermes/channel_directory.json, que o gateway atualiza a cada poucos minutos enquanto está rodando. Se você vir "no channels discovered yet", suba o gateway uma vez (hermes gateway start) para que ele preencha o cache.

Os nomes legíveis (discord:#ops, slack:#engineering) são resolvidos contra esse cache na hora do envio, então você não precisa decorar IDs numéricos.

Comparação com outras abordagens​

AbordagemMultiplataformaReaproveita as credenciais do HermesPrecisa do gatewayMelhor para
hermes send✅✅Não (com token de bot)Tudo daqui de baixo
curl cru para cada plataformaCada uma escrita à parteManualNãoWatchdogs críticos
Job de cron com --deliver✅✅NãoTarefas agendadas do agente

O hermes send é de propósito a superfície mais simples possível. Se você precisa de um agente para decidir o que dizer, agende um job de cron — a resposta final do agente é entregue automaticamente ao alvo configurado em deliver: (o agente não dispara mais mensagens sozinho). Se você precisa de uma execução agendada com conteúdo gerado por LLM, use cronjob(action='create', prompt=...) com deliver='telegram:...'. Se você só precisa canalizar uma string crua, vá de hermes send.