BeatLedger FIT Importer

BeatLedger FIT Importer is an optional local terminal tool for bringing Garmin Connect running activities into BeatLedger. BeatLedger and this importer are currently beta software.

The importer supports Garmin running activities only. It does not support other providers or direct integrations yet. You can continue to use manual FIT upload in BeatLedger instead.

Source code, issues, and release history are public at github.com/frankstevens1/beatledger-fit-import.

Before you start

You need:

• An active BeatLedger beta account.
• A Garmin Connect account with running activities.
• uv, which installs and manages the required Python runtime.

Install and import

1. Install the importer and confirm that it can reach BeatLedger:

   uv tool install beatledger-fit-import
   beatledger-fit doctor
   

2. Start an interactive import:

   beatledger-fit import
   

3. When prompted, approve the short code in your browser. Sign in to BeatLedger there, not in the terminal.

4. Enter Garmin credentials locally when prompted, then choose one import mode:

   • Date range imports running activities between two inclusive dates.
   • Individual runs lets you choose from a list of recent runs.
   • Incremental imports Garmin activities BeatLedger has not already recorded.

5. Review the selected runs and confirm before any FIT file is uploaded.

The command finishes with a summary such as:

Imported: 3  Duplicates: 1  Failed: 0

Imported means BeatLedger accepted the selected FIT file for processing. Duplicates are activities BeatLedger already has, and Failed entries are reported with their activity name so you can retry them.

Useful commands

Check your installation and API connection:

beatledger-fit doctor

Preview the runs that would be selected without downloading or uploading FIT files:

beatledger-fit import --dry-run

Keep downloaded FIT files in beatledger-fit-files/ in the current directory. Those files can contain sensitive route and health information; they are deleted by default and this directory is ignored by Git:

beatledger-fit import --keep-files

Remove local Garmin and BeatLedger importer access:

beatledger-fit logout

Update or uninstall the importer:

uv tool upgrade beatledger-fit-import
uv tool uninstall beatledger-fit-import

Privacy and security

• Garmin credentials are entered on your computer and are not sent to BeatLedger. The importer uses them to connect to Garmin.
• Garmin refresh credentials remain on your computer. Your Garmin password is not stored by this tool.
• BeatLedger approval happens in your browser at beatledger.app. The CLI receives a separate, revocable importer authorization, never your browser cookies or email one-time code.
• The importer stores BeatLedger authorization in the system keyring when available; otherwise it uses a restricted local fallback file and tells you when that fallback is used.
• Only FIT files you explicitly select and confirm are uploaded to BeatLedger. They are held in memory and removed locally after upload unless you use --keep-files.
• This application does not include analytics or telemetry.

You can revoke BeatLedger importer access from your BeatLedger Account page, or run beatledger-fit logout to remove local access.

Limitations and troubleshooting

• This is an unofficial, read-only Garmin Connect integration. It is not made by or affiliated with Garmin and may stop working if Garmin changes its service.
• The importer handles Garmin running activities only. Manual FIT upload is the fallback for other sources or unavailable Garmin downloads.
• If browser approval expires, run beatledger-fit import again and approve a new code.
• If Garmin login or download fails, verify your Garmin account and MFA code, then retry the selected activity.
• Run beatledger-fit doctor to check your Python version and BeatLedger API connection.

For setup instructions within BeatLedger, see the BeatLedger importer guide. Report security concerns under the process in SECURITY.md; report bugs at the GitHub issue tracker.

Local development

To test against a local BeatLedger API instead of the default production API:

BEATLEDGER_API_URL=http://127.0.0.1:8000 uv run beatledger-fit doctor
BEATLEDGER_API_URL=http://127.0.0.1:8000 uv run beatledger-fit import --dry-run

Use the local HTTP override only for trusted local development. See local testing for the required Supabase, API, and browser-approval setup, and releasing for publication steps.

Development checks

uv sync --all-groups --locked
uv run ruff check .
uv run pytest -q
uv build

Do not use a personal Garmin account in automated tests. Live testing should use a dedicated account and must never record credentials, tokens, activity responses, or FIT files.