Metadata-Version: 2.5
Name: beatledger-fit-import
Version: 0.1.0
Summary: Local, interactive Garmin FIT importer for BeatLedger
Project-URL: Documentation, https://beatledger.app/docs/fit-importer
Project-URL: Homepage, https://beatledger.app
Project-URL: Issues, https://github.com/frankstevens1/beatledger-fit-import/issues
Project-URL: Repository, https://github.com/frankstevens1/beatledger-fit-import
Author: BeatLedger
License: MIT License
        
        Copyright (c) 2026 BeatLedger
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: beatledger,fit,garmin,running
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Requires-Dist: garminconnect>=0.2.28
Requires-Dist: httpx>=0.28.0
Requires-Dist: keyring>=25.0.0
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: rich>=13.9.0
Requires-Dist: typer>=0.15.0
Description-Content-Type: text/markdown

# BeatLedger FIT Importer

BeatLedger FIT Importer is an optional local terminal tool for bringing Garmin Connect running activities into [BeatLedger](https://beatledger.app). 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](https://github.com/frankstevens1/beatledger-fit-import).

## Before you start

You need:

- An active BeatLedger beta account.
- A Garmin Connect account with running activities.
- [uv](https://docs.astral.sh/uv/getting-started/installation/), which installs and manages the required Python runtime.

## Install and import

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

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

2. Start an interactive import:

   ```bash
   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:

```text
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:

```bash
beatledger-fit doctor
```

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

```bash
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:

```bash
beatledger-fit import --keep-files
```

Remove local Garmin and BeatLedger importer access:

```bash
beatledger-fit logout
```

Update or uninstall the importer:

```bash
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](https://beatledger.app/docs/fit-importer). Report security concerns under the process in [SECURITY.md](SECURITY.md); report bugs at the [GitHub issue tracker](https://github.com/frankstevens1/beatledger-fit-import/issues).

## Local development

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

```bash
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](docs/LOCAL_TESTING.md) for the required Supabase, API, and browser-approval setup, and [releasing](docs/RELEASING.md) for publication steps.

## Development checks

```bash
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.
