hdmx — the helpdesk CLI

hdmx is a single-binary command-line client for the helpdesk. It wraps the public GraphQL API behind ergonomic resource-and-verb commands so that both AI agents and people can drive the helpdesk from a terminal or a script instead of the browser.

It is designed agent-first, human-second: every command runs non-interactively, every data command can emit a structured --json envelope, errors enumerate the valid values they expected, and a machine-readable command schema lets an agent learn the whole surface in one call and reuse it across many.

Separate repository

The CLI ships from its own repository, github.com/mirasvit/hdmx — it is not part of the helpdesk codebase. The helpdesk side only provides the public API and Personal Access Tokens that hdmx authenticates against. That repo's README is the live source of truth for the current command list; this page is the orientation and the contract it relies on.

Installing

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

Pre-built binaries (Linux, macOS, Windows), a Homebrew tap, and a container image are published with each release. hdmx version prints the version, build date, and the API schema version the binary was built against.

Authenticating

hdmx authenticates with a Personal Access Token — see Public API → Authentication. Create a token yourself in the agent app under Settings → API tokens; it carries scopes, a mandatory IP allowlist, and an expiry.

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

The token is stored in the operating-system keyring. For CI and containers, three environment variables override the stored profile with no interactive prompt: HDMX_HOST, HDMX_SUBDOMAIN, HDMX_TOKEN.

Multiple tenants are handled with profiles — one profile bundles a host, a subdomain, a token, and a set of defaults:

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

What it can do

The command surface maps onto the helpdesk's resource families. The headline areas:

Area	What you can do
Tickets	list, search, triage, show, update, assign, set status / priority / tags, merge, delete
Messages	read a ticket's messages, post a public reply or an internal note
Chat	list and show conversations, send, close, reopen, join, leave, mark read
Customers	list, search, show, create, update, merge
Reference data	departments, statuses, priorities, mailboxes, tags, users
Reports	overview, volume, response times, per-agent, backlog, breakdowns
Account	current account, metadata, current user

Two conveniences worth calling out:

• Names instead of IDs. Flags accept either a human name or an ID — --status open, --assignee [email protected], or the raw identifier all resolve. The mapping is cached locally per account.
• Named workflows. hdmx tickets triage runs the standard triage view (open, not closed, not a feature request, ordered by priority) without the caller having to re-derive the filter each time.

Output and safety

• Structured by default for machines. Piped output is a JSON envelope (ok, data, summary, warnings, error, meta); a TTY gets readable Markdown. --jq filters JSON inline. Data goes to stdout, diagnostics to stderr.
• Teaching errors. When a value is rejected, the error names the valid values and a concrete next command — e.g. a bad status returns the list of real statuses and an example invocation.
• Bounded responses. List commands have a default page size and a hard cap; when output is clipped, the response says so and tells you how to narrow it. This keeps responses inside an agent's token budget.
• Dry-run and approval gates. Every mutation accepts --dry-run (renders the operation and its projected effect without sending it). Destructive actions require --force; posting customer-visible messages or internal notes requires --approve.

Learning the surface

There are three layers of help, aimed at three audiences:

• hdmx <command> --help — free-text usage and examples (for people).
• hdmx agent-context — a versioned, machine-readable schema of every command, flag, enum, error code, default, and named workflow (for agents binding to a stable surface).
• hdmx skills — composition recipes that bind several commands into a named runbook (e.g. a triage-and-respond flow).

Relationship to the public API

hdmx is the first non-browser consumer of the helpdesk's public API. Everything it does goes through the same PAT-authenticated GraphQL endpoint, under the same scopes and rate limits — there is no privileged backdoor. The API schema is the contract; hdmx is built against a pinned API version and follows the API's deprecation policy, so a CLI release keeps working against any compatible (non-breaking) server schema.