hdmx — la CLI dell'helpdesk

hdmx è un client da riga di comando a binario singolo per l'helpdesk. Racchiude l'API GraphQL pubblica dietro comandi ergonomici del tipo risorsa-e-verbo, così che sia gli agenti IA sia le persone possano pilotare l'helpdesk da un terminale o da uno script invece che dal browser.

È progettato prima per gli agenti, poi per le persone: ogni comando viene eseguito in modo non interattivo, ogni comando che restituisce dati può emettere una busta --json strutturata, gli errori elencano i valori validi che si attendevano e uno schema dei comandi leggibile dalle macchine permette a un agente di apprendere l'intera superficie in una sola chiamata e di riutilizzarla molte volte.

Repository separato

La CLI viene distribuita da un repository proprio, github.com/mirasvit/hdmx: non fa parte del codice dell'helpdesk. Il lato helpdesk fornisce soltanto l'API pubblica e i token di accesso personale con cui hdmx si autentica. Il README di quel repository è la fonte di verità aggiornata per l'elenco dei comandi attuali; questa pagina fornisce l'orientamento e il contratto su cui si basa.

Installazione

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

A ogni rilascio vengono pubblicati binari precompilati (Linux, macOS, Windows), un tap Homebrew e un'immagine container. hdmx version stampa la versione, la data di compilazione e la versione dello schema API con cui il binario è stato compilato.

Autenticazione

hdmx si autentica con un token di accesso personale — vedi API pubblica → Autenticazione. Crea un token tu stesso nell'app agente, in Settings → API tokens; porta con sé ambiti, un elenco IP consentiti obbligatorio e una scadenza.

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

Il token viene conservato nel portachiavi del sistema operativo. Per CI e container, tre variabili d'ambiente sostituiscono il profilo salvato senza alcuna richiesta interattiva: HDMX_HOST, HDMX_SUBDOMAIN, HDMX_TOKEN.

I tenant multipli si gestiscono con i profili: un profilo raccoglie un host, un sottodominio, un token e un insieme di valori predefiniti:

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

Che cosa sa fare

La superficie dei comandi rispecchia le famiglie di risorse dell'helpdesk. Le aree principali:

Area	Che cosa puoi fare
Ticket	elencare, cercare, fare triage, mostrare, aggiornare, assegnare, impostare stato / priorità / tag, unire, eliminare
Messaggi	leggere i messaggi di un ticket, pubblicare una risposta pubblica o una nota interna
Chat	elencare e mostrare conversazioni, inviare, chiudere, riaprire, entrare, uscire, segnare come letto
Clienti	elencare, cercare, mostrare, creare, aggiornare, unire
Dati di riferimento	reparti, stati, priorità, caselle di posta, tag, utenti
Report	panoramica, volume, tempi di risposta, per agente, arretrato, ripartizioni
Account	account corrente, metadati, utente corrente

Due comodità da segnalare:

• Nomi invece di ID. Le opzioni accettano sia un nome leggibile sia un ID: --status open, --assignee [email protected] o l'identificativo grezzo vengono tutti risolti. La corrispondenza viene messa in cache localmente per ogni account.
• Flussi con nome. hdmx tickets triage esegue la vista di triage standard (aperti, non chiusi, esclusi i suggerimenti di funzionalità, ordinati per priorità) senza che il chiamante debba ricostruire ogni volta il filtro.

Output e sicurezza

• Strutturato per impostazione predefinita per le macchine. L'output reindirizzato è una busta JSON (ok, data, summary, warnings, error, meta); un TTY riceve Markdown leggibile. --jq filtra il JSON al volo. I dati vanno su stdout, la diagnostica su stderr.
• Errori che insegnano. Quando un valore viene rifiutato, l'errore indica i valori validi e un comando successivo concreto: uno stato errato, ad esempio, restituisce l'elenco degli stati reali e un esempio di invocazione.
• Risposte limitate. I comandi di elenco hanno una dimensione di pagina predefinita e un tetto rigido; quando l'output viene troncato, la risposta lo dichiara e spiega come restringere la ricerca. Così le risposte restano nel budget di token di un agente.
• Prova a vuoto e passaggi di approvazione. Ogni mutazione accetta --dry-run (mostra l'operazione e il suo effetto previsto senza inviarla). Le azioni distruttive richiedono --force; pubblicare messaggi visibili al cliente o note interne richiede --approve.

Imparare la superficie

L'aiuto è su tre livelli, rivolti a tre pubblici:

• hdmx <command> --help — uso in testo libero ed esempi (per le persone).
• hdmx agent-context — uno schema versionato e leggibile dalle macchine di ogni comando, opzione, enum, codice di errore, valore predefinito e flusso con nome (per gli agenti che si legano a una superficie stabile).
• hdmx skills — ricette di composizione che uniscono più comandi in un runbook con nome (ad esempio un flusso di triage e risposta).

Rapporto con l'API pubblica

hdmx è il primo consumatore non-browser dell'API pubblica dell'helpdesk. Tutto ciò che fa passa dallo stesso endpoint GraphQL autenticato con PAT, sotto gli stessi ambiti e limiti di frequenza: non esiste alcuna porta di servizio privilegiata. Lo schema dell'API è il contratto; hdmx è compilato su una versione dell'API fissata e segue la politica di deprecazione dell'API, così un rilascio della CLI continua a funzionare con qualsiasi schema del server compatibile (senza modifiche non retrocompatibili).