Skip to main content

Install

The Hamtrax CLI ships as a single npm package. Install it globally, configure your API key once, and you're online.

Requirements​

  • Node.js 20 or newer. The CLI is published as ESM and uses modern crypto and fetch APIs that landed in Node 20.
  • npm 9 or newer (bundled with Node 20+).
  • Internet access to *.cloudfunctions.net -- the CLI talks to Hamtrax's hosted API.

To check your Node version:

node --version
# v20.11.0  (or newer)

If you're below 20, install the latest LTS from nodejs.org or use a version manager like nvm or fnm.

Install​

npm install -g hamtrax

Then verify:

hamtrax --version

Platform notes​

macOS​

  • Works on Intel and Apple Silicon.
  • API keys are stored in the macOS Keychain by default via keytar. You may be prompted by the OS the first time the CLI writes a key -- click Always Allow.
  • If you installed Node via Homebrew, you may need to use a Node version manager to avoid permission errors with npm install -g.

Linux​

  • Works on any glibc-based distro that ships Node 20.
  • API keys are stored in the system Secret Service (GNOME Keyring, KWallet) via keytar. On headless servers without a Secret Service, the CLI falls back to ~/.config/hamtrax/config.json with mode 0600 and prints a one-time stderr warning.
  • To force the config-file path explicitly (CI, Docker), set HAMTRAX_NO_KEYRING=1.

Windows​

  • Works on Windows 10 and 11.
  • API keys are stored in the Windows Credential Manager via keytar.
  • Use PowerShell or Windows Terminal -- legacy cmd.exe works but lacks color and Unicode glyph support in some commands.

Docker / CI​

  • Set HAMTRAX_API_KEY as an environment variable. The CLI prefers the env var over keychain or config-file storage. See Auth and Keys.
  • Set HAMTRAX_NO_KEYRING=1 to skip the keychain probe entirely (it errors fast on systems without a Secret Service daemon).
docker run -e HAMTRAX_API_KEY=htx_live_xxxxxxxxxxxxxxxxxxxxxxxx \
  -e HAMTRAX_NO_KEYRING=1 \
  node:20-alpine \
  sh -c "npm i -g hamtrax && hamtrax whoami --json"

First run​

Once installed, log in interactively:

hamtrax auth login

You'll be prompted to paste an API key generated in the Hamtrax web app. See Auth and Keys for the full flow.

A successful smoke test:

hamtrax whoami
# callsign: N0CALL
# plan:     free
# tier:     basic
# QSOs:     12 / 200

Updating​

npm install -g hamtrax@latest

The CLI is independently versioned from the HTTPS API (/v1/). A new CLI release won't break older keys, and an API change will roll out without forcing a CLI upgrade. Check the Changelog before upgrading if you have automation pinned to specific output formats.

Uninstall​

npm uninstall -g hamtrax
hamtrax auth logout   # before uninstall, to clear keychain entries

If you forgot to log out before uninstalling, you can manually remove the keychain entry under the service name hamtrax-cli in your OS keychain manager, or delete ~/.config/hamtrax/config.json.