garmin-mtp

name	garmin-mtp
description	Use when working with Garmin watches over MTP using the garmin-mtp CLI: listing watch files, pulling CIQ logs or FIT files, pushing files to Garmin import directories, diagnosing Android File Transfer or Garmin Express conflicts, handling storage/path selection, or explaining Garmin MTP directory behavior.

Garmin MTP

Use the garmin-mtp command for Garmin watch file transfer over MTP. The tool reads the MTP object tree directly; it does not mount the watch as a normal filesystem and cannot bypass Garmin secure storage rules.

First Checks

Run MTP commands serially against one watch. Do not parallelize garmin-mtp calls; libmtp needs exclusive access to the USB/MTP interface.

Prefer the installed command:

which garmin-mtp
garmin-mtp devices

If it is missing on macOS:

brew tap Likenttt/tap
brew install garmin-mtp

If opening the device fails, check for competing MTP apps:

ps -axo pid,command | rg 'Android File Transfer|Garmin Express|Garmin Core Service|MTP'

Ask the user to close Android File Transfer, Android File Transfer Agent, Garmin Express, or Garmin Express Service, then unplug and reconnect the watch before retrying.

Listing And Pulling

Start from storage and then list the target directory:

garmin-mtp list /
garmin-mtp list /GARMIN/Apps/LOGS

If list / sees storage but a Garmin path reports directory not found, retry after updating to garmin-mtp 0.1.3 or newer. That version falls back to parent-id object traversal for watches that expose storage but return an empty classic folder tree.

Garmin paths are case-sensitive on some devices. On Forerunner-class devices, app logs commonly live at /GARMIN/Apps/LOGS, not /GARMIN/APPS/LOG.

Pull CIQ logs into a local logs directory:

mkdir -p logs
garmin-mtp pull /GARMIN/Apps/LOGS/CIQ_LOG.YML logs/
garmin-mtp pull /GARMIN/Apps/LOGS/CIQ_LOG.BAK logs/

Pull app-specific logs by listing the folder first, then pulling the exact filenames:

garmin-mtp list /GARMIN/Apps/LOGS
garmin-mtp pull /GARMIN/Apps/LOGS/WristAlbum.TXT logs/
garmin-mtp pull /GARMIN/Apps/LOGS/WristAlbum.BAK logs/

For multiple storage volumes or devices:

garmin-mtp --device-index 1 list /
garmin-mtp --storage "Internal Storage" list /GARMIN

Pushing Files

Push only to directories that already exist and that Garmin expects for imports. For incoming files, prefer NewFiles when it appears in the device tree:

garmin-mtp push ./example.fit /GARMIN/NewFiles

Do not overwrite silently. Use the CLI's explicit overwrite flag only when replacement is intended:

garmin-mtp push --overwrite ./example.fit /GARMIN/NewFiles

Debugging

Use manual or menu to show the built-in directory guide:

garmin-mtp menu

Use dump when path resolution fails or Garmin returns unusual object-tree data:

garmin-mtp dump

For directory purpose and transfer-risk guidance, read references/directories.md. For implementation details of the reliable fallback, read references/parent-id-fallback.md.