FitTrack_GarminSync/specs/006-cli-auth-sync-mfa/quickstart.md

Quickstart Guide: CLI App for API Interaction with MFA

Overview

This guide provides essential steps for setting up and using the GarminSync CLI application to authenticate with MFA support, trigger sync operations, and check sync status.

Prerequisites

Before you begin, ensure you have the following installed:

• Python 3.13+: The CLI application is built with Python 3.13 as required by project standards.
  • Install Python
• Git: For cloning the repository (if installing from source).

Installation

Option 1: Install from Package (Recommended)

pip install garmin-sync-cli

Option 2: Install from Source

1. Clone the repository:

   git clone <repository-url>
   cd <repository-name>
   

2. Navigate to the CLI directory:

   cd cli
   

3. Install the CLI application in a virtual environment:

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   pip install -r requirements.txt
   pip install -e .
   

Basic Usage

1. Authentication

To authenticate with your account (without MFA):

garmin-sync auth --username your_email@example.com --password your_password

To authenticate with your account (with MFA):

garmin-sync auth --username your_email@example.com --password your_password --mfa-code 123456

For interactive authentication (recommended for MFA):

garmin-sync auth --interactive

This will prompt you for your credentials and MFA code if required.

2. Trigger a Sync

After authenticating, trigger a sync operation:

garmin-sync sync trigger --type activities --start-date 2024-01-01 --end-date 2024-01-31

Available sync types: activities, health, workouts

For a full sync (not incremental):

garmin-sync sync trigger --type activities --force-full

3. Check Sync Status

Check the status of all recent sync jobs:

garmin-sync sync status

Check the status of a specific sync job:

garmin-sync sync status --job-id abc123def456

Configuration

The CLI application stores authentication tokens and configuration in your home directory:

• ~/.garmin-sync/config.yaml: Configuration settings
• ~/.garmin-sync/tokens.json: Encrypted authentication tokens

Custom Configuration

You can create a custom configuration file at ~/.garmin-sync/config.yaml:

api_base_url: https://api.yourdomain.com
default_timeout: 30
output_format: table  # Options: table, json, csv
remember_login: true

Output Formats

The CLI supports multiple output formats:

• Table (default): Human-readable tabular format
• JSON: Structured JSON output for scripting
• CSV: Comma-separated values for data analysis

Specify output format with the --format option:

garmin-sync sync status --format json

Help

Get help with any command:

garmin-sync --help
garmin-sync auth --help
garmin-sync sync --help

Examples

Authenticate and Sync Activities

# Authenticate interactively
garmin-sync auth --interactive

# Trigger a sync for recent activities
garmin-sync sync trigger --type activities --start-date $(date -d "7 days ago" +%Y-%m-%d)

# Check the status of the sync
garmin-sync sync status

Check All Sync Jobs in JSON Format

garmin-sync sync status --format json

Troubleshooting

Authentication Issues

• Ensure your credentials are correct
• If using MFA, make sure your code is current
• Clear stored tokens if needed: garmin-sync auth logout

Sync Issues

• Check your internet connection
• Verify API endpoint accessibility
• Check if your account has proper permissions