# 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