Metadata-Version: 2.4
Name: garmin-ical-export
Version: 2.0.0
Summary: Export Garmin Connect activities to iCalendar file
Home-page: https://github.com/jirikuchta/garmin-ical-export
Author: Jiri Kuchta
Author-email: jiri.kuchta@email.cz
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: vobject
Requires-Dist: garth
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Garmin iCAL Export
Garmin Connect currently only supports publishing a calendar of planned workouts for the next 30 days ([source](https://support.garmin.com/ms-MY/?faq=UVAoDoRAgl1d75WQc4aGEA)).
Unfortunately, there is no native way to export or publish your past activities. This package provides a CLI tool designed to bridge that gap.

The tool exports your activity history into an [iCalendar](https://en.wikipedia.org/wiki/ICalendar) (.ics) file, which can be imported into any calendar application.

To keep your calendar synchronized with Garmin Connect, you will need to:
1. Schedule a periodic job to run the CLI tool.
2. Host the generated iCalendar file at a public or accessible URL.
3. Subscribe to that URL from your preferred calendar client.



## Installation
```bash
pip3 install garmin-ical-export
```

## Usage
```
usage: garmin-ical-export [-h]
                          [--activity_type {running,cycling,swimming,multi_sport,fitness_equipment,hiking,walking,winter_sports,other,all}]
                          [--limit LIMIT]
                          [--measurement_system {metric,imperial}]
                          [--target_file TARGET_FILE]
                          [login_email]

Exports Garmin Connect activities to iCalendar file.

positional arguments:
  login_email           your Garmin Connect login e-mail (falls back to the
                        GARMIN_ICAL_EXPORT_EMAIL env var, then an interactive
                        prompt)

optional arguments:
  -h, --help            show this help message and exit
  --activity_type {running,cycling,swimming,multi_sport,fitness_equipment,hiking,walking,winter_sports,other,all}
                        export only specific type of activity
  --limit LIMIT         max. number of activities to export
  --measurement_system {metric,imperial}
                        which system to use to calculate activity properties
  --target_file TARGET_FILE
                        target .ics file (prints to stdout if not passed)

```

Your password is never accepted as a command-line argument — it's always read from the `GARMIN_ICAL_EXPORT_PASSWORD` env var or an interactive, hidden prompt. See [Security note](#security-note) below.

## Examples
Export all activities, print the result (password prompted interactively).
```bash
garmin-ical-export <GARMIN_CONNECT_EMAIL>
```
Export only `running` activities, save the result to `garmin_activities.ics` file inside home folder.
```bash
garmin-ical-export <GARMIN_CONNECT_EMAIL> --activity_type running --target_file ~/garmin_activities.ics
```
Run non-interactively, e.g. from a cron job, without exposing credentials as command-line arguments.
```bash
GARMIN_ICAL_EXPORT_EMAIL=<GARMIN_CONNECT_EMAIL> GARMIN_ICAL_EXPORT_PASSWORD=<GARMIN_CONNECT_PASSWORD> garmin-ical-export --target_file ~/garmin_activities.ics
```

## Security note
`login_email` is optional and may be passed as a command-line argument, but `password` never is — it's always read from the `GARMIN_ICAL_EXPORT_PASSWORD` env var, or an interactive, hidden prompt if that's not set. This avoids the password ever ending up in your shell history or being visible to other users on the machine via the process list (`ps`). `login_email` falls back the same way, via `GARMIN_ICAL_EXPORT_EMAIL`, if you'd rather not pass it as an argument either.

After a successful login, the tool caches your session (not your password) in a `garmin-ical-export-session` file in your system's temp directory, so you won't be prompted for MFA on every run. Delete that file to force a fresh login.

## Development
See [AGENTS.md](./AGENTS.md) for local setup and running tests.

## License
[MIT](./LICENSE)
