CLI y cURL

El comando honk-me envía desde scripts de shell, tareas cron y CI, con los mismos reintentos e idempotencia que las bibliotecas. O sáltate la instalación y usa una sola solicitud cURL.

Paquete: github.com/honk-me/honk-go Publicado
Código fuente: github.com/honk-me/honk-go · Licencia MIT
Requisitos: Linux, macOS o Windows (amd64 o arm64). Go 1.22+ para compilarla tú.

Instalación

La CLI forma parte del módulo de Go.

Terminal

go install github.com/honk-me/honk-go/cmd/honk-me@latest
# or download a prebuilt binary (Linux, macOS, Windows; amd64 and arm64):
# https://github.com/honk-me/honk-go/releases

Quien tenga una clave de ingesta (honk_…) puede enviar mensajes a su proyecto. Guárdala en servidores, tareas y secretos de CI, nunca en un navegador ni en una app móvil o de escritorio.

Enviar un evento

Lee HONK_URL y HONK_KEY del entorno; la clave nunca se pasa como opción, así que nunca acaba en el historial de tu shell ni en la lista de procesos.

Terminal

export HONK_URL=https://honk-me.app HONK_KEY=honk_…   # better: your secret store

honk-me beep "Backup finished" "nightly pg_dump took 42 s"
honk-me loud "Disk 91%" --group-key "disk/$(hostname)/var"

Comandos

Los atajos light, beep, loud, long y blast fijan el nivel y reciben el texto como argumentos. send, problem y recovery usan opciones. honk-me send -h las muestra todas.

Terminal

honk-me loud "Disk 91%"                                   # shortcut: light, beep, loud, long, blast
honk-me beep "Backup finished" "nightly pg_dump took 42 s" # [TITLE] MESSAGE, flags anywhere
honk-me send --title "Disk almost full" --message "/var at 91%" --severity loud \
  --group-key "disk/$(hostname)/var" --source "$(hostname)" --meta host="$(hostname)" --meta used:=91
honk-me problem  --group-key db/backup --title "Backup failed" --message "pg_dump exited with 1"
honk-me recovery --group-key db/backup --title "Backup OK"     --message "pg_dump finished"
tail -c 8000 /var/log/backup.log | honk-me send --title "Backup log" --message -   # message from stdin
honk-me send --message "Front door" --image-url https://cam.example.com/snap.jpg --priority high
honk-me light "New request from Emily" "Wants a quote for an online shop" \
  --action "Reply by email=mailto:[email protected]" --action "Call=tel:+12025550147"   # buttons, up to 3

En cron: avisar solo cuando falla

Envía una recuperación solo cuando algo estaba roto de verdad. Una recuperación sin un problema abierto abre igualmente un episodio «recuperado» y avisa, así que una recuperación después de cada ejecución correcta te avisaría todas las noches.

crontab

0 3 * * * pg_dump app > /backup/app.sql || honk-me problem --group-key db/backup --source "$(hostname)" --title "Backup failed" --message "pg_dump exited with $?"

En CI

Una clave de idempotencia por intento de ejecución, para que los reintentos de la propia CLI nunca dupliquen nada, y || true para que una notificación nunca pueda hacer fallar la compilación.

.github/workflows/…

- name: Notify
  if: failure()
  env:
    HONK_URL: ${{ secrets.HONK_URL }}
    HONK_KEY: ${{ secrets.HONK_KEY }}
  run: |
    honk-me problem --group-key "ci/${{ github.repository }}/${{ github.ref_name }}" \
      --title "CI failed: ${{ github.workflow }}" --message "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}" \
      --source github-actions --category deployments \
      --idempotency-key "gh-${{ github.run_id }}-${{ github.run_attempt }}" || true

Códigos de salida

Añade || true donde una notificación fallida no deba hacer fallar el script.

0	Aceptado, o duplicado de un evento ya aceptado
1	Respuesta inesperada: un `HONK_URL` incorrecto, una redirección, una respuesta mal formada
2	Error de uso, o falta `HONK_URL` o `HONK_KEY`
3	Mensaje no válido: corrige las opciones
4	Autenticación: clave no válida o revocada, urgente no permitido, proyecto suspendido
5	Cuota o límite de frecuencia (`429`); stderr muestra `Retry-After`
6	Conflicto de idempotencia (`409`): misma clave, contenido distinto
7	Fallo temporal tras los reintentos: vuelve a ejecutarlo con la misma `--idempotency-key`

Con cURL

Sin instalar nada. Añade una Idempotency-Key para que los reintentos del propio cURL no puedan crear duplicados.

Terminal

curl -sS https://honk-me.app/v1/messages \
  -H "Authorization: Bearer $HONK_KEY" \
  -H "Idempotency-Key: backup-$(date +%Y%m%d)" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Backup failed",
    "message": "pg_dump exited with 1",
    "severity": "long",
    "group_key": "db/backup",
    "event_type": "problem"
  }'
# → 202 {"id":"msg_…","status":"accepted","duplicate":false,"received_at":"…"}

Terminal

curl --fail-with-body -sS --max-time 10 --retry 3 --retry-all-errors \
  -X POST "$HONK_URL/v1/messages" \
  -H "Authorization: Bearer $HONK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: request-42" \
  -d '{"title":"New request from Ana Pop","message":"Wants a quote for an online shop, budget €4,000.","severity":"light","priority":"high","category":"customers","group_key":"requests/42"}'

Reintentos que nunca envían dos veces

Cada envío lleva una Idempotency-Key: la tuya o un UUIDv7 nuevo. La misma clave se reutiliza en cada reintento y, durante 24 horas, Honk responde a una repetición con el id original y duplicate: true, así que una respuesta perdida nunca crea un segundo mensaje.
Solo se reintentan los errores de red, los tiempos de espera agotados, 429 y 5xx, con backoff exponencial y jitter completo, y nunca antes del Retry-After del servidor. Las demás respuestas 4xx no se reintentan nunca: hay que corregir la solicitud.
Cada intento se corta a los 5 segundos y todo se detiene a los 30. Una espera que superaría ese plazo, como una cuota diaria que se reinicia a medianoche, falla al momento y te dice cuándo reintentar.
Los campos se validan antes de enviar, y todos los errores de validación se devuelven juntos.