Command Reference

Complete reference for every hamtrax command. Each entry lists the description, the full flag set, and at least two worked 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 Hamtrax API key: ******************************
# Stored in keychain. Tier: basic. Callsign: N0CALL.

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

hamtrax auth set-key <key>

Non-interactive variant of auth login. Accepts the key as an argument or piped on stdin. Useful for provisioning scripts.

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 the currently configured key prefix, tier, and callsign by calling GET /v1/whoami. Does not print the plaintext key.

Flags: --json

hamtrax auth status
# Key prefix: htx_live_a4b
# Tier:       basic
# Callsign:   N0CALL

hamtrax auth status --json
# {"keyPrefix":"htx_live_a4b","tier":"basic","callsign":"N0CALL"}

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 auth panic-revoke for that.

Flags: none.

hamtrax auth logout

hamtrax auth logout && hamtrax auth status
# Error: no API key configured. Run `hamtrax auth login`. (exit 3)

hamtrax auth panic-revoke

Revokes the currently configured key on the server. After this completes, the key is permanently dead -- subsequent requests return 401 key_revoked.

Flags: --yes (skip confirmation prompt)

hamtrax auth panic-revoke
# This will revoke the key 'htx_live_a4b' on the server. Continue? [y/N]

# Non-interactive (e.g. from a security script)
hamtrax auth panic-revoke --yes

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
# QSOs:     12 / 200

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

hamtrax folders list

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

Flags:

• --type <activation|category|monthly> -- filter by folder type
• --limit <N> -- page size (default 50, max 200)
• --cursor <id> -- opaque pagination cursor returned by the previous page
• --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

# Stream the entire folder via cursor pagination
hamtrax contacts list --folder fld_8a4f0c2b9e1d --ndjson > activation.ndjson

hamtrax contacts create

Creates a QSO. Hits POST /v1/contacts. If the target folder is an activation folder, the server auto-populates mySig=POTA and mySigInfo=<reference> -- you don't need to set them.

Flags:

• --folder <id> -- required destination folder
• --callsign <call> -- required worked station callsign
• --frequency <MHz> -- required, in MHz (e.g. 14.074)
• --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
• --rst-rcvd <report> -- optional signal report received
• --name <name> -- optional operator name
• --notes <text> -- optional free-form notes
• --json

hamtrax contacts create \
  --folder fld_8a4f0c2b9e1d \
  --callsign W1AW \
  --frequency 14.074 \
  --mode FT8 \
  --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-rcvd 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. Missing or not-owned QSOs both return 404 not_found (deliberate -- existence is not leaked).

Flags: --yes (skip confirmation prompt)

hamtrax contacts delete qso_92b1f4d2e8a0
# Delete QSO qso_92b1... (W1AW, FT8, 2026-05-07)? [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 filter where endTime == null.

Flags:

• --in-progress -- filter to activations that haven't been ended
• --limit <N> -- page size (default 50, max 200)
• --cursor <id> -- pagination cursor
• --json / --ndjson

hamtrax activations list --in-progress

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

hamtrax activations create

Idempotently finds-or-creates an activation folder. Hits POST /v1/activations. Same (callsign, locationReference, date) always resolves to the same folder, so calling this twice from two scripts is safe -- you'll get the same id back.

Flags:

• --reference <ref> -- required, e.g. K-1234. Format: ^[A-Z]{1,2}-\d{1,5}$/i (case-insensitive).
• --callsign <call> -- required activator callsign
• --program <id> -- optional program id, defaults to pota
• --location-name <name> -- optional human label
• --start-time <ISO> -- optional ISO 8601 start 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 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.0

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

Global flags

These apply to every command:

• --json -- emit a single JSON object for the invocation. Mutations: { id, ... }. Lists: { items, cursor }. Errors: { error, message, details, requestId }.
• --ndjson -- list-only. One JSON object per line, no wrapper. Designed for streaming into agent pipelines.
• --verbose -- include HTTP request/response details on stderr. See Troubleshooting.
• --quiet -- suppress non-error output.
• --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.

Related pages

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