hdmx — de helpdesk-CLI

hdmx is een opdrachtregelclient voor de helpdesk in één binair bestand. Hij verpakt de publieke GraphQL-API achter ergonomische commando's van het type resource-en-werkwoord, zodat zowel AI-agents als mensen de helpdesk vanuit een terminal of script kunnen aansturen in plaats van vanuit de browser.

Hij is ontworpen eerst voor agents, daarna voor mensen: elk commando draait niet-interactief, elk datacommando kan een gestructureerde --json-envelop uitgeven, fouten sommen de geldige waarden op die ze verwachtten, en een machineleesbaar commandoschema laat een agent het hele oppervlak in één aanroep leren en over veel taken hergebruiken.

Aparte repository

De CLI wordt geleverd vanuit een eigen repository, github.com/mirasvit/hdmx — hij maakt geen deel uit van de helpdeskcodebase. De helpdeskkant levert alleen de publieke API en de persoonlijke toegangstokens waartegen hdmx zich authenticeert. De README van die repository is de levende bron van waarheid voor de actuele commandolijst; deze pagina geeft de oriëntatie en het contract waarop hij steunt.

Installeren

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

Bij elke release verschijnen kant-en-klare binaries (Linux, macOS, Windows), een Homebrew-tap en een containerimage. hdmx version toont de versie, de builddatum en de API-schemaversie waartegen het binaire bestand is gebouwd.

Authenticeren

hdmx authenticeert met een persoonlijk toegangstoken — zie Publieke API → Authenticatie. Maak zelf een token aan in de agent-app onder Settings → API tokens; het draagt scopes, een verplichte IP-allowlist en een vervaldatum.

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

Het token wordt bewaard in de sleutelring van het besturingssysteem. Voor CI en containers overschrijven drie omgevingsvariabelen het opgeslagen profiel zonder interactieve vraag: HDMX_HOST, HDMX_SUBDOMAIN, HDMX_TOKEN.

Meerdere tenants worden afgehandeld met profielen — één profiel bundelt een host, een subdomein, een token en een set standaardwaarden:

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

Wat het kan

Het commando-oppervlak volgt de resourcefamilies van de helpdesk. De belangrijkste gebieden:

Gebied	Wat u kunt doen
Tickets	opsommen, zoeken, triëren, tonen, bijwerken, toewijzen, status / prioriteit / tags zetten, samenvoegen, verwijderen
Berichten	de berichten van een ticket lezen, een openbaar antwoord of een interne notitie plaatsen
Chat	gesprekken opsommen en tonen, versturen, sluiten, heropenen, betreden, verlaten, als gelezen markeren
Klanten	opsommen, zoeken, tonen, aanmaken, bijwerken, samenvoegen
Referentiegegevens	afdelingen, statussen, prioriteiten, mailboxen, tags, gebruikers
Rapporten	overzicht, volume, responstijden, per agent, achterstand, uitsplitsingen
Account	huidig account, metadata, huidige gebruiker

Twee gemakken zijn het vermelden waard:

• Namen in plaats van ID's. Vlaggen accepteren zowel een leesbare naam als een ID — --status open, --assignee [email protected] of de ruwe identifier worden alle omgezet. De koppeling wordt lokaal per account gecachet.
• Benoemde workflows. hdmx tickets triage draait de standaard triage-weergave (open, niet gesloten, geen feature-verzoek, gesorteerd op prioriteit) zonder dat de aanroeper het filter telkens opnieuw hoeft af te leiden.

Uitvoer en veiligheid

• Standaard gestructureerd voor machines. Doorgesluisde uitvoer is een JSON-envelop (ok, data, summary, warnings, error, meta); een TTY krijgt leesbare Markdown. --jq filtert JSON ter plekke. Gegevens gaan naar stdout, diagnostiek naar stderr.
• Fouten die iets leren. Wanneer een waarde wordt geweigerd, noemt de fout de geldige waarden en een concreet volgend commando — een verkeerde status geeft bijvoorbeeld de lijst met echte statussen en een voorbeeldaanroep terug.
• Begrensde antwoorden. Lijstcommando's hebben een standaard paginagrootte en een harde bovengrens; als uitvoer wordt afgekapt, zegt het antwoord dat en legt uit hoe u kunt verfijnen. Zo blijven antwoorden binnen het tokenbudget van een agent.
• Proefdraaien en goedkeuringspoorten. Elke mutatie accepteert --dry-run (toont de operatie en het verwachte effect zonder te versturen). Destructieve acties vereisen --force; het plaatsen van voor klanten zichtbare berichten of interne notities vereist --approve.

Het oppervlak leren

Er zijn drie lagen hulp, gericht op drie doelgroepen:

• hdmx <command> --help — vrije tekst met gebruik en voorbeelden (voor mensen).
• hdmx agent-context — een geversioneerd, machineleesbaar schema van elk commando, elke vlag, enum, foutcode, standaardwaarde en benoemde workflow (voor agents die zich aan een stabiel oppervlak binden).
• hdmx skills — compositierecepten die meerdere commando's tot een benoemd runbook verbinden (bijvoorbeeld een triage-en-antwoordstroom).

Verhouding tot de publieke API

hdmx is de eerste niet-browserconsument van de publieke API van de helpdesk. Alles wat hij doet loopt via hetzelfde met een PAT geauthenticeerde GraphQL-eindpunt, onder dezelfde scopes en rate limits — er is geen bevoorrechte achterdeur. Het API-schema is het contract; hdmx wordt gebouwd tegen een vastgezette API-versie en volgt het deprecatiebeleid van de API, zodat een CLI-release blijft werken met elk compatibel (niet-brekend) serverschema.