hdmx — 헬프데스크 CLI
hdmx는 헬프데스크를 위한 단일 바이너리 명령줄 클라이언트입니다. 공개 GraphQL API를 "리소스와 동사" 형태의 편리한 명령으로 감싸, AI 에이전트와 사람 모두가 브라우저 대신 터미널이나 스크립트에서 헬프데스크를 조작할 수 있게 합니다.
설계 원칙은 에이전트 우선, 사람은 그다음입니다. 모든 명령이 비대화식으로 실행되고, 데이터를 다루는 명령은 구조화된 --json 엔벨로프를 낼 수 있으며, 오류는 기대했던 유효한 값을 열거하고, 기계가 읽을 수 있는 명령 스키마 덕분에 에이전트는 한 번의 호출로 전체 표면을 익혀 여러 작업에서 재사용할 수 있습니다.
CLI는 자체 저장소 github.com/mirasvit/hdmx에서 배포되며, 헬프데스크 코드베이스의 일부가 아닙니다. 헬프데스크 쪽은 hdmx가 인증에 사용하는 공개 API와 개인 액세스 토큰만 제공합니다. 현재 명령 목록의 살아 있는 기준은 그 저장소의 README이며, 이 페이지는 전체 그림과 CLI가 의존하는 계약을 설명합니다.
설치
go install github.com/mirasvit/hdmx/cmd/hdmx@latest
릴리스마다 미리 빌드된 바이너리(Linux, macOS, Windows), Homebrew tap, 컨테이너 이미지가 공개됩니다. 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.
여러 테넌트는 프로필로 다룹니다. 프로필 하나가 호스트, 서브도메인, 토큰, 기본값 묶음을 담습니다.
hdmx profile save acme --host helpdesk.example.com --subdomain acme --token hdmx_…
hdmx profile use acme
hdmx --profile other tickets list
할 수 있는 일
명령 체계는 헬프데스크의 리소스 계열에 대응합니다. 주요 영역은 다음과 같습니다.
| 영역 | 할 수 있는 일 |
|---|---|
| 티켓 | 목록 조회, 검색, 분류(트리아지), 상세 보기, 수정, 담당자 지정, 상태 / 우선순위 / 태그 설정, 병합, 삭제 |
| 메시지 | 티켓의 메시지 읽기, 공개 답변이나 내부 메모 게시 |
| 채팅 | 대화 목록 조회와 보기, 전송, 종료, 재오픈, 참여, 나가기, 읽음 표시 |
| 고객 | 목록 조회, 검색, 보기, 생성, 수정, 병합 |
| 기준 정보 | 부서, 상태, 우선순위, 메일함, 태그, 사용자 |
| 리포트 | 개요, 물량, 응답 시간, 상담원별, 백로그, 세부 분류 |
| 계정 | 현재 계정, 메타데이터, 현재 사용자 |
특히 언급할 만한 두 가지 편의 기능이 있습니다.
- ID 대신 이름. 플래그는 사람이 읽는 이름과 ID를 모두 받습니다.
--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— 모든 명령, 플래그, 열거값, 오류 코드, 기본값, 이름 있는 워크플로를 담은 버전이 매겨진 기계 판독 스키마(안정적인 표면에 결합하는 에이전트용).hdmx skills— 여러 명령을 이름 있는 실행 절차로 엮는 조합 레시피(예: 분류 후 응답하는 흐름).
공개 API와의 관계
hdmx는 헬프데스크 공개 API의 첫 번째 비브라우저 소비자입니다. 이 CLI가 하는 모든 일은 동일한 PAT 인증 GraphQL 엔드포인트를 통해, 동일한 스코프와 요청 한도 아래에서 이뤄집니다. 특권적인 뒷문은 없습니다. API 스키마가 계약이며, hdmx는 고정된 API 버전을 대상으로 빌드되고 API의 지원 중단 정책을 따르므로, CLI 릴리스는 호환되는(파괴적이지 않은) 서버 스키마와 계속 동작합니다.