hdmx — la CLI du helpdesk

hdmx est un client en ligne de commande à binaire unique pour le helpdesk. Il enveloppe l'API GraphQL publique derrière des commandes ergonomiques de type ressource-et-verbe, afin que les agents IA comme les humains puissent piloter le helpdesk depuis un terminal ou un script plutôt que depuis le navigateur.

Il est conçu d'abord pour les agents, ensuite pour les humains : chaque commande s'exécute de façon non interactive, chaque commande de données peut émettre une enveloppe --json structurée, les erreurs énumèrent les valeurs valides attendues, et un schéma de commandes lisible par machine permet à un agent d'apprendre toute la surface en un seul appel et de la réutiliser à de nombreuses reprises.

Dépôt distinct

La CLI est livrée depuis son propre dépôt, github.com/mirasvit/hdmx — elle ne fait pas partie du code du helpdesk. Le helpdesk ne fournit que l'API publique et les jetons d'accès personnels auprès desquels hdmx s'authentifie. Le README de ce dépôt est la source de vérité vivante pour la liste actuelle des commandes ; cette page donne l'orientation et décrit le contrat sur lequel elle s'appuie.

Installation

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

Des binaires précompilés (Linux, macOS, Windows), un tap Homebrew et une image de conteneur sont publiés à chaque version. hdmx version affiche la version, la date de compilation et la version du schéma d'API contre laquelle le binaire a été construit.

Authentification

hdmx s'authentifie avec un jeton d'accès personnel — voir API publique → Authentification. Créez un jeton vous-même dans l'application agent, sous Settings → API tokens ; il porte des portées, une liste d'IP autorisées obligatoire et une expiration.

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

Le jeton est stocké dans le trousseau du système d'exploitation. Pour la CI et les conteneurs, trois variables d'environnement remplacent le profil enregistré sans aucune invite interactive : HDMX_HOST, HDMX_SUBDOMAIN, HDMX_TOKEN.

La gestion de plusieurs locataires passe par des profils — un profil regroupe un hôte, un sous-domaine, un jeton et un ensemble de valeurs par défaut :

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

Ce qu'il sait faire

La surface de commandes reflète les familles de ressources du helpdesk. Les domaines principaux :

Domaine	Ce que vous pouvez faire
Tickets	lister, rechercher, trier, afficher, mettre à jour, assigner, définir statut / priorité / étiquettes, fusionner, supprimer
Messages	lire les messages d'un ticket, publier une réponse publique ou une note interne
Chat	lister et afficher les conversations, envoyer, fermer, rouvrir, rejoindre, quitter, marquer comme lu
Clients	lister, rechercher, afficher, créer, mettre à jour, fusionner
Données de référence	services, statuts, priorités, boîtes mail, étiquettes, utilisateurs
Rapports	vue d'ensemble, volume, temps de réponse, par agent, arriéré, répartitions
Compte	compte courant, métadonnées, utilisateur courant

Deux commodités méritent d'être signalées :

• Des noms plutôt que des identifiants. Les options acceptent aussi bien un nom lisible qu'un identifiant — --status open, --assignee [email protected] ou l'identifiant brut sont tous résolus. La correspondance est mise en cache localement pour chaque compte.
• Flux nommés. hdmx tickets triage exécute la vue de tri standard (ouverts, non fermés, hors demandes de fonctionnalité, triés par priorité) sans que l'appelant ait à redéfinir le filtre à chaque fois.

Sortie et sûreté

• Structurée par défaut pour les machines. Une sortie redirigée est une enveloppe JSON (ok, data, summary, warnings, error, meta) ; un terminal (TTY) reçoit du Markdown lisible. --jq filtre le JSON en ligne. Les données vont sur stdout, les diagnostics sur stderr.
• Des erreurs qui enseignent. Lorsqu'une valeur est refusée, l'erreur nomme les valeurs valides et une commande suivante concrète — un statut incorrect renvoie par exemple la liste des statuts réels et un exemple d'invocation.
• Réponses bornées. Les commandes de liste ont une taille de page par défaut et un plafond strict ; lorsque la sortie est tronquée, la réponse le signale et indique comment affiner. Cela maintient les réponses dans le budget de jetons d'un agent.
• Simulation et garde-fous d'approbation. Chaque mutation accepte --dry-run (affiche l'opération et son effet prévu sans l'envoyer). Les actions destructives exigent --force ; publier des messages visibles par le client ou des notes internes exige --approve.

Apprendre la surface

L'aide comporte trois niveaux, destinés à trois publics :

• hdmx <command> --help — usage en texte libre et exemples (pour les humains).
• hdmx agent-context — un schéma versionné et lisible par machine de chaque commande, option, énumération, code d'erreur, valeur par défaut et flux nommé (pour les agents qui se lient à une surface stable).
• hdmx skills — des recettes de composition qui relient plusieurs commandes en un runbook nommé (par exemple un flux de tri puis de réponse).

Relation avec l'API publique

hdmx est le premier consommateur non navigateur de l'API publique du helpdesk. Tout ce qu'il fait passe par le même point de terminaison GraphQL authentifié par PAT, sous les mêmes portées et limites de débit — il n'existe aucune porte dérobée privilégiée. Le schéma de l'API est le contrat ; hdmx est construit contre une version d'API épinglée et suit la politique de dépréciation de l'API, si bien qu'une version de la CLI continue de fonctionner avec tout schéma serveur compatible (sans changement incompatible).