hdmx — helpdesk-CLI'en

hdmx er en kommandolinjeklient til helpdesken i én binær fil. Den pakker det offentlige GraphQL-API ind i lettilgængelige kommandoer efter mønsteret ressource-og-udsagnsord, så både AI-agenter og mennesker kan styre helpdesken fra en terminal eller et script i stedet for fra browseren.

Den er designet først til agenter, dernæst til mennesker: hver kommando kører ikke-interaktivt, hver datakommando kan udsende en struktureret --json-konvolut, fejl opremser de gyldige værdier, de forventede, og et maskinlæsbart kommandoskema lader en agent lære hele fladen i ét kald og genbruge den på tværs af mange opgaver.

Selvstændigt repository

CLI'en udgives fra sit eget repository, github.com/mirasvit/hdmx — den er ikke en del af helpdeskens kodebase. Helpdesksiden leverer kun det offentlige API og de personlige adgangstokens, som hdmx godkendes mod. Det repositorys README er den levende sandhedskilde for den aktuelle kommandoliste; denne side giver overblikket og beskriver den kontrakt, den bygger på.

Installation

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

Med hver udgivelse offentliggøres færdigbyggede binære filer (Linux, macOS, Windows), en Homebrew-tap og et container-image. hdmx version udskriver versionen, byggedatoen og den API-skemaversion, den binære fil er bygget mod.

Godkendelse

hdmx godkendes med et personligt adgangstoken — se Offentligt API → Godkendelse. Opret selv et token i agentappen under Settings → API tokens; det bærer scopes, en obligatorisk IP-allowliste og en udløbsdato.

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

Tokenet gemmes i operativsystemets nøglering. Til CI og containere tilsidesætter tre miljøvariabler den gemte profil uden nogen interaktiv forespørgsel: HDMX_HOST, HDMX_SUBDOMAIN, HDMX_TOKEN.

Flere lejere håndteres med profiler — én profil samler en vært, et subdomæne, et token og et sæt standardværdier:

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

Hvad den kan

Kommandofladen følger helpdeskens ressourcefamilier. De vigtigste områder:

Område	Hvad du kan gøre
Sager	vise, søge, triagere, fremvise, opdatere, tildele, sætte status / prioritet / tags, flette, slette
Beskeder	læse en sags beskeder, poste et offentligt svar eller en intern note
Chat	vise og fremvise samtaler, sende, lukke, genåbne, tilslutte sig, forlade, markere som læst
Kunder	vise, søge, fremvise, oprette, opdatere, flette
Stamdata	afdelinger, statusser, prioriteter, postkasser, tags, brugere
Rapporter	overblik, mængde, svartider, pr. agent, efterslæb, opdelinger
Konto	aktuel konto, metadata, aktuel bruger

To bekvemmeligheder er værd at fremhæve:

• Navne i stedet for id'er. Flag accepterer enten et læsevenligt navn eller et id — --status open, --assignee [email protected] eller den rå identifikator bliver alle slået op. Sammenhængen caches lokalt pr. konto.
• Navngivne arbejdsgange. hdmx tickets triage kører standardvisningen til triagering (åbne, ikke lukkede, ikke ønsker om nye funktioner, sorteret efter prioritet), uden at den kaldende part skal udlede filteret forfra hver gang.

Output og sikkerhed

• Struktureret som standard for maskiner. Output, der sendes videre i en pipe, er en JSON-konvolut (ok, data, summary, warnings, error, meta); en TTY får læsevenlig Markdown. --jq filtrerer JSON undervejs. Data går til stdout, diagnostik til stderr.
• Fejl, der lærer fra sig. Når en værdi afvises, nævner fejlen de gyldige værdier og en konkret næste kommando — en forkert status returnerer for eksempel listen over de faktiske statusser og et eksempel på et kald.
• Afgrænsede svar. Listekommandoer har en standard sidestørrelse og et hårdt loft; når output beskæres, siger svaret det og fortæller, hvordan du kan indsnævre. Det holder svarene inden for en agents tokenbudget.
• Prøvekørsel og godkendelsesled. Enhver mutation accepterer --dry-run (viser operationen og dens forventede virkning uden at sende den). Destruktive handlinger kræver --force; at poste kundevendte beskeder eller interne noter kræver --approve.

Sådan lærer du fladen at kende

Der er tre lag af hjælp, rettet mod tre målgrupper:

• hdmx <command> --help — fritekst med brug og eksempler (til mennesker).
• hdmx agent-context — et versioneret, maskinlæsbart skema over hver kommando, hvert flag, hver enum, fejlkode, standardværdi og navngiven arbejdsgang (til agenter, der binder sig til en stabil flade).
• hdmx skills — sammensætningsopskrifter, der binder flere kommandoer sammen til en navngiven drejebog (for eksempel et triager-og-svar-forløb).

Forholdet til det offentlige API

hdmx er den første ikke-browserbaserede forbruger af helpdeskens offentlige API. Alt, hvad den gør, går gennem det samme PAT-godkendte GraphQL-endpoint, under de samme scopes og hastighedsgrænser — der findes ingen privilegeret bagdør. API-skemaet er kontrakten; hdmx bygges mod en fastlåst API-version og følger APIets udfasningspolitik, så en CLI-udgivelse bliver ved med at virke mod ethvert kompatibelt (ikke-brydende) serverskema.