Command Reference

Complete reference for every hamtrax command. Each entry lists the description, the published flag set, and examples. Global flags (--json, --ndjson, --verbose, --quiet, --api-base, --no-color) are listed once at the bottom.

note

This page is hand-authored. The published CLI's hamtrax help --all (and the machine-readable hamtrax --help-json) is authoritative if the two diverge -- file an issue at HammerCreativeLLC/Hamtrax-CLI so we can sync the docs.

`hamtrax auth login`

Interactive sign-in. Prompts you to paste a key, validates it against GET /v1/whoami, and stores it in your OS keychain (or config-file fallback).

Flags: none.

hamtrax auth login
# ? Paste your htx_live_ API key: ******************************
# Logged in as N0CALL (tier: basic).

# After login, confirm with whoami
hamtrax auth login && hamtrax whoami

`hamtrax auth set-key <key>`

Non-interactive key storage. Accepts the key as an argument or piped on stdin. It validates the key prefix locally, then stores the key without calling GET /v1/whoami.

Flags: none.

# Pipe (preferred — never appears in shell history)
echo "htx_live_xxxxxxxxxxxxxxxxxxxxxxxx" | hamtrax auth set-key

# Argument form (visible in shell history; use the pipe in shared environments)
hamtrax auth set-key htx_live_xxxxxxxxxxxxxxxxxxxxxxxx

`hamtrax auth status`

Shows where the active key comes from, the safe key prefix, and, when a key is configured, identity details from GET /v1/whoami. Does not print the plaintext key.

Flags: --json

hamtrax auth status
# source          keychain
# keyPrefix       htx_live_a4b
# callsign        N0CALL
# plan            free
# tier            basic
# nativeQsoCount  3

hamtrax auth status --json
# {"source":"keychain","keyPrefix":"htx_live_a4b","whoami":{"callsign":"N0CALL","plan":"free","tier":"basic","nativeQsoCount":3}}

`hamtrax auth logout`

Removes the configured key from the keychain and deletes any ~/.config/hamtrax/config.json fallback. Does not revoke the key on the server; use the Hamtrax CLI tool in the web app's sidebar for server-side revocation.

Flags: none.

hamtrax auth logout

hamtrax auth logout && hamtrax auth status
# Not logged in. Run `hamtrax auth login`.

`hamtrax auth panic-revoke`

Prints the server-side revocation path. In the published 0.1.1 CLI, this command does not revoke the key; use the Hamtrax CLI tool in the web app's sidebar for server-side revocation, or auth logout for local removal only.

Flags: none.

hamtrax auth panic-revoke
# Server-side key revocation is not available from the CLI.
# Visit https://hamtrax.com/cli/security to revoke this key.

`hamtrax whoami`

Returns the user's callsign, plan, tier, and native QSO count. Hits GET /v1/whoami.

Flags: --json

hamtrax whoami
# callsign        N0CALL
# plan            free
# tier            basic
# nativeQsoCount  3

hamtrax whoami --json
# {"callsign":"N0CALL","plan":"free","tier":"basic","nativeQsoCount":3}

`hamtrax folders list`

Lists folders owned by the requester. Hits GET /v1/folders with an optional ?type= filter.

Flags:

--type <activation|category|monthly> -- filter by folder type
--json / --ndjson

hamtrax folders list --type activation
# id           name                       type        startTime
# fld_8a4f...  N0CALL@K-1234-20260507    activation  2026-05-07T14:30:00Z
# fld_2c1a...  N0CALL@K-7777-20260423    activation  2026-04-23T18:15:00Z

# NDJSON for piping into a streaming consumer
hamtrax folders list --ndjson | jq -r 'select(.type=="activation") | .id'

`hamtrax folders show <id>`

Shows a single folder's metadata. Currently a client-side filter over folders list; ships in v0.1.

Flags: --json

hamtrax folders show fld_8a4f0c2b9e1d

hamtrax folders show fld_8a4f0c2b9e1d --json | jq '.locationReference'
# "K-1234"

`hamtrax contacts list --folder <id>`

Lists QSOs in a folder. Hits GET /v1/folders/:folderId/contacts. Folder ownership is validated server-side -- you'll get 404 not_found for folders you don't own.

Flags:

--folder <id> -- required folder id
--limit <N> -- page size (default 50, max 200)
--cursor <id> -- opaque pagination cursor
--json / --ndjson

hamtrax contacts list --folder fld_8a4f0c2b9e1d --limit 10

# Export the current page as NDJSON
hamtrax contacts list --folder fld_8a4f0c2b9e1d --ndjson > activation.ndjson

`hamtrax contacts create`

Creates a QSO. Hits POST /v1/contacts. The CLI sends the current ISO timestamp when --time-on is omitted. The destination must be a contact-holding folder: All Contacts and category folders are rejected, a monthly folder requires the contact's UTC month to match, and an activation folder must have one supported program and a valid matching reference. A custom folder refuses a contact whose sig/sigInfo or mySig/mySigInfo pair names a supported program (POTA, DX, REPEATER) — that contact belongs in the program's activation or monthly folder, and the rejection names it. A No Program custom folder that QRZ sync creates, such as October 2026 - No Program, also requires the contact's UTC month to match. In a valid POTA activation folder, the server auto-populates mySig=POTA, mySigInfo=<reference>, and the activation link -- you don't need to set them. Unknown, ambiguous, or malformed folder identity is rejected rather than guessed. QRZ sync treats the accepted contact as it treats contacts logged in the app: it syncs only with a connected QRZ logbook whose callsign matches the contact's station callsign — the activation's callsign in an activation folder, otherwise your account callsign — and only while that logbook has Automatically sync with QRZ on or you select Sync now there. It must have enough recorded identity for a safe match or create; ambiguous contacts wait for review.

Flags:

--folder <id> -- required destination folder
--callsign <call> -- required worked station callsign
--frequency <MHz> -- required, in MHz (e.g. 14.074). Send MHz; a kHz value such as 14074 is converted to MHz before the contact is stored
--mode <mode> -- required (e.g. FT8, SSB, CW)
--time-on <ISO> -- optional ISO 8601 timestamp; defaults to now if omitted
--rst-sent <report> -- optional signal report sent: 59, 599, or a dB signal-to-noise report such as -15 for FT8 and the other WSJT-X digital modes. A dB report is tidied to the way WSJT-X writes it, so -5 is stored as -05
--rst-received <report> -- optional signal report received, in the same shapes
--name <name> -- optional operator name
--notes <text> -- optional free-form notes
--idempotency-key <key> -- available in CLI 0.2.0; optional operation identity for retries. Reuse the same key, fields, and explicit --time-on timestamp
--json

hamtrax contacts create \
  --folder fld_8a4f0c2b9e1d \
  --callsign W1AW \
  --frequency 14.074 \
  --mode FT8 \
  --rst-sent -13 \
  --rst-received +02 \
  --time-on 2026-05-07T15:42:00Z

# Voice contest exchange with notes
hamtrax contacts create \
  --folder fld_2c1a... \
  --callsign K5ZD \
  --frequency 7.185 \
  --mode SSB \
  --rst-sent 59 \
  --rst-received 59 \
  --name "Randy" \
  --notes "Contest exchange"

`hamtrax contacts delete <qsoId>`

Deletes a QSO. Hits DELETE /v1/contacts/:qsoId. Requires an elevated key -- a basic key returns 403 tier_insufficient and the CLI exits with code 5. A missing or not-owned QSO is treated as already deleted, so the command succeeds without changing contacts or counts. Deletion is local to Hamtrax. QRZ records remain intact, and known QRZ counterparts stay excluded from incoming sync until explicitly restored.

Flags: --yes (skip confirmation prompt), --json, and --idempotency-key <key> (CLI 0.2.0; reuse on a retry of the same deletion)

hamtrax contacts delete qso_92b1f4d2e8a0
# Delete QSO qso_92b1f4d2e8a0? This cannot be undone. [y/N]

# Bulk delete from a list, no prompts
hamtrax contacts list --folder fld_2c1a... --json \
  | jq -r '.items[].id' \
  | xargs -I{} hamtrax contacts delete {} --yes

`hamtrax activations list`

Lists activation folders. Hits GET /v1/activations. Use --in-progress to select activations that have started and have not ended. See Pagination for continuing through filtered pages.

Flags:

--in-progress -- filter to activations that have started and haven't been ended
--limit <N> -- maximum folders scanned per page (default 50, max 200)
--cursor <id> -- opaque pagination cursor; use the same filters on the next request
--json / --ndjson

hamtrax activations list --in-progress

hamtrax activations list --json | jq '.items[] | {id, locationReference, startTime}'

`hamtrax activations create`

Idempotently finds or creates a POTA activation folder under All Contacts → Activations. Hits POST /v1/activations. The same program, callsign, normalized reference, and UTC start day returns the same activation folder, even when two clients ask at once. Hamtrax refuses a conflicting or malformed existing folder rather than adopting or overwriting it. POTA is the only CLI activation program today; unknown, empty, or non-text program IDs fail validation rather than defaulting to POTA. Hamtrax's other activity programs are hunting-only, so passing one of their ids (dx, repeaters) is rejected as well — with a distinct "does not support activations" message rather than the unknown-program one.

Flags:

--reference <ref> -- required, e.g. K-1234. POTA format: 1–3 letters, a hyphen, then digits; input is trimmed and normalized to uppercase.
--callsign <call> -- required activator callsign
--program <id> -- optional registered program id; currently only pota, which is also the default
--location-name <name> -- optional human label
--start-time <ISO> -- optional ISO 8601 start timestamp
--idempotency-key <key> -- available in CLI 0.2.0; optional operation identity for retries. Reuse the same key, fields, and explicit --start-time timestamp
--json

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

# With a planned start and human label
hamtrax activations create \
  --reference K-7777 \
  --callsign N0CALL \
  --location-name "Mount Tam" \
  --start-time 2026-05-08T14:00:00Z \
  --json

`hamtrax mcp` / `hamtrax-mcp`

CLI 0.2.0 adds the local MCP server over standard input/output. Both commands run the same server with the CLI's existing credential storage and API endpoint configuration. Standard output carries MCP messages. See MCP: Connect an AI Assistant for connection setup and release availability.

Flags:

--allow-writes -- expose contact and POTA activation creation tools
--allow-deletes -- expose contact deletion; requires an elevated key and exact contact-ID confirmation
--api-base <url> -- override the API endpoint; HAMTRAX_API_BASE is also supported

The default exposes only the four read tools. The two access flags are independent. Every MCP write requires idempotency_key; contact creation requires time_on, and activation creation requires start_time.

hamtrax mcp
# For an assistant configured to allow creation:
hamtrax-mcp --allow-writes

`hamtrax help [command]` / `hamtrax help --all`

Prints help for a single command, or the entire command tree with --all. The --all form is the LLM-readable surface -- it dumps everything to stdout in one go (no pager) so an agent can cache it. See AI Agent Guide.

hamtrax help contacts create

# Capture the entire help corpus for an agent
hamtrax help --all > hamtrax-help.txt

`hamtrax --version` / `hamtrax --help-json`

Prints the package version, or a structured JSON manifest of every command, flag, and example. The JSON form includes cli_version and api_version so an LLM can pin its understanding to a release.

hamtrax --version
# 0.1.1

hamtrax --help-json | jq '{cli_version, api_version, commands: [.commands[].name]}'

Global flags

These are accepted as global flags by the published CLI. Output-format support is command-dependent:

--json -- emit a single JSON object where supported. Mutations: { id, ... }. Lists: { items, cursor }. CLI-formatted errors include { command, error, message, exitCode, ... }.
--ndjson -- list-only. One JSON object per line, no wrapper. Designed for streaming into agent pipelines.
--verbose -- accepted global flag for verbose logging.
--quiet -- accepted global flag for suppressing non-error output; output suppression is command-dependent in 0.1.1.
--api-base <url> -- override the API base URL (use for staging or local dev). Default points at production.
--no-color -- disable ANSI color codes. Color is auto-disabled when stdout is not a TTY.

Examples -- end-to-end workflows
AI Agent Guide -- agent-friendly usage, exit codes
Auth and Keys -- key generation and storage
Troubleshooting

hamtrax auth login​

hamtrax auth set-key <key>​

hamtrax auth status​

hamtrax auth logout​

hamtrax auth panic-revoke​

hamtrax whoami​

hamtrax folders list​

hamtrax folders show <id>​

hamtrax contacts list --folder <id>​

hamtrax contacts create​

hamtrax contacts delete <qsoId>​

hamtrax activations list​

hamtrax activations create​

hamtrax mcp / hamtrax-mcp​

hamtrax help [command] / hamtrax help --all​

hamtrax --version / hamtrax --help-json​

Global flags​

Related pages​

`hamtrax auth login`

`hamtrax auth set-key <key>`

`hamtrax auth status`

`hamtrax auth logout`

`hamtrax auth panic-revoke`

`hamtrax whoami`

`hamtrax folders list`

`hamtrax folders show <id>`

`hamtrax contacts list --folder <id>`

`hamtrax contacts create`

`hamtrax contacts delete <qsoId>`

`hamtrax activations list`

`hamtrax activations create`

`hamtrax mcp` / `hamtrax-mcp`

`hamtrax help [command]` / `hamtrax help --all`

`hamtrax --version` / `hamtrax --help-json`

Global flags

Related pages