hdmx — a CLI do helpdesk

hdmx é um cliente de linha de comando de binário único para o helpdesk. Ele envolve a API GraphQL pública atrás de comandos ergonômicos no formato recurso-e-verbo, para que tanto agentes de IA quanto pessoas possam operar o helpdesk a partir de um terminal ou script, em vez do navegador.

Foi projetado primeiro para agentes, depois para pessoas: todo comando roda de forma não interativa, todo comando de dados pode emitir um envelope --json estruturado, os erros enumeram os valores válidos que esperavam, e um schema de comandos legível por máquina permite que um agente aprenda toda a superfície em uma única chamada e a reutilize muitas vezes.

Repositório separado

A CLI é distribuída a partir do seu próprio repositório, github.com/mirasvit/hdmx — ela não faz parte do código do helpdesk. O lado do helpdesk fornece apenas a API pública e os tokens de acesso pessoal com os quais o hdmx se autentica. O README daquele repositório é a fonte de verdade viva para a lista de comandos atual; esta página dá a orientação e o contrato em que ela se apoia.

Instalação

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

A cada lançamento são publicados binários prontos (Linux, macOS, Windows), um tap do Homebrew e uma imagem de contêiner. hdmx version imprime a versão, a data de compilação e a versão do schema da API contra a qual o binário foi compilado.

Autenticação

O hdmx se autentica com um token de acesso pessoal — veja API pública → Autenticação. Crie um token você mesmo no app do agente, em Settings → API tokens; ele carrega escopos, uma lista de IPs permitidos obrigatória e uma expiração.

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

O token é guardado no chaveiro do sistema operacional. Para CI e contêineres, três variáveis de ambiente substituem o perfil salvo sem nenhuma pergunta interativa: HDMX_HOST, HDMX_SUBDOMAIN, HDMX_TOKEN.

Múltiplos inquilinos são tratados com perfis — um perfil reúne um host, um subdomínio, um token e um conjunto de padrões:

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

O que ele faz

A superfície de comandos corresponde às famílias de recursos do helpdesk. As áreas principais:

Área	O que você pode fazer
Tickets	listar, buscar, triar, exibir, atualizar, atribuir, definir status / prioridade / tags, mesclar, excluir
Mensagens	ler as mensagens de um ticket, publicar uma resposta pública ou uma nota interna
Chat	listar e exibir conversas, enviar, fechar, reabrir, entrar, sair, marcar como lida
Clientes	listar, buscar, exibir, criar, atualizar, mesclar
Dados de referência	departamentos, status, prioridades, caixas de correio, tags, usuários
Relatórios	visão geral, volume, tempos de resposta, por agente, backlog, detalhamentos
Conta	conta atual, metadados, usuário atual

Duas conveniências que valem menção:

• Nomes em vez de IDs. As flags aceitam tanto um nome legível quanto um ID — --status open, --assignee [email protected] ou o identificador bruto são todos resolvidos. O mapeamento fica em cache local por conta.
• Fluxos nomeados. hdmx tickets triage executa a visão de triagem padrão (abertos, não fechados, sem pedidos de funcionalidade, ordenados por prioridade), sem que quem chama precise refazer o filtro a cada vez.

Saída e segurança

• Estruturada por padrão para máquinas. A saída redirecionada é um envelope JSON (ok, data, summary, warnings, error, meta); um TTY recebe Markdown legível. --jq filtra o JSON na hora. Os dados vão para stdout e os diagnósticos para stderr.
• Erros que ensinam. Quando um valor é recusado, o erro nomeia os valores válidos e um próximo comando concreto — um status inválido, por exemplo, retorna a lista de status reais e um exemplo de invocação.
• Respostas limitadas. Os comandos de listagem têm um tamanho de página padrão e um teto rígido; quando a saída é cortada, a resposta avisa e explica como restringir. Isso mantém as respostas dentro do orçamento de tokens de um agente.
• Simulação e portões de aprovação. Toda mutação aceita --dry-run (mostra a operação e o efeito previsto sem enviá-la). Ações destrutivas exigem --force; publicar mensagens visíveis ao cliente ou notas internas exige --approve.

Aprender a superfície

Há três camadas de ajuda, voltadas a três públicos:

• hdmx <command> --help — uso em texto livre e exemplos (para pessoas).
• hdmx agent-context — um schema versionado e legível por máquina de cada comando, flag, enum, código de erro, padrão e fluxo nomeado (para agentes que se ligam a uma superfície estável).
• hdmx skills — receitas de composição que unem vários comandos em um runbook nomeado (por exemplo, um fluxo de triagem e resposta).

Relação com a API pública

O hdmx é o primeiro consumidor fora do navegador da API pública do helpdesk. Tudo o que ele faz passa pelo mesmo endpoint GraphQL autenticado por PAT, sob os mesmos escopos e limites de taxa — não existe porta dos fundos privilegiada. O schema da API é o contrato; o hdmx é compilado contra uma versão da API fixada e segue a política de descontinuação da API, de modo que um lançamento da CLI continua funcionando com qualquer schema de servidor compatível (sem mudanças incompatíveis).