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.

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 POTA activations (with idempotent find-or-create semantics).
  • Create QSOs in contact-holding folders they match -- the same park/month guardrails as the web app apply, and POTA fields auto-populate in a valid activation folder.
  • Delete QSOs (requires an elevated key).

Use the web app or the iOS and Android apps for imports, exports, and maps. Use the CLI when you want to control Hamtrax from a terminal, script, or custom hardware.

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 for shell commands or MCP for a compatible assistant connection.
  • Power users who prefer keyboard over UI for repetitive logging.

How it works​

  1. Install the CLI on your computer.
  2. In the Hamtrax web app, open Tools > Hamtrax CLI and generate an API key.
  3. Run hamtrax auth login and paste the key when prompted. You only need to do this once per device.
  4. Run Hamtrax commands from your terminal, scripts, or custom hardware. Contacts and activations are saved to your Hamtrax logbook.

See Auth and Keys for detailed setup and key-management instructions.

$ hamtrax activations create --reference K-1234 --callsign N0CALL
Activation started: K-1234 (folder: <folder-id>).

$ hamtrax contacts create --callsign W1AW --mode FT8 --frequency 14.074 --folder <folder-id>
Logged QSO <qso-id>.

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​