hdmx — ヘルプデスク CLI

hdmx はヘルプデスク用の単一バイナリのコマンドラインクライアントです。公開 GraphQL API を「リソース＋動詞」形式の使いやすいコマンドで包み、AI エージェントも人も、ブラウザーではなくターミナルやスクリプトからヘルプデスクを操作できるようにします。

設計思想は エージェントが第一、人が第二 です。すべてのコマンドが非対話的に動作し、データを返すコマンドは構造化された --json エンベロープを出力でき、エラーは期待していた有効な値を列挙し、機械可読なコマンドスキーマによってエージェントは 1 回の呼び出しで全体像を学習し、多くの場面で再利用できます。

別リポジトリ

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

トークンは OS のキーリングに保存されます。CI やコンテナでは、3 つの環境変数が対話的な入力なしに保存済みプロファイルを上書きします：HDMX_HOST、HDMX_SUBDOMAIN、HDMX_TOKEN。

複数テナントは プロファイル で扱います。1 つのプロファイルにホスト、サブドメイン、トークン、既定値一式をまとめます。

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

できること

コマンド体系はヘルプデスクのリソースのまとまりに対応しています。主な領域は次のとおりです。

領域	できること
チケット	一覧、検索、トリアージ、表示、更新、担当割り当て、ステータス／優先度／タグの設定、統合、削除
メッセージ	チケットのメッセージの閲覧、公開返信または内部メモの投稿
チャット	会話の一覧と表示、送信、クローズ、再オープン、参加、退出、既読にする
顧客	一覧、検索、表示、作成、更新、統合
マスターデータ	部門、ステータス、優先度、メールボックス、タグ、ユーザー
レポート	概況、件数、応答時間、エージェント別、バックログ、内訳
アカウント	現在のアカウント、メタデータ、現在のユーザー

特に挙げておきたい 2 つの利点があります。

• 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 が必要です。

全体像の学び方

ヘルプは 3 つの層に分かれ、それぞれ想定する読み手が異なります。

• hdmx <command> --help — 自由文の使い方と例（人向け）。
• hdmx agent-context — すべてのコマンド、フラグ、列挙値、エラーコード、既定値、名前付きワークフローを収めたバージョン付きの機械可読スキーマ（安定した仕様に結び付くエージェント向け）。
• hdmx skills — 複数のコマンドを名前付きの手順書にまとめる組み合わせレシピ（たとえばトリアージして返信する流れ）。

公開 API との関係

hdmx は、ヘルプデスクの 公開 API をブラウザー以外から利用する最初のクライアントです。その動作はすべて、同じ PAT 認証の GraphQL エンドポイントを通り、同じスコープとレート制限に従います。特権的な裏口はありません。API スキーマが契約であり、hdmx は固定した API バージョン に対してビルドされ、API の非推奨ポリシーに従うため、CLI のリリースは互換性のある（破壊的でない）サーバースキーマであれば動作し続けます。