Mi Fitness Sync
An unofficial Python CLI for accessing Mi Fitness workout data and manually syncing activities that failed to reach Strava.
Why This Exists
Mi Fitness is the Android app used by Xiaomi wearable devices. When a workout is recorded on the watch, the data is synced to the phone over Bluetooth/BLE and then uploaded to the Mi Fitness cloud under the user's Xiaomi account.
Mi Fitness officially supports third-party integrations such as Strava. In practice, workout activities are sometimes not uploaded to Strava even though they appear inside Mi Fitness.
I created this project because I wanted a way to manually sync workouts that were recorded in Mi Fitness but never made it to Strava.
What This Is Good For
This is mainly useful if you want to:
- Confirm that your workouts really exist in Mi Fitness cloud storage
- Inspect recent activities when Mi Fitness fails to push them to Strava
- Pull activity data yourself instead of waiting for the official sync to work
- Export one or many workouts to GPX, TCX, or FIT for manual backup or re-upload
- Upload workouts directly to Strava with duplicate detection
Install
Python 3.12 or newer is required.
Install from PyPI:
pip install mi-fitness-sync
Or install it as a standalone tool with uv:
uv tool install mi-fitness-sync
Then run with:
mi-fitness-sync --help
Or from a checkout without installing:
uv run main.py --help
Strava API Setup
Before using any Strava commands you need a Strava API application:
- Go to https://www.strava.com/settings/api and create an application
- Set the Authorization Callback Domain to
localhost(just the domain, with no protocol, port, or path)
The CLI uses http://localhost:{port}/callback as the redirect URI. Strava only matches on the domain portion, so the callback domain setting must be exactly localhost.
Quick Start
# 1. Log in to your Mi / Xiaomi account (prompts for email and password)
mi-fitness-sync login
# 2. Check auth status
mi-fitness-sync auth-status
# 3. List recent workouts
mi-fitness-sync list-activities --limit 10
# 4. List activities and show which ones are already on Strava (requires strava-login)
mi-fitness-sync list-activities --limit 10 --strava
# 5. View normalized detail for one activity
mi-fitness-sync activity-detail sid:key:1717200000 --json
# 6. Export a workout
mi-fitness-sync export-activity sid:key:1717200000 --format gpx --output run.gpx
# 7. Bulk export matching workouts
mi-fitness-sync export-activities --format gpx --since 2024-01-01 --output-dir backups
# 8. Authenticate with Strava (prompts for client ID and secret)
mi-fitness-sync strava-login
# 9. Upload a workout to Strava
mi-fitness-sync upload-to-strava sid:key:1717200000
All credentials are entered via CLI arguments or interactive prompts. There are no environment variables.
Commands
Commands that access Mi Fitness accept --state-path to override the default auth state file location. Commands that access Strava accept --strava-token-path to override the default Strava token file location.
The --verbose debug output includes request URLs that carry session tokens, so do not share it unredacted.
login
Logs into Xiaomi Passport for the Mi Fitness service and saves the auth state locally. Email and password can be passed as arguments or entered interactively when omitted. The password prompt does not echo input.
If Xiaomi requires extra verification, the CLI supports the interactive flows it can complete locally:
- Captcha challenges download an image to the local captcha directory and try to open it with the OS default image viewer
- Step-2 verification prompts for the email/SMS code in the terminal
- Identity verification (
notificationUrl) sends a code to the account email and prompts for it in the terminal
Xiaomi can ask for a second challenge after you answer the first one, for example, identity verification after a captcha. The CLI handles each one in turn, up to 5.
At the identity verification prompt, type resend to get a new email code or cancel to stop. An empty or rejected code prompts you again. If Xiaomi cannot send the email, the error shows the verification URL so you can see which check Xiaomi asks for. Approving the sign-in in a browser does not log the CLI in, so run login again afterwards.
Examples:
mi-fitness-sync login
mi-fitness-sync login --email you@example.com --password your-password
Flags:
| Flag | Description |
|---|---|
--email |
Mi / Xiaomi account email (prompted if omitted) |
--password |
Mi / Xiaomi account password (prompted securely if omitted) |
--state-path |
Override the persisted auth state file path |
--verbose |
Enable debug logging |
logout
Deletes the saved local Mi Fitness auth state.
mi-fitness-sync logout
Flags:
| Flag | Description |
|---|---|
--state-path |
Override the persisted auth state file path |
auth-status
Shows the currently saved Mi Fitness auth state.
mi-fitness-sync auth-status
mi-fitness-sync auth-status --json
Flags:
| Flag | Description |
|---|---|
--json |
Print the full auth state as JSON |
--state-path |
Override the persisted auth state file path |
list-activities
Lists workout activities from the Mi Fitness cloud.
mi-fitness-sync list-activities --limit 10
mi-fitness-sync list-activities --since 2024-01-01 --json
mi-fitness-sync list-activities --since 2026-03-20 --strava
mi-fitness-sync list-activities --since 1717200000 --until 1719800000 --limit 50
Flags:
| Flag | Description |
|---|---|
--since |
Inclusive start time (unix seconds or ISO-8601) |
--until |
Inclusive end time (unix seconds or ISO-8601) |
--limit |
Maximum activities to return (default: 20) |
--category |
Mi Fitness category filter string |
--country-code |
Two-letter country override (e.g. ID, GB, US); mapped to the Mi Fitness region automatically |
--strava |
Show whether each activity is already uploaded to Strava |
--strava-token-path |
Override the Strava token file path (used with --strava) |
--json |
Print activities as JSON |
--verbose |
Enable debug logging |
--state-path |
Override the persisted auth state file path |
When --country-code is omitted, the CLI uses automatic Mi Fitness region detection.
activity-detail
Fetches the normalized detail payload for one activity.
mi-fitness-sync activity-detail sid:key:1717200000
mi-fitness-sync activity-detail sid:key:1717200000 --country-code ID --json
Flags:
| Flag | Description |
|---|---|
activity_id |
Activity ID from list-activities (positional, required) |
--country-code |
Two-letter country override |
--json |
Print normalized detail as JSON |
--no-cache |
Disable the local FDS binary cache |
--cache-dir |
Override the local FDS cache directory |
--verbose |
Enable debug logging |
--state-path |
Override the persisted auth state file path |
Detail lookup behavior:
- Prefers the richer workout JSON payload when Mi Fitness exposes it
- Checks the Mi Fitness cloud for downloadable binary workout data (FDS files containing GPS tracks, heart rate, etc.)
- Can synthesize detail from FDS sport samples or GPS track points when the JSON payload is missing
- Attaches recoverable FDS sport-report and recovery-rate data (not consumed by exporters)
- Fails if neither the JSON detail nor FDS binary data is available
export-activity
Exports one activity to GPX, TCX, or FIT.
mi-fitness-sync export-activity sid:key:1717200000 --format gpx --output run.gpx
mi-fitness-sync export-activity sid:key:1717200000 --format tcx --output run.tcx.gz --gzip
mi-fitness-sync export-activity sid:key:1717200000 --format gpx --smooth-mode full --outlier-speed 7:30
mi-fitness-sync export-activity sid:key:1717200000 --format fit
Flags:
| Flag | Description |
|---|---|
activity_id |
Activity ID from list-activities (positional, required) |
--format |
Export format: gpx, tcx, or fit (required) |
--output |
Destination file path (default: ~/.mi_fitness_sync/exports/<sanitized_title>_<local_start_time>.<format>) |
--gzip |
Gzip-compress the output |
--country-code |
Two-letter country override |
--no-cache |
Disable the local FDS binary cache |
--cache-dir |
Override the local FDS cache directory |
--no-smooth |
Disable GPS smoothing entirely |
--outlier-speed |
Max plausible speed for outlier detection, as km/h (for example 180 or 180kmh) or pace (for example 7:30 or 7:30/km) |
--smooth-mode |
Smoothing strategy: match (default, converge toward the Mi Fitness summary distance) or full (apply the strongest smoothing pass) |
--verbose |
Enable debug logging |
--state-path |
Override the persisted auth state file path |
Export behavior:
- GPX requires GPS track points in the detail payload
- TCX and FIT prefer track points but fall back to timestamped sport samples without coordinates
- GPS smoothing is enabled by default for exports that include GPS coordinates; it only adjusts latitude/longitude and leaves timestamps, heart rate, cadence, and other fields unchanged
matchmode tries to bring the smoothed GPS distance closer to the Mi Fitness summary distance, whilefullapplies the largest valid smoothing window after outlier cleanup- FIT generation is best-effort, so only fields present in the Mi Fitness source are included
- Pool swim FIT exports write one
lengthmessage per pool length, with rest as idle lengths, and onelapper swim set plus one per rest period before, between, or after sets
export-activities
Exports many activities to GPX, TCX, or FIT using the same filters as list-activities.
mi-fitness-sync export-activities --format gpx --since 2024-01-01 --output-dir backups
mi-fitness-sync export-activities --format fit --category outdoor_run --workers 2
mi-fitness-sync export-activities --format tcx --limit 100 --gzip --resume-file backups/export_manifest.jsonl
Flags:
| Flag | Description |
|---|---|
--since |
Inclusive start time (unix seconds or ISO-8601) |
--until |
Inclusive end time (unix seconds or ISO-8601) |
--limit |
Maximum activities to export (default: all matching activities) |
--category |
Mi Fitness category filter string |
--format |
Export format: gpx, tcx, or fit (required) |
--output-dir |
Destination directory (default: ~/.mi_fitness_sync/exports/bulk) |
--resume-file |
Resume/manifest JSONL path (default: <output-dir>/bulk_export_<format>.jsonl) |
--workers |
Concurrent export workers (default: 2) |
--overwrite |
Re-export files even when the output path already exists |
--gzip |
Gzip-compress every exported file |
--country-code |
Two-letter country override |
--no-cache |
Disable the local FDS binary cache |
--cache-dir |
Override the local FDS cache directory |
--no-smooth |
Disable GPS smoothing entirely |
--outlier-speed |
Max plausible speed for outlier detection, as km/h or pace |
--smooth-mode |
Smoothing strategy: match (default) or full |
--verbose |
Enable debug logging |
--state-path |
Override the persisted auth state file path |
Bulk export behavior:
- Streams activities page-by-page instead of building one large in-memory list
- Reuses the listed activity objects directly, so it avoids the extra ID lookup step used by single-activity export
- Writes output files atomically and records progress in an append-only JSONL manifest so reruns can resume large jobs
- Skips existing output files by default; use
--overwriteto regenerate them - Uses conservative bounded concurrency plus automatic retry/backoff for transient Mi Fitness and FDS HTTP failures
- Default filenames include the activity ID suffix to keep large batches collision-free
strava-login
Authenticates with Strava using the OAuth2 authorization code flow. Opens a browser for authorization, then stores the tokens locally. Client ID and secret can be passed as arguments or entered interactively.
mi-fitness-sync strava-login
mi-fitness-sync strava-login --client-id YOUR_ID --client-secret YOUR_SECRET
Flags:
| Flag | Description |
|---|---|
--client-id |
Strava API client ID (prompted if omitted) |
--client-secret |
Strava API client secret (prompted if omitted) |
--port |
Local port for the OAuth callback server (default: 5478) |
--strava-token-path |
Override the Strava token file path |
The flow:
- Starts a temporary local HTTP server on
localhost:{port} - Opens the Strava authorization page in your browser
- After authorization, Strava redirects to the local server with an auth code
- Exchanges the code for access and refresh tokens
- Saves tokens to
~/.mi_fitness_sync/strava/tokens.json
When the saved access token has expired or is about to expire, the CLI refreshes it with the stored refresh token before filling the --strava column or uploading an activity.
strava-status
Shows the currently saved Strava auth state.
mi-fitness-sync strava-status
Flags:
| Flag | Description |
|---|---|
--strava-token-path |
Override the Strava token file path |
strava-logout
Revokes the Strava access token via the Strava API and deletes the local token file. Exits cleanly if no tokens exist. Deletes local tokens even if remote revocation fails.
mi-fitness-sync strava-logout
Flags:
| Flag | Description |
|---|---|
--strava-token-path |
Override the Strava token file path |
upload-to-strava
Uploads one Mi Fitness activity to Strava as a FIT file. The FIT file is also saved locally.
mi-fitness-sync upload-to-strava sid:key:1717200000
mi-fitness-sync upload-to-strava sid:key:1717200000 --output run.fit
mi-fitness-sync upload-to-strava sid:key:1717200000 --smooth-mode full --outlier-speed 180kmh
mi-fitness-sync upload-to-strava sid:key:1717200000 --skip-duplicate-check
Flags:
| Flag | Description |
|---|---|
activity_id |
Activity ID from list-activities (positional, required) |
--output |
Local FIT file save path (default: ~/.mi_fitness_sync/exports/<sanitized_title>_<local_start_time>.fit) |
--country-code |
Two-letter country override |
--skip-duplicate-check |
Skip checking Strava for existing activities with a similar start time |
--strava-token-path |
Override the Strava token file path |
--no-cache |
Disable the local FDS binary cache |
--cache-dir |
Override the local FDS cache directory |
--no-smooth |
Disable GPS smoothing entirely before generating the FIT upload |
--outlier-speed |
Max plausible speed for outlier detection, as km/h or pace |
--smooth-mode |
Smoothing strategy: match (default) or full |
--verbose |
Enable debug logging |
--state-path |
Override the persisted Mi Fitness auth state file path |
Upload behavior:
- Fetches the activity detail from Mi Fitness
- Renders to FIT format with the same optional smoothing controls as
export-activity, then saves the file locally - Checks Strava for existing activities within 5 minutes either side of the start time (unless
--skip-duplicate-checkis set) - If potential duplicates are found, prompts for confirmation before uploading
- Uploads the FIT file to Strava and polls until Strava finishes processing it, giving up after about a minute
- Prints the Strava activity URL on success
- The sport type is mapped from Mi Fitness to the closest Strava equivalent; unmapped types let Strava auto-detect
Project Layout
src/mi_fitness_sync/
activity/ Activity listing, detail, region routing, normalization
auth/ Xiaomi Passport auth and persistence
cli/ Command-line entry point
export/ GPX, TCX, and FIT rendering
fds/ Mi Fitness FDS binary parsing and caching
strava/ Strava OAuth2 auth and upload
tests/ Per-module test files mirroring the package structure, plus the release tooling test
Development
The project is managed with uv and checked with ruff and mypy in strict mode.
# Create the environment and install the development dependencies
uv sync --all-groups
# Run the test suite with coverage
uv run pytest --cov --cov-report=term-missing
# Format and lint
uv run ruff format
uv run ruff check
# Type check the package
uv run mypy
CI runs formatting, lint, and type checks on pushes to main and on every pull request, together with a build whose packaging metadata is validated. The test suite runs on Ubuntu and Windows for Python 3.12 and 3.13.
Changelog
Release notes live in CHANGELOG.md, and every published version has a GitHub release.
Local Auth Storage
By default, Mi Fitness auth state is stored in the user profile under ~/.mi_fitness_sync/auth/auth.json.
You can override that location with --state-path.
Strava tokens are stored under ~/.mi_fitness_sync/strava/tokens.json. You can override that location with --strava-token-path.
When Xiaomi requires a captcha, the image is saved under ~/.mi_fitness_sync/captcha/ and the CLI tries to open it with your OS default image app. The file is deleted on a best-effort basis after you respond; if deletion fails, the CLI prints the saved path so you can remove it manually.
Both files contain sensitive credentials and should not be shared or committed to version control.
Limitations
- This is an unofficial project and is not affiliated with Xiaomi, Mi Fitness, or Strava.
- Parts of the Xiaomi login flow had to be pieced together from app behavior and decompiled code.
- Xiaomi may change endpoints, cookies, signatures, or response formats at any time.
- Some accounts may require captcha or app approval flows that are not fully automated here. Step-2 verification (SMS/email code) and identity verification by email code are supported interactively.
- Detail retrieval currently depends on the raw
huami_sport_recordpayload shape used by the Android app; Xiaomi may change that format without notice. - FDS download-url metadata does not guarantee the corresponding cloud object is still downloadable, so some workouts still cannot be enriched from FDS.
- GPX export is unavailable for workouts where Mi Fitness does not expose GPS track points.
- TCX and FIT require timestamped export points. The exporter uses GPS track points directly when they are present in the normalized detail and otherwise falls back to timestamped sport samples; if neither source exists, those exports are unavailable.
- FIT export is best-effort and may omit fields when Mi Fitness does not provide enough source data for a fuller activity file.
Security Notes
- The CLI accepts Mi account and Strava client credentials either on the command line or via interactive prompts.
- Command-line arguments may be persisted in shell history or process listings depending on your environment, so interactive prompts are safer on shared machines.
- The persisted Mi Fitness auth state and Strava token files contain sensitive session data and should be protected.
If you use this on a shared machine, treat the local auth state like a credential.
Sponsor
If mi-fitness-sync saves you time, you can support its development on Ko-fi.
License
MIT. See LICENSE.
Metadata
Release files for mi-fitness-sync 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mi_fitness_sync-0.1.0.tar.gz | 197.0 kB | With provenance | Details for mi_fitness_sync-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mi_fitness_sync-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for mi_fitness_sync-0.1.0-py3-none-any.whl |
Total release size: 287.7 kB
Release files / mi_fitness_sync-0.1.0.tar.gz
| Download URL | mi_fitness_sync-0.1.0.tar.gz |
|---|---|
| Size | 197.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9bc1c071a4bca18a5d7e14d556bfa100c5272f7a6ccaf8087868b27e76816937
|
|
BLAKE2b-256 checksum How to use checksums |
8e1a7d80c1b8ea9f821a347fffcae249a66ba23fe3c3f6316992585b3b26cf34
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logRelease files / mi_fitness_sync-0.1.0-py3-none-any.whl
| Download URL | mi_fitness_sync-0.1.0-py3-none-any.whl |
|---|---|
| Size | 90.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f09b7c8695aef38abfb95baa344047eff67ba179c501fd980bb88836c5e93226
|
|
BLAKE2b-256 checksum How to use checksums |
72f7f53fe75beb038405c21145bc982e2194648bfb6963ba4da2c4b11c28cf4c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logSecurity for mi-fitness-sync 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for mi_fitness_sync-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.