Set Up the LoTW Pipeline
LoTW (Logbook of The World) is the official ARRL system for QSO confirmations and is accepted for most DXCC, WAS, and WAZ awards. HAM-Tools uses the official CLI tool TQSL as a subprocess — you keep full control over certificates and station locations.
Time: 30 minutes the first time, after that uploads run in seconds.
Prerequisites
- LoTW account at arrl.org/logbook-of-the-world (free, postal verification can take 1–2 weeks)
- HAM-Tools installed and license activated
- Internet connection
Phase 1 — Install TQSL.app (one-time)
HAM-Tools does not ship TQSL (ARRL licensing reasons). You install it yourself.
- Download: lotw.arrl.org/lotw-help/installation/ → "TQSL for macOS" (currently 2.8.x)
- Open the DMG, drag TQSL.app into the Applications folder
- First launch: Gatekeeper complains ("unverified developer"). Right-click → "Open" → "Open anyway".
tqsl 2.5+
HAM-Tools supports both tqsl ≥ 2.5 (configs in ~/.tqsl/) and older versions (configs in ~/Library/Application Support/TrustedQSL/). You don't have to decide — the picker finds both.
Phase 2 — Request and Import the ARRL Certificate
- In TQSL.app: Callsign Certificate → Request New Callsign Certificate
- Enter your callsign, country/DXCC, license period
- "Save Request" → creates a
.tq5file - Submit it to ARRL by email (linked at the end of the wizard)
- ARRL mails a postcard to your license address with a verify code (that's why it can take 1–2 weeks)
- After their reply: TQSL.app → Callsign Certificate → Load Certificate → load the
.tq6file ARRL emails you - When loading, you set a cert password — remember it!
TQSL stores the cert in its own data folder (~/.tqsl, older versions ~/Library/Application Support/TrustedQSL), not in the macOS Keychain.
Phase 3 — Create a Station Location in TQSL
A station location describes where you operated (for LoTW's mapping of DXCC multipliers, US states, ITU/CQ zones).
- TQSL.app → Station → Station Locations
- Click "Add"
- Click through the wizard:
- Callsign:
HB9HJI(your licensed call) - DXCC Entity: Switzerland / your country
- CQ Zone: 14 (CH), ITU Zone: 28
- Grid Square: your locator (e.g.
JN47PN) - State / County: only relevant for W/VE
- Callsign:
- Assign a name: e.g.
HB9HJI/HOME(shown in HAM-Tools) - "OK", the station is saved in
~/.tqsl/station_data.xml
Multiple stations
If you operate portable or abroad, create a separate location per site: HB9HJI/JN36, HB9HJI/M-Tuscany, HB9HJI/AM. HAM-Tools always uploads with the location selected in Settings (Phase 4) — switch it there before uploading from a different site.
apply to LoTW: here the TQSL station location determines the site (and thus MY_GRIDSQUARE).
Phase 4 — Link It in HAM-Tools
Now HAM-Tools comes into play.
- Settings → Lookup & Upload (
⌘,→ "Lookup & Upload" tab) - Sub-picker at the top: choose "LoTW"
- tqsl binary: default is
/Applications/Tqsl.app/Contents/MacOS/tqsl— auto-detection should have found the path. If it's empty or the app is elsewhere: click the "📁 Search…" button next to the field → in Finder just click Tqsl.app, and HAM-Tools fills in the binary path automatically. This also works with a Homebrew install (select/opt/homebrew/bin/tqsldirectly). - Station location: open the dropdown → you'll see the locations from Phase 3. Pick your default location (e.g.
HB9HJI/HOME)
Picker empty?
If the dropdown stays empty: the station location wasn't created in TQSL yet. Did you really finish Phase 3? Does ~/.tqsl/station_data.xml (or ~/Library/Application Support/TrustedQSL/station_data.xml) exist? Check in Terminal:
cat ~/.tqsl/station_data.xml
ls -la ~/Library/Application\ Support/TrustedQSL/Phase 5 — Enable Auto-Upload
Three toggles in the LoTW section:
| Toggle | Effect |
|---|---|
| "Automatically upload every logged QSO" | One TQSL call per QSO — recommended for home loggers. Only applies to standard logs (DX) |
| "Mark »QSL sent via LoTW« after successful upload" | Additionally records the general QSL sent status (date + "LOTW") unless one is already present — recommended. Up to 1.56 the switch had no effect from 1.57 |
| "Real-time upload (master)" at the very top | If off, EVERYTHING is paused (for travel/portable without internet) |
Phase 6 — Test the First Upload
- Logbook → select a log, with at least 1 QSO in it
- Select a QSO in the table (or several via ⌘-click)
- Right-click → "Upload to LoTW (tqsl)" (for several: "Upload N QSOs to LoTW (tqsl)") — all selected QSOs go out in a single tqsl call
- If your certificate has a password (Phase 2), tqsl asks for it in its own window — HAM-Tools doesn't store it
- Wait 5–30 seconds — an alert reports the result ("N QSOs uploaded to LoTW" with new / duplicates / errors, or "LoTW upload failed" with the end of the tqsl output). Afterwards the "QSL status" column in the table shows:
| Display | Meaning |
|---|---|
LoTW → (row yellow) | Successfully handed to LoTW |
LoTW ✓ (row green) | The other station uploaded their QSO too + it matched |
Initially you'll only see LoTW → — confirmation comes once the other station uploads on their end.
the log the QSO comes from — even if you open another log while the upload is running.
Phase 7 — Confirmation Sync
After a few days / weeks, some of the other stations have submitted their QSOs to LoTW too. Pull the confirmations:
- One-time: Settings → Lookup & Upload → LoTW, section "Confirmation sync (LoTW web login)" — enter the Username and Password of your lotw.arrl.org account (not the cert password from Phase 2)
- Logbook → "QSL" tab in the bottom tab bar
- Button "Fetch LoTW confirmations" (the same fetch sits behind "Retrieve confirmations now" in Settings)
- HAM-Tools fetches the LoTW report (ADIF) from arrl.org and matches it against the QSOs of the open log on call + date/time (to the minute)
- band + mode; an alert shows how many confirmations were matched and how many are new
- Confirmed QSOs change from
LoTW →toLoTW ✓in the "QSL status" column - The Awards tab shows the new confirmed counters
Matching reliable only from 1.56 from 1.56
Up to 1.55 the fetch found no confirmations because of a parser bug. If you fetched in vain before, simply fetch again now. From 1.57 the sync checks all logbooks, not only the open one; unreadable logbooks are named in the result from 1.57.
Frequency: once a week is enough
LoTW doesn't push confirmations in real time. A weekly sync covers 95%. If a DXpedition QSO matters (the DX operators often don't sync to LoTW until 6 months later), just wait.
Common Problems
"Station Location X could not be found"
→ Typo in the picker. Go to TQSL.app → Station Locations and check the exact name (case matters). Or reopen the picker in HAM-Tools — the dropdown shows the real names.
Cert password is asked for every time
→ That's intentional (security). Saving it would require Keychain item reuse, which we don't do — otherwise you couldn't separate personal/club/contest certs.
"tqsl: error: command-line option 'x' not recognized"
→ You have a very old TQSL version (< 2.5). Update to 2.7+.
Upload ends up in the "rejected" branch even though everything looks OK
→ The error alert contains the end of the raw tqsl output ([tqsl output]). Common cause: the cert has expired (LoTW certs are valid for 3 years), or the mode label (e.g. FT8 vs. MFSK) isn't accepted by tqsl. Running tqsl manually in Terminal reproduces it.
Some QSOs rejected — and none is marked as sent from 1.56
→ If LoTW rejects individual QSOs in a batch upload (or tqsl only processes part of it), HAM-Tools no longer marks any of the QSOs as sent — up to 1.55 they could all count as uploaded. Fix the rejected QSOs using the tqsl output and upload the selection again; LoTW then reports the ones already accepted as duplicates.
"tqsl did not respond within 180 s and was terminated" from 1.56
→ HAM-Tools aborts a hanging tqsl call after 180 seconds. Check your internet connection and the LoTW status, then upload again.
Use eQSL/QRZ instead of LoTW
→ see Settings → Lookup & Upload. Each service has its own toggles, all can run in parallel.
What's Next
- Log Your First POTA QSO — if you haven't yet
- The POTA module and SOTA module read LoTW confirmations automatically for award tracking
- ARRL DXCC + WAS + WAZ awards can be applied for directly at ARRL once you have enough confirmations