hdmx — a CLI do helpdesk

O hdmx é um cliente de linha de comandos de binário único para o helpdesk. Envolve a API GraphQL pública atrás de comandos ergonómicos do tipo recurso-e-verbo, para que tanto agentes de IA como pessoas possam operar o helpdesk a partir de um terminal ou de um script, em vez do browser.

Foi concebido primeiro para agentes, depois para pessoas: cada comando corre de forma não interativa, cada 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 a um agente aprender toda a superfície numa única chamada e reutilizá-la muitas vezes.

Repositório separado

A CLI é distribuída a partir do seu próprio repositório, github.com/mirasvit/hdmx — 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 perante os quais o hdmx se autentica. O README desse 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 se apoia.

Instalação

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

Em cada lançamento são publicados binários pré-compilados (Linux, macOS, Windows), um tap do Homebrew e uma imagem de contentor. 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 autentica-se com um token de acesso pessoal — veja API pública → Autenticação. Crie um token você mesmo na aplicação de agente, em Settings → API tokens; transporta âmbitos, uma lista de IP permitidos obrigatória e uma validade.

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

O token é guardado no porta-chaves do sistema operativo. Para CI e contentores, três variáveis de ambiente substituem o perfil guardado sem qualquer pergunta interativa: HDMX_HOST, HDMX_SUBDOMAIN, HDMX_TOKEN.

Vários inquilinos são geridos com perfis — um perfil junta um servidor, um subdomínio, um token e um conjunto de valores por omissão:

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

O que consegue fazer

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

Área	O que pode fazer
Tickets	listar, pesquisar, triar, mostrar, atualizar, atribuir, definir estado / prioridade / etiquetas, fundir, eliminar
Mensagens	ler as mensagens de um ticket, publicar uma resposta pública ou uma nota interna
Chat	listar e mostrar conversas, enviar, fechar, reabrir, entrar, sair, marcar como lida
Clientes	listar, pesquisar, mostrar, criar, atualizar, fundir
Dados de referência	departamentos, estados, prioridades, caixas de correio, etiquetas, utilizadores
Relatórios	visão geral, volume, tempos de resposta, por agente, backlog, desagregações
Conta	conta atual, metadados, utilizador atual

Duas comodidades a destacar:

• Nomes em vez de IDs. As opções aceitam tanto um nome legível como um ID — --status open, --assignee [email protected] ou o identificador em bruto são todos resolvidos. A correspondência fica em cache local por conta.
• Fluxos com nome. hdmx tickets triage executa a vista de triagem padrão (abertos, não fechados, sem pedidos de funcionalidade, ordenados por prioridade), sem que quem invoca tenha de refazer o filtro de cada vez.

Saída e segurança

• Estruturada por omissã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 no momento. Os dados vão para stdout e o diagnóstico para stderr.
• Erros que ensinam. Quando um valor é recusado, o erro nomeia os valores válidos e um comando seguinte concreto — um estado inválido, por exemplo, devolve a lista dos estados reais e um exemplo de invocação.
• Respostas limitadas. Os comandos de listagem têm um tamanho de página por omissão e um limite rígido; quando a saída é cortada, a resposta diz e explica como restringir. Assim as respostas mantêm-se dentro do orçamento de tokens de um agente.
• Simulação e portões de aprovação. Todas as mutações aceitam --dry-run (mostra a operação e o seu efeito previsto sem a enviar). As ações destrutivas exigem --force; publicar mensagens visíveis para o cliente ou notas internas exige --approve.

Aprender a superfície

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

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

Relação com a API pública

O hdmx é o primeiro consumidor fora do browser da API pública do helpdesk. Tudo o que faz passa pelo mesmo endpoint GraphQL autenticado por PAT, sob os mesmos âmbitos e limites de taxa — não existe qualquer porta traseira 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, pelo que um lançamento da CLI continua a funcionar com qualquer schema de servidor compatível (sem alterações incompatíveis).