Skip to main content

Install

The Hamtrax CLI and local MCP server ship as one package. Install it globally, then configure your API key once.

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 GitHub and npm during installation, and to *.cloudfunctions.net for 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​

CLI 0.3.0, including MCP support, is available from the official GitHub release. Install its released package with npm:

npm install -g https://github.com/HammerCreativeLLC/Hamtrax-CLI/releases/download/v0.3.0/hamtrax-0.3.0.tgz

Then verify:

hamtrax --version
# 0.3.0

Publication of 0.3.0 to the npm registry is pending. The registry currently provides 0.1.1, so npm install -g hamtrax installs the earlier terminal client without MCP. The GitHub command above installs the released 0.3.0 package directly.

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 where keytar is unavailable, the CLI falls back to ~/.config/hamtrax/config.json with mode 0600 and prints a warning when it stores the key.
  • 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 when you want to skip keytar and use the env var or config-file backend.
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"

This terminal-only example installs the npm registry's 0.1.1 release. For MCP, install the GitHub package from Install in your image.

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
# nativeQsoCount  12

Updating​

To update to 0.3.0 now, repeat the GitHub package command in Install. Updating to 0.3.0 with npm install -g hamtrax@latest is pending its registry publication; the current registry version is 0.1.1.

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​

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

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.