Skip to content
Sign in
Start here

beatledger FIT Importer

What it does

beatledger FIT Importer is an optional local tool for Garmin Connect users. It is the easier alternative to manual FIT uploads in the app when bringing across history or keeping Garmin runs up to date. It can import a date range, selected recent runs, or only activities beatledger has not already seen.

The importer supports Garmin running activities only. It is read-only, unofficial, and is not made by or affiliated with Garmin.

Install and check setup

The importer can be installed with uv, which manages the required Python runtime for you. You do not need to install Python, create a virtual environment, or use pip.

  1. Open FIT Importer downloads and install uv for your operating system and use it to install the importer.
  2. After successfully installing uv and the importer and check that it can reach beatledger:
beatledger-fit doctor

doctor checks your Python version and beatledger API connection. It does not import activities.

Authorize and import

Start the importer, then choose date range, individual runs, or incremental import when prompted:

beatledger-fit import
  1. The terminal shows a short approval code and opens beatledger in your browser.
  2. Sign in to beatledger there and approve that code.
  3. Enter Garmin credentials locally if needed, then select runs.
  4. Review the list and confirm before any FIT file is uploaded.

The final summary reports Imported, Duplicates, andFailed. Imported files have been accepted by beatledger for processing; duplicates are activities beatledger already has.

Choose imports

  • Date range: import running activities between inclusive local dates.
  • Individual runs: browse recent runs and select exactly what to import.
  • Incremental: checks beatledger for Garmin activity IDs and imports only missing runs after your latest recorded Garmin import, with a short overlap for delayed sync.

Downloaded FIT files are deleted after upload by default. Choose the tool's explicit keep-files option only when you want a local copy. beatledger receives only FIT files you select, then processes them under the same privacy terms as a manual FIT upload.

What stays local

Garmin credentials are entered and stored on your computer; they are not sent to beatledger. Your Garmin password is not stored by the importer. The tool stores its separate beatledger authorization locally so you do not need to approve every import. You can revoke that authorization from Account or remove local Garmin and beatledger access with:

beatledger-fit logout

beatledger sign-in happens in your browser. The CLI never receives browser cookies or email one-time codes. FIT files are kept in memory and deleted locally after upload unless you explicitly run beatledger-fit import --keep-files.

Updates and source

Update the installer with uv tool upgrade beatledger-fit-import. The importer source, issue tracker, and release history are available at github.com/frankstevens1/beatledger-fit-import.

Troubleshooting

  • Run beatledger-fit doctor first; it checks the local setup and beatledger connection.
  • If browser approval expires, start the sign-in step again from the importer.
  • Use beatledger-fit logout to remove local Garmin and beatledger access, then sign in again.
  • Use manual FIT upload if Garmin login or download is unavailable, or for another source.