hdmx — helpdeskens CLI

hdmx är en kommandoradsklient för helpdesken i en enda binärfil. Den paketerar det publika GraphQL-API:et bakom smidiga kommandon av typen resurs-och-verb, så att både AI-agenter och människor kan styra helpdesken från en terminal eller ett skript i stället för från webbläsaren.

Den är utformad för agenter först, människor sedan: varje kommando körs icke-interaktivt, varje datakommando kan skriva ut ett strukturerat --json-kuvert, fel räknar upp de giltiga värden de förväntade sig, och ett maskinläsbart kommandoschema låter en agent lära sig hela ytan i ett enda anrop och återanvända den i många uppgifter.

Separat repository

CLI:t levereras från ett eget repository, github.com/mirasvit/hdmx — det ingår inte i helpdeskens kodbas. Helpdesksidan tillhandahåller bara det publika API:et och de personliga åtkomsttokens som hdmx autentiserar sig mot. Det repositoryts README är den levande sanningskällan för den aktuella kommandolistan; den här sidan ger överblicken och beskriver kontraktet den vilar på.

Installation

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

Vid varje release publiceras färdigbyggda binärfiler (Linux, macOS, Windows), en Homebrew-tap och en containerbild. hdmx version skriver ut versionen, byggdatumet och den API-schemaversion som binärfilen byggts mot.

Autentisering

hdmx autentiserar sig med en personlig åtkomsttoken — se Publikt API → Autentisering. Skapa en token själv i agentappen under Settings → API tokens; den bär scopes, en obligatorisk IP-tillåtelselista och ett utgångsdatum.

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

Token lagras i operativsystemets nyckelring. För CI och containrar åsidosätter tre miljövariabler den sparade profilen utan någon interaktiv fråga: HDMX_HOST, HDMX_SUBDOMAIN, HDMX_TOKEN.

Flera hyresgäster hanteras med profiler — en profil samlar en värd, en underdomän, en token och en uppsättning standardvärden:

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

Vad den kan göra

Kommandoytan följer helpdeskens resursfamiljer. De viktigaste områdena:

Område	Vad du kan göra
Ärenden	lista, söka, triagera, visa, uppdatera, tilldela, sätta status / prioritet / etiketter, slå samman, ta bort
Meddelanden	läsa ett ärendes meddelanden, publicera ett publikt svar eller en intern anteckning
Chatt	lista och visa konversationer, skicka, stänga, återöppna, gå med, lämna, markera som läst
Kunder	lista, söka, visa, skapa, uppdatera, slå samman
Grunddata	avdelningar, statusar, prioriteter, brevlådor, etiketter, användare
Rapporter	översikt, volym, svarstider, per agent, eftersläpning, nedbrytningar
Konto	aktuellt konto, metadata, aktuell användare

Två bekvämligheter är värda att lyfta fram:

• Namn i stället för ID:n. Flaggor tar emot antingen ett läsbart namn eller ett ID — --status open, --assignee [email protected] eller den råa identifieraren slås alla upp. Kopplingen cachas lokalt per konto.
• Namngivna arbetsflöden. hdmx tickets triage kör standardvyn för triagering (öppna, ej stängda, inte funktionsönskemål, sorterade efter prioritet) utan att anroparen behöver sätta ihop filtret på nytt varje gång.

Utdata och säkerhet

• Strukturerad som standard för maskiner. Utdata som skickas vidare i en pipe är ett JSON-kuvert (ok, data, summary, warnings, error, meta); en TTY får läsbar Markdown. --jq filtrerar JSON direkt. Data går till stdout, diagnostik till stderr.
• Fel som lär ut. När ett värde avvisas namnger felet de giltiga värdena och ett konkret nästa kommando — en felaktig status ger till exempel listan över de verkliga statusarna och ett exempel på anrop.
• Begränsade svar. Listkommandon har en standardsidstorlek och ett hårt tak; när utdata klipps av säger svaret ifrån och berättar hur du kan smalna av. Det håller svaren inom en agents tokenbudget.
• Torrkörning och godkännandegrindar. Varje mutation tar emot --dry-run (visar operationen och dess förväntade effekt utan att skicka den). Destruktiva åtgärder kräver --force; att publicera kundvända meddelanden eller interna anteckningar kräver --approve.

Att lära känna ytan

Hjälpen finns i tre lager, riktade till tre målgrupper:

• hdmx <command> --help — fritext med användning och exempel (för människor).
• hdmx agent-context — ett versionerat, maskinläsbart schema över varje kommando, flagga, enum, felkod, standardvärde och namngivet arbetsflöde (för agenter som binder sig till en stabil yta).
• hdmx skills — kompositionsrecept som binder ihop flera kommandon till en namngiven körbok (till exempel ett triagera-och-svara-flöde).

Förhållandet till det publika API:et

hdmx är den första icke-webbläsarbaserade konsumenten av helpdeskens publika API. Allt den gör går via samma PAT-autentiserade GraphQL-endpunkt, under samma scopes och hastighetsgränser — det finns ingen privilegierad bakdörr. API-schemat är kontraktet; hdmx byggs mot en fastlåst API-version och följer API:ets utfasningspolicy, så en CLI-release fortsätter fungera mot vilket kompatibelt (icke-brytande) serverschema som helst.