mirror of
https://github.com/sstent/FitTrack_GarminSync.git
synced 2026-01-25 16:41:41 +00:00
sstent
28ab4f3416
- Created implementation plan with technical context - Developed data models for User Session, Sync Job, and Authentication Token - Defined API contracts for authentication, sync triggering, and status checking - Created quickstart guide for CLI usage - Updated agent context with new technology stack - Verified constitution compliance for all design decisions
171 lines
3.7 KiB
Markdown
171 lines
3.7 KiB
Markdown
# 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](https://www.python.org/downloads/)
|
|
* **Git**: For cloning the repository (if installing from source).
|
|
|
|
## Installation
|
|
|
|
### Option 1: Install from Package (Recommended)
|
|
|
|
```bash
|
|
pip install garmin-sync-cli
|
|
```
|
|
|
|
### Option 2: Install from Source
|
|
|
|
1. Clone the repository:
|
|
```bash
|
|
git clone <repository-url>
|
|
cd <repository-name>
|
|
```
|
|
|
|
2. Navigate to the CLI directory:
|
|
```bash
|
|
cd cli
|
|
```
|
|
|
|
3. Install the CLI application in a virtual environment:
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
garmin-sync auth --username your_email@example.com --password your_password
|
|
```
|
|
|
|
To authenticate with your account (with MFA):
|
|
|
|
```bash
|
|
garmin-sync auth --username your_email@example.com --password your_password --mfa-code 123456
|
|
```
|
|
|
|
For interactive authentication (recommended for MFA):
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
garmin-sync sync trigger --type activities --force-full
|
|
```
|
|
|
|
### 3. Check Sync Status
|
|
|
|
Check the status of all recent sync jobs:
|
|
|
|
```bash
|
|
garmin-sync sync status
|
|
```
|
|
|
|
Check the status of a specific sync job:
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```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:
|
|
|
|
```bash
|
|
garmin-sync sync status --format json
|
|
```
|
|
|
|
## Help
|
|
|
|
Get help with any command:
|
|
|
|
```bash
|
|
garmin-sync --help
|
|
garmin-sync auth --help
|
|
garmin-sync sync --help
|
|
```
|
|
|
|
## Examples
|
|
|
|
### Authenticate and Sync Activities
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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 |