Uptime Monitoring from the Command Line: HostTracker CLI

By the HostTracker Team - published August 2026

A monitoring dashboard is great for the moment something is already broken and you want to see it at a glance. It is the wrong tool for the moment monitoring needs to be part of your work instead of a tab you check: a deploy script that should not finish until the new build answers, a cron job that walks a handful of endpoints every morning, an incident where the fastest path is one command instead of a login and three clicks. That is the job a command-line client is built for, and it is what HostTracker's own CLI, ht-cli, does.

ht-cli drives the HostTracker API v2 REST surface from a shell: monitors, contacts, alerts, reports, incidents, maintenance windows, status pages, webhooks and on-demand checks - 139 commands across 14 groups, generated from the same OpenAPI document as the official SDKs, with a hand-written layer on top for auth, output, paging and multi-call protocols. This walkthrough installs it, authenticates it, runs the commands you will reach for most often, and wires it into a CI pipeline. For a shorter version, HostTracker's own command-line monitoring overview covers the same ground.

Why Run Monitoring From a Terminal

A web dashboard is not going away, and for a first glance at "is everything up" it is still the fastest tool. A CLI earns its place for the moments a dashboard cannot reach:

• Scripts and deploy pipelines. A release script can call ht-cli check run against the freshly deployed URL and stop the rollout if it does not answer, instead of shipping first and finding out from an alert later.
• Cron and scheduled jobs. A crontab entry can query monitors or account state on a schedule with no browser session anywhere in the loop.
• CI pipelines. Exit codes and machine-readable output let a workflow gate on a real result instead of a human reading a chart.
• No context switch. Checking a monitor from a terminal - mid-incident, in an SSH session on the box in question - beats opening a browser, finding it, and reading a chart.

ht-cli is built on HostTracker's Go SDK, so it inherits the SDK's retries, idempotency handling and error mapping rather than reinventing them for a shell.

Installing ht-cli

The binary is named ht-cli, not ht - that shorter name is already taken by Homebrew-core's ht editor and by packages of the same name on Debian and Arch. Development happens in the open at github.com/HostTracker/cli, and the CLI ships through most of the channels developers already use, plus a plain install script for anywhere else:

# Homebrew (macOS/Linux)
brew install HostTracker/tap/ht-cli

# Script -> ~/.local/bin
curl -fsSL https://raw.githubusercontent.com/HostTracker/cli/main/install.sh | sh

# Debian/Ubuntu (signed apt repo, one 'stable' suite, amd64+arm64)
curl -fsSL https://hosttracker.github.io/apt/key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/hosttracker.gpg
echo "deb [signed-by=/usr/share/keyrings/hosttracker.gpg] https://hosttracker.github.io/apt stable main" | sudo tee /etc/apt/sources.list.d/hosttracker.list
sudo apt update && sudo apt install ht-cli

# Fedora/RHEL/CentOS Stream (dnf repo; yum on RHEL7/CentOS7; zypper on openSUSE)
sudo curl -fsSL -o /etc/yum.repos.d/hosttracker.repo https://hosttracker.github.io/apt/rpm/hosttracker.repo
sudo dnf install ht-cli

# Arch (AUR)
yay -S ht-cli-bin

# Windows (Scoop)
scoop bucket add hosttracker https://github.com/HostTracker/scoop-bucket
scoop install ht-cli
# Windows (winget) - pending community-repo review
winget install HostTracker.ht-cli

# Docker (two names, same image, linux/amd64+arm64)
docker run --rm -e HT_TOKEN ghcr.io/hosttracker/ht-cli monitors list
docker run --rm -e HT_TOKEN hosttracker/ht-cli monitors list

# Go 1.24+
go install github.com/HostTracker/cli/cmd/ht-cli@latest

A single .deb, .rpm or .apk file is also attached to every release, for anyone who would rather skip the repo setup - Alpine's .apk needs apk add --allow-untrusted since it is not signed the way the apt and dnf repos are. Every Linux package, the Homebrew formula, the AUR package and the release archives ship shell completions on their own; anywhere else, ht-cli completion bash|zsh|fish|powershell prints them for you to wire in.

Authenticating

Authentication is a token, not a username and password. The interactive path prompts for it, checks that it actually works, and stores it with restrictive file permissions:

ht-cli auth login                    # prompts, verifies against GET /account, stores 0600
ht-cli auth status
export HT_TOKEN=...
ht-cli monitors list                 # or: ht-cli --token "$HT_TOKEN" monitors list

Every setting ht-cli reads - the token, the base URL, which profile is active, the output format - resolves in the same fixed order: a command-line flag wins first, then an environment variable (HT_TOKEN, HT_BASE_URL, HT_PROFILE, HT_OUTPUT), then the active profile, then a built-in default. That makes it straightforward to keep separate credentials for separate accounts or environments behind named profiles:

ht-cli auth login --profile staging

HT_CONFIG_DIR points the whole config file somewhere else, which is the cleanest way to hand a CI job its own throwaway profile without ever touching a developer's local config - more on that in the CI section below.

First Commands: Monitors and Checks

A handful of commands cover most of what you will do day to day: read the current state of your monitors, create or edit them, and run one-off checks on demand.

Listing, Inspecting and Creating Monitors

ht-cli monitors list --state down --type http --tag prod
ht-cli monitors get <monitor-id> --expand settings,lastResult
ht-cli monitors create --set name="api health" --set type=http                    --set url=https://api.example.com/health --set interval=5

The list filters (--state, --type, --tag) narrow a large fleet down to what you actually want to look at; --expand pulls related data, like settings or the last result, into the same response instead of a second round trip. create and its sibling update commands build a resource up field by field with repeated --set key=value flags.

Running an Instant Check

ht-cli check run https://www.host-tracker.com --type http --country de --country us --wait
ht-cli check run https://example.com --strict-tls --wait

Repeating --country runs the same check from more than one location at once; --wait blocks until the result is in instead of leaving you to poll for it. The second example's --strict-tls flag turns on strict TLS handshake validation for http checks: a self-signed certificate, an untrusted root, a hostname mismatch or an expired certificate now fails the check outright instead of passing quietly, which is exactly what you want from a certificate-focused check rather than a plain uptime check. It is the same validation behind HostTracker's browser-based SSL certificate checker - and if certificates are the reason you are here, the fuller walkthrough, including the one gap in what strict mode currently catches, is in automating SSL certificate expiry checks.

Bulk Edits and Background Jobs

job=$(ht-cli monitors bulk-update --json @edit.json -o json | jq -r .jobId)
ht-cli jobs wait "$job"

A bulk edit takes a JSON file describing the change, submits it as a background job, and hands back a job id; -o json switches the command's own output to JSON so the id can be piped straight into jq, and jobs wait blocks until that job finishes. That combination is the pattern for scripting a change across many monitors at once instead of clicking through them one by one.

Using ht-cli in CI

In a pipeline, skip the interactive login entirely and set HT_TOKEN as a secret - no config file needs to exist on the runner at all. Add --verbose to any command to trace the request, the response status, the X-Request-Id and the current rate-limit budget to stderr, which is the fastest way to see why a step failed. The Docker image needs no local toolchain install, which suits a lot of CI runners as-is:

docker run --rm -e HT_TOKEN ghcr.io/hosttracker/ht-cli monitors list

Every command's exit code tells the calling script what actually happened, which is more useful in a pipeline than parsing text output:

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.

Code 6 covers two different situations on purpose: a rate_limited throttle is worth retrying after a pause, a quota_exceeded refusal is not. These codes report whether the CLI command itself succeeded, not whether the site it checked is up - that distinction matters for the GitHub Action below, which adds its own up/down semantics on top.

For GitHub Actions specifically, HostTracker publishes a composite action so a workflow does not need an install step at all: HostTracker/check-action, no bundled JavaScript, running ht-cli underneath. It can run a one-off check from real monitoring locations, assert that every one of them sees the site up, or create the monitors a repository declares in a JSON file:

- uses: HostTracker/check-action@v1
  with:
    token: ${{ secrets.HT_TOKEN }}
    mode: assert-up
    url: https://www.example.com

Input	Default	Notes
token	required	your API token, from a repo secret
mode	check	check, assert-up, or create-monitor
url	-	target for check and assert-up
type	http	check type
pools	-	named location pools to run from
json	-	monitor definition file, for create-monitor
timeout	120	seconds to wait for a result
base-url	https://api2.host-tracker.com	override for a different environment
version	the action's own pinned build, or latest	which ht-cli build the action runs
fail-on-down	true	fail the job if the check comes back down

check and assert-up need a token scoped with check:write and check:read; create-monitor needs monitor:write and monitor:read. The action runs on Linux, macOS and Windows runners, both amd64 and arm64. @v1 tracks the whole 1.x line as it gets updates; pin an exact @v1.2.3 tag or a commit @<sha> if a workflow needs precise control over what runs.

What You Need to Use It

Worth being upfront about before you install anything: API, SDK, CLI and MCP access are not part of every plan. The Free, Personal and Webmaster plans do not include API access at all. Using ht-cli for anything beyond evaluation needs a Business or Enterprise plan - or the 30-day trial, which does include full API access with no card required, so you can run everything in this article before deciding on a plan. Start the trial, or compare what each plan includes.

Rate limits scale with the plan behind the token:

Plan	Per minute	Per month
30-day trial	10 reads, 5 writes	10,000 reads, 500 writes
Business	60 reads, 30 writes	100,000 reads, 20,000 writes
Enterprise	120 reads, 60 writes	1,000,000 reads, 100,000 writes

Every response carries RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Policy headers, and a 429 adds Retry-After - the --verbose flag surfaces exactly this budget on stderr, which is worth turning on the first time you script anything at volume. Tokens themselves are shown once at creation and never stored server-side again; a fresh one defaults to a ten-year lifetime but can be scoped down to a shorter expiry, up to ten allowed IP addresses, and a hard request cap. The full endpoint reference, if you want to see everything ht-cli is a shell in front of, is the API v2 documentation.

Where to Go Next

ht-cli is one door into the same API v2 surface as the rest of HostTracker's developer toolkit, and which door fits depends on where the code needs to run. If a check needs to live inside your own application instead of a shell, the official SDKs call the same endpoints from Python, JavaScript, Go and .NET - see our practical tour of the API for what is under all of them. And if what you actually want is to ask an AI assistant to run a check or read back your monitors' state in plain language rather than typing a command, that is what the MCP server is for - the setup is in letting AI assistants run your uptime checks.