Skip to main content

CLI Overview

The Hamtrax CLI is a small, focused command-line tool for logging POTA contacts, managing activations, and integrating Hamtrax into your scripts and custom hardware. It's designed to be operated by both humans at a terminal and AI agents calling commands programmatically.

Hamtrax Beaver mascot

What it does​

The CLI exposes a deliberately small slice of Hamtrax functionality -- the parts you actually need from a terminal:

  • whoami -- show your callsign, plan, tier, and native QSO count.
  • List folders, contacts, and activations.
  • Create activations (with idempotent find-or-create semantics).
  • Create QSOs in any of your folders -- POTA fields auto-populate when you log into an activation folder.
  • Delete QSOs (requires an elevated key).

Everything else -- imports, exports, maps -- stays in the web app and the iOS/Android Capacitor builds. The CLI is the integration surface, not a replacement.

Who it's for​

  • Portable operators running a Raspberry Pi or laptop in the field who want to script their logging flow.
  • Custom hardware builders wiring Hamtrax into rig-control software, foot-switch loggers, or display panels.
  • AI agents that need a stable, machine-readable API for logging contacts on a user's behalf -- see AI Agent Guide.
  • Power users who prefer keyboard over UI for repetitive logging.

How it works​

The CLI is a thin Node.js wrapper over a versioned HTTPS API hosted on Hamtrax's Cloud Functions. Each request authenticates with an API key you generate in the web app -- the key is hashed (SHA-256) on the server and shown only once at creation time. See Auth and Keys for the full lifecycle.

$ hamtrax activations create --reference K-1234 --callsign N0CALL
Activation K-1234 ready (folder: act_8a4f...)

$ hamtrax contacts create --callsign W1AW --mode FT8 --frequency 14.074 --folder act_8a4f...
QSO logged (id: qso_92b1...)

Agent-friendly by design​

The CLI is built with three principles that matter for automation:

  • Stable exit codes -- every error class maps to a deterministic exit code (see AI Agent Guide).
  • Structured output -- --json for one-shot calls, --ndjson for streaming list output into pipelines.
  • Self-describing help -- hamtrax help --all dumps the entire command tree to stdout and hamtrax --help-json emits a machine-readable manifest, both versioned alongside the API.

What's next​