hdmx — CLI хелпдеска
hdmx — це клієнт командного рядка для хелпдеска, що складається з одного бінарного файлу. Він огортає публічний GraphQL API у зручні команди виду «ресурс і дія», щоб і AI-агенти, і люди могли керувати хелпдеском з термінала чи скрипта замість браузера.
Його спроєктовано насамперед для агентів, а вже потім для людей: кожна команда виконується неінтерактивно, кожна команда з даними може повертати структурований конверт --json, помилки перелічують значення, яких вони очікували, а машиночитана схема команд дозволяє агенту вивчити всю поверхню за один виклик і повторно використовувати її в багатьох сценаріях.
CLI постачається з власного репозиторію — github.com/mirasvit/hdmx; він не є частиною кодової бази хелпдеска. З боку хелпдеска надаються лише публічний API та персональні токени доступу, за якими автентифікується hdmx. Файл README того репозиторію є актуальним джерелом істини щодо поточного переліку команд; ця сторінка дає загальне уявлення та описує контракт, на який CLI спирається.
Встановлення
go install github.com/mirasvit/hdmx/cmd/hdmx@latest
З кожним випуском публікуються готові бінарні файли (Linux, macOS, Windows), тап Homebrew та образ контейнера. Команда hdmx version виводить версію, дату збірки та версію схеми API, під яку зібрано бінарний файл.
Автентифікація
hdmx автентифікується за допомогою персонального токена доступу — див. Публічний API → Автентифікація. Створіть токен самостійно в застосунку агента, у розділі Settings → API tokens; він містить права доступу, обов'язковий список дозволених IP і термін дії.
hdmx auth login --host helpdesk.example.com --subdomain acme --token hdmx_…
hdmx auth status
hdmx auth logout
Токен зберігається у сховищі ключів операційної системи. Для CI та контейнерів три змінні середовища перевизначають збережений профіль без інтерактивних запитів: HDMX_HOST, HDMX_SUBDOMAIN, HDMX_TOKEN.
Робота з кількома орендарями (tenants) виконується через профілі — один профіль об'єднує хост, субдомен, токен і набір значень за замовчуванням:
hdmx profile save acme --host helpdesk.example.com --subdomain acme --token hdmx_…
hdmx profile use acme
hdmx --profile other tickets list
Що він уміє
Набір команд відповідає родинам ресурсів хелпдеска. Основні напрямки:
| Напрямок | Що можна робити |
|---|---|
| Тікети | список, пошук, тріаж, перегляд, оновлення, призначення, встановлення статусу / пріоритету / тегів, об'єднання, видалення |
| Повідомлення | читання повідомлень тікета, публікація публічної відповіді або внутрішньої нотатки |
| Чат | перегляд списку та вмісту розмов, надсилання, закриття, повторне відкриття, приєднання, вихід, позначення прочитаним |
| Клієнти | список, пошук, перегляд, створення, оновлення, об'єднання |
| Довідкові дані | відділи, статуси, пріоритети, поштові скриньки, теги, користувачі |
| Звіти | загальний огляд, обсяг, час відповіді, за агентами, беклог, розрізи даних |
| Обліковий запис | поточний обліковий запис, метадані, поточний користувач |
Дві зручності, які варто відзначити окремо:
- Назви замість ідентифікаторів. Прапорці приймають або зрозумілу людині назву, або ідентифікатор —
--status open,--assignee [email protected]чи сирий ідентифікатор працюють однаково. Відповідність кешується локально для кожного облікового запису. - Іменовані робочі процеси. Команда
hdmx tickets triageвиконує стандартне подання для тріажу (відкриті, не закриті, не запити на нову функціональність, упорядковані за пріоритетом) — не потрібно щоразу заново складати фільтр.
Вивід і безпека
- Структурований вивід за замовчуванням для машин. У разі перенаправлення виводу повертається JSON-конверт (
ok,data,summary,warnings,error,meta); у терміналі (TTY) — зручний для читання Markdown.--jqфільтрує JSON на льоту. Дані йдуть у stdout, діагностика — у stderr. - Помилки, що навчають. Коли значення відхилено, помилка називає припустимі значення та конкретну наступну команду — наприклад, для неправильного статусу повертається перелік наявних статусів і приклад виклику.
- Обмежений обсяг відповідей. Команди зі списками мають розмір сторінки за замовчуванням і жорстке обмеження; якщо вивід обрізано, у відповіді про це сказано й пояснено, як звузити вибірку. Це утримує відповіді в межах бюджету токенів агента.
- Пробний запуск і підтвердження дій. Кожна мутація приймає
--dry-run(показує операцію та її очікуваний ефект, не надсилаючи її). Деструктивні дії вимагають--force; публікація повідомлень, видимих клієнту, або внутрішніх нотаток вимагає--approve.
Як вивчити набір команд
Довідка має три рівні, розраховані на три аудиторії:
hdmx <command> --help— текстовий опис використання та приклади (для людей).hdmx agent-context— версійована машиночитана схема кожної команди, прапорця, переліку enum, коду помилки, значення за замовчуванням та іменованого робочого процесу (для агентів, які прив'язуються до стабільної поверхні).hdmx skills— рецепти композиції, що об'єднують кілька команд в іменований сценарій (наприклад, процес тріажу та відповіді).
Зв'язок із публічним API
hdmx — перший небраузерний споживач публічного API хелпдеска. Усе, що він робить, проходить через той самий GraphQL-ендпоінт з автентифікацією за PAT, під тими самими правами доступу та обмеженнями частоти запитів — жодного привілейованого чорного ходу немає. Схема API є контрактом; hdmx зібрано під закріплену версію API і він дотримується політики застарілих елементів API, тож випуск CLI продовжує працювати з будь-якою сумісною (без несумісних змін) схемою сервера.