hdmx — la CLI del helpdesk

hdmx es un cliente de línea de comandos de un solo binario para el helpdesk. Envuelve la API GraphQL pública tras comandos ergonómicos de recurso y verbo, para que tanto los agentes de IA como las personas puedan manejar el helpdesk desde un terminal o un script en lugar del navegador.

Está diseñado primero para agentes y después para personas: cada comando se ejecuta de forma no interactiva, cada comando de datos puede emitir un sobre --json estructurado, los errores enumeran los valores válidos que esperaban, y un esquema de comandos legible por máquina permite a un agente aprender toda la superficie en una sola llamada y reutilizarla muchas veces.

Repositorio aparte

La CLI se distribuye desde su propio repositorio, github.com/mirasvit/hdmx: no forma parte del código del helpdesk. El lado del helpdesk solo aporta la API pública y los tokens de acceso personal contra los que se autentica hdmx. El README de ese repositorio es la fuente de verdad viva para la lista de comandos actual; esta página aporta la orientación y el contrato en el que se apoya.

Instalación

go install github.com/mirasvit/hdmx/cmd/hdmx@latest

Con cada versión se publican binarios precompilados (Linux, macOS, Windows), un tap de Homebrew y una imagen de contenedor. hdmx version muestra la versión, la fecha de compilación y la versión del esquema de la API con la que se compiló el binario.

Autenticación

hdmx se autentica con un token de acceso personal; consulta API pública → Autenticación. Crea un token tú mismo en la aplicación de agente, en Settings → API tokens; lleva ámbitos, una lista de IP permitidas obligatoria y una caducidad.

hdmx auth login --host helpdesk.example.com --subdomain acme --token hdmx_…
hdmx auth status
hdmx auth logout

El token se guarda en el llavero del sistema operativo. Para CI y contenedores, tres variables de entorno sustituyen al perfil guardado sin ninguna pregunta interactiva: HDMX_HOST, HDMX_SUBDOMAIN, HDMX_TOKEN.

Los múltiples inquilinos se gestionan con perfiles: un perfil agrupa un host, un subdominio, un token y un conjunto de valores por defecto:

hdmx profile save acme --host helpdesk.example.com --subdomain acme --token hdmx_…
hdmx profile use acme
hdmx --profile other tickets list

Qué puede hacer

La superficie de comandos se corresponde con las familias de recursos del helpdesk. Las áreas principales:

Área	Qué puedes hacer
Tickets	listar, buscar, triar, mostrar, actualizar, asignar, fijar estado / prioridad / etiquetas, fusionar, eliminar
Mensajes	leer los mensajes de un ticket, publicar una respuesta pública o una nota interna
Chat	listar y mostrar conversaciones, enviar, cerrar, reabrir, unirse, salir, marcar como leído
Clientes	listar, buscar, mostrar, crear, actualizar, fusionar
Datos de referencia	departamentos, estados, prioridades, buzones, etiquetas, usuarios
Informes	visión general, volumen, tiempos de respuesta, por agente, backlog, desgloses
Cuenta	cuenta actual, metadatos, usuario actual

Dos comodidades que merece la pena destacar:

• Nombres en lugar de identificadores. Las opciones aceptan tanto un nombre legible como un identificador: --status open, --assignee [email protected] o el identificador en bruto se resuelven igual. La correspondencia se guarda en caché localmente para cada cuenta.
• Flujos con nombre. hdmx tickets triage ejecuta la vista de triaje estándar (abiertos, no cerrados, sin peticiones de funcionalidad, ordenados por prioridad) sin que quien llama tenga que rehacer el filtro cada vez.

Salida y seguridad

• Estructurada por defecto para máquinas. La salida redirigida es un sobre JSON (ok, data, summary, warnings, error, meta); un TTY recibe Markdown legible. --jq filtra el JSON sobre la marcha. Los datos van a stdout y los diagnósticos a stderr.
• Errores que enseñan. Cuando se rechaza un valor, el error nombra los valores válidos y un comando siguiente concreto; por ejemplo, un estado incorrecto devuelve la lista de estados reales y un ejemplo de invocación.
• Respuestas acotadas. Los comandos de listado tienen un tamaño de página por defecto y un tope estricto; cuando la salida se recorta, la respuesta lo indica y explica cómo acotar. Así las respuestas caben en el presupuesto de tokens de un agente.
• Simulación y puertas de aprobación. Toda mutación acepta --dry-run (representa la operación y su efecto previsto sin enviarla). Las acciones destructivas exigen --force; publicar mensajes visibles para el cliente o notas internas exige --approve.

Aprender la superficie

Hay tres capas de ayuda, dirigidas a tres públicos:

• hdmx <command> --help: uso en texto libre y ejemplos (para personas).
• hdmx agent-context: un esquema versionado y legible por máquina de cada comando, opción, enumeración, código de error, valor por defecto y flujo con nombre (para agentes que se enlazan a una superficie estable).
• hdmx skills: recetas de composición que unen varios comandos en un runbook con nombre (por ejemplo, un flujo de triaje y respuesta).

Relación con la API pública

hdmx es el primer consumidor no navegador de la API pública del helpdesk. Todo lo que hace pasa por el mismo endpoint GraphQL autenticado con PAT, bajo los mismos ámbitos y límites de tasa: no hay ninguna puerta trasera privilegiada. El esquema de la API es el contrato; hdmx se compila contra una versión de la API fijada y sigue la política de obsolescencia de la API, de modo que una versión de la CLI sigue funcionando con cualquier esquema de servidor compatible (sin cambios incompatibles).