hdmx — die Helpdesk-CLI

hdmx ist ein Kommandozeilen-Client für den Helpdesk als einzelne Binärdatei. Er kapselt die öffentliche GraphQL-API hinter ergonomischen Befehlen nach dem Muster Ressource-und-Verb, sodass sowohl KI-Agenten als auch Menschen den Helpdesk aus einem Terminal oder Skript statt aus dem Browser steuern können.

Er ist agenten-zuerst, menschen-danach entworfen: Jeder Befehl läuft nicht-interaktiv, jeder Datenbefehl kann einen strukturierten --json-Umschlag ausgeben, Fehler zählen die erwarteten gültigen Werte auf, und ein maschinenlesbares Befehlsschema lässt einen Agenten die gesamte Oberfläche in einem Aufruf lernen und über viele Einsätze hinweg wiederverwenden.

Eigenes Repository

Die CLI wird aus einem eigenen Repository ausgeliefert, github.com/mirasvit/hdmx — sie ist nicht Teil der Helpdesk-Codebasis. Die Helpdesk-Seite stellt lediglich die öffentliche API und die Personal Access Tokens bereit, gegen die sich hdmx authentifiziert. Die README jenes Repositories ist die maßgebliche Quelle für die aktuelle Befehlsliste; diese Seite bietet die Orientierung und beschreibt den Vertrag, auf den sie sich stützt.

Installation

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

Mit jedem Release werden vorgefertigte Binärdateien (Linux, macOS, Windows), ein Homebrew-Tap und ein Container-Image veröffentlicht. hdmx version gibt die Version, das Build-Datum und die API-Schema-Version aus, gegen die die Binärdatei gebaut wurde.

Authentifizierung

hdmx authentifiziert sich mit einem Personal Access Token — siehe Öffentliche API → Authentifizierung. Erstellen Sie einen Token selbst in der Agenten-App unter Settings → API tokens; er trägt Scopes, eine verpflichtende IP-Allowlist und ein Ablaufdatum.

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

Der Token wird im Schlüsselbund des Betriebssystems gespeichert. Für CI und Container überschreiben drei Umgebungsvariablen das gespeicherte Profil ohne interaktive Rückfrage: HDMX_HOST, HDMX_SUBDOMAIN, HDMX_TOKEN.

Mehrere Mandanten werden über Profile abgebildet — ein Profil bündelt einen Host, eine Subdomain, einen Token und eine Reihe von Standardwerten:

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

Was es kann

Die Befehlsoberfläche bildet die Ressourcenfamilien des Helpdesks ab. Die wichtigsten Bereiche:

Bereich	Was Sie tun können
Tickets	auflisten, suchen, triagieren, anzeigen, aktualisieren, zuweisen, Status / Priorität / Tags setzen, zusammenführen, löschen
Nachrichten	die Nachrichten eines Tickets lesen, eine öffentliche Antwort oder eine interne Notiz posten
Chat	Konversationen auflisten und anzeigen, senden, schließen, wieder öffnen, betreten, verlassen, als gelesen markieren
Kunden	auflisten, suchen, anzeigen, erstellen, aktualisieren, zusammenführen
Stammdaten	Abteilungen, Status, Prioritäten, Postfächer, Tags, Benutzer
Reports	Überblick, Volumen, Antwortzeiten, pro Agent, Backlog, Aufschlüsselungen
Konto	aktuelles Konto, Metadaten, aktueller Benutzer

Zwei Annehmlichkeiten sind besonders erwähnenswert:

• Namen statt IDs. Flags akzeptieren entweder einen menschenlesbaren Namen oder eine ID — --status open, --assignee [email protected] oder der rohe Bezeichner werden alle aufgelöst. Die Zuordnung wird lokal pro Konto zwischengespeichert.
• Benannte Workflows. hdmx tickets triage führt die Standard-Triage-Ansicht aus (offen, nicht geschlossen, kein Feature-Request, nach Priorität sortiert), ohne dass der Aufrufer den Filter jedes Mal neu herleiten muss.

Ausgabe und Sicherheit

• Standardmäßig strukturiert für Maschinen. Weitergeleitete Ausgabe ist ein JSON-Umschlag (ok, data, summary, warnings, error, meta); ein TTY erhält lesbares Markdown. --jq filtert JSON direkt. Daten gehen nach stdout, Diagnosen nach stderr.
• Lehrreiche Fehler. Wird ein Wert abgelehnt, nennt der Fehler die gültigen Werte und einen konkreten nächsten Befehl — ein falscher Status liefert etwa die Liste der tatsächlichen Status und einen Beispielaufruf.
• Begrenzte Antworten. Auflistungsbefehle haben eine Standard-Seitengröße und eine harte Obergrenze; wird die Ausgabe abgeschnitten, sagt die Antwort das und erklärt, wie Sie eingrenzen können. So bleiben Antworten im Token-Budget eines Agenten.
• Trockenlauf und Freigabestufen. Jede Mutation akzeptiert --dry-run (stellt die Operation und ihre erwartete Wirkung dar, ohne sie zu senden). Destruktive Aktionen erfordern --force; das Posten kundensichtbarer Nachrichten oder interner Notizen erfordert --approve.

Die Oberfläche kennenlernen

Es gibt drei Hilfeebenen für drei Zielgruppen:

• hdmx <command> --help — Freitext-Nutzung und Beispiele (für Menschen).
• hdmx agent-context — ein versioniertes, maschinenlesbares Schema jedes Befehls, Flags, Enums, Fehlercodes, Standardwerts und benannten Workflows (für Agenten, die sich an eine stabile Oberfläche binden).
• hdmx skills — Kompositionsrezepte, die mehrere Befehle zu einem benannten Runbook verbinden (z. B. ein Triage-und-Antwort-Ablauf).

Verhältnis zur öffentlichen API

hdmx ist der erste Nicht-Browser-Konsument der öffentlichen API des Helpdesks. Alles, was er tut, läuft über denselben PAT-authentifizierten GraphQL-Endpunkt, unter denselben Scopes und Rate Limits — es gibt keine privilegierte Hintertür. Das API-Schema ist der Vertrag; hdmx wird gegen eine festgelegte API-Version gebaut und folgt der Deprecation-Richtlinie der API, sodass ein CLI-Release mit jedem kompatiblen (nicht brechenden) Server-Schema weiter funktioniert.