Skip to main content
HostTracker
HOST-TRACKER
website monitoring service
Status pages Instant check Price
Login Register

Command line (ht-cli)

Every operation of the Host-Tracker REST API v2 as a command: monitors, incidents, contacts, alerts, reports, maintenance windows, status pages, webhooks and on-demand checks, from a shell or a CI job. The commands are generated from the same published OpenAPI document the API serves, so ht-cli cannot drift behind the API, and it is built on the Go SDK, so the bearer token, the automatic idempotency keys, the retry ladder and the problem-document errors are the SDK's behaviour rather than a second implementation of them.

Install

A single binary, three ways to get it

Homebrew (macOS and Linux, shell completion included):

brew install HostTracker/tap/ht-cli

curl (Linux or macOS, installs into ~/.local/bin):

curl -fsSL https://raw.githubusercontent.com/HostTracker/cli/main/install.sh | sh

Go 1.24 or newer:

go install github.com/HostTracker/cli/cmd/ht-cli@latest

Release binaries for Linux, macOS and Windows are on the releases page: take the archive for your platform, verify it against checksums.txt and put ht-cli on your PATH.

Requires nothing but the binary; Go 1.24 or newer is needed only for the go install route. Outside Homebrew, ht-cli completion bash|zsh|fish|powershell prints the completion script.

Quick start

Authenticate once, then drive the account

ht-cli auth login                       # stores the token 0600
ht-cli monitors list                    # a table, JSON when piped
ht-cli monitors get <monitor-id>
ht-cli check run https://example.com --type http --wait
ht-cli monitors create --json @monitor.json
ht-cli monitors bulk-update --json @edit.json
ht-cli jobs wait <job-id>
ht-cli monitors list --output json | jq -r '.data[].url'

--wait follows a one-off check to its result, and a bulk edit answers with a job id for ht-cli jobs wait.

ht-cli auth login stores the token in a YAML file under the OS configuration directory (ht-cli config path prints it), written 0600. A CI job usually skips it and exports HT_TOKEN instead. Mint the token on the API page with the scopes the integration actually needs.

Output and exit codes

Readable at a terminal, scriptable everywhere else

The default is a table on a terminal and JSON when the answer is piped, so ht-cli monitors list | jq needs no flag and neither does reading it yourself. --output json|yaml|table (or -o) forces it either way. The table view is a reading aid; use JSON for anything a script depends on. 

ht-cli monitors list -o json | jq -r '.data[] | select(.state=="down") | .url'
Code Meaning
0 The command did what it was asked.
1 A failure with no more specific code.
2 The command line was wrong: an unknown flag, a missing argument, a bad value.
3 The credential is missing, rejected or under-scoped.
4 The address names nothing.
5 The API refused the request: validation, a conflict, a precondition.
6 Throttled, or the quota is exhausted.
7 The API could not be reached, or faulted.

A failure prints the RFC 9457 problem document to stderr with the machine code, the human detail, the offending members and the request id to quote in a support request; under -o json the whole document is printed instead, so a script can read it. 429 deliberately splits across two problem codes: rate_limited is worth retrying and quota_exceeded is not, and only the problem code tells them apart. --verbose reports each request, its status, its request id and the rate-limit budget on stderr, retries included, which is the first thing to turn on when an answer surprises you.

Questions about ht-cli belong in its GitHub repository; account and billing matters go to support.