Skip to main content
The Synheart CLI is a powerful development tool that lets you test wearable integrations locally, manage OAuth tokens, and pull data from cloud APIs without building a full mobile app.

​
Prerequisites

Before installing the CLI, ensure you have:
  • Python 3.11+ installed
  • pip package manager
  • ngrok account (free) for local webhook testing
  • OAuth credentials for cloud wearables (WHOOP, Garmin, Fitbit, etc.)

​
Installation

Install the Synheart Wear CLI using pip: 
pip install synheart-wear-cli
Verify the installation: 
wear --version

​
Configuration

​
Environment Variables

Create a .env.local file in your project directory: 
# WHOOP OAuth credentials
WHOOP_CLIENT_ID=your_client_id
WHOOP_CLIENT_SECRET=your_client_secret

# Garmin OAuth credentials
GARMIN_CONSUMER_KEY=your_consumer_key
GARMIN_CONSUMER_SECRET=your_consumer_secret

# Fitbit OAuth credentials
FITBIT_CLIENT_ID=your_client_id
FITBIT_CLIENT_SECRET=your_client_secret

# Optional: Custom data directory
SYNHEART_DATA_DIR=~/.synheart/data
Never commit .env.local to version control. Add it to your .gitignore file.

​
ngrok Setup

For local webhook testing, configure ngrok:
  1. Sign up for a free account at ngrok.com
  2. Get your authtoken from the dashboard
  3. Configure ngrok:
ngrok config add-authtoken YOUR_NGROK_TOKEN
  1. Verify configuration:
ngrok config check

​
Basic Usage

​
Start Local Development Server

Start a local development server with automatic browser opening: 
wear start dev --vendor whoop --open-browser
This will:
  • Start a local HTTP server on http://localhost:8080
  • Open your browser to complete OAuth flow
  • Store tokens securely in ~/.synheart/tokens/
  • Stream data in real-time to your terminal

​
Pull Data Once

Pull historical data from a cloud API: 
# Pull last 7 days of data
wear pull once --vendor whoop --since 7d

# Pull specific date range
wear pull once --vendor whoop --since 2024-01-01 --until 2024-01-31

# Pull and save to file
wear pull once --vendor whoop --since 7d --output data.json

​
Stream Real-Time Data

Stream real-time data from a wearable: 
# Stream with default settings
wear stream --vendor whoop

# Stream specific metrics
wear stream --vendor whoop --metrics hr,hrv,steps

# Stream to file
wear stream --vendor whoop --output stream.jsonl

​
Common Commands

​
OAuth Token Management

# List all stored tokens
wear tokens list

# List tokens for specific vendor
wear tokens list --vendor whoop

# Revoke a token
wear tokens revoke --vendor whoop

# Refresh expired tokens
wear tokens refresh --vendor whoop

​
Data Management

# View local data cache
wear data list

# Clear local cache
wear data clear

# Export data to CSV
wear data export --output export.csv --format csv

# View data statistics
wear data stats

​
Device Management

# List connected devices
wear devices list --vendor whoop

# Get device information
wear devices info --vendor whoop --device-id DEVICE_ID

# Test device connection
wear devices test --vendor whoop

​
Advanced Usage

​
Custom Webhook Endpoints

Set up webhooks for real-time data delivery: 
# Start ngrok tunnel
ngrok http 8080

# In another terminal, start webhook server
wear webhook start --port 8080 --endpoint /webhook

# Configure webhook URL in vendor dashboard
wear webhook configure --vendor whoop --url https://your-ngrok-url.ngrok.io/webhook

​
Batch Processing

Process multiple vendors or date ranges: 
# Pull from multiple vendors
wear pull batch --vendors whoop,garmin --since 7d

# Process with custom script
wear pull once --vendor whoop --since 7d | python process_data.py

​
Debugging

Enable verbose logging for troubleshooting: 
# Enable debug mode
wear --debug stream --vendor whoop

# Save logs to file
wear --debug stream --vendor whoop --log-file debug.log

# Check configuration
wear config check

​
Platform-Specific Examples

​
WHOOP Integration

# 1. Get OAuth credentials from WHOOP developer portal
# 2. Add to .env.local:
#    WHOOP_CLIENT_ID=your_id
#    WHOOP_CLIENT_SECRET=your_secret

# 3. Start OAuth flow
wear start dev --vendor whoop --open-browser

# 4. Pull data
wear pull once --vendor whoop --since 7d

# 5. Stream real-time
wear stream --vendor whoop --metrics hr,hrv,recovery

​
Garmin Integration

# 1. Get OAuth credentials from Garmin Developer Portal
# 2. Add to .env.local:
#    GARMIN_CONSUMER_KEY=your_key
#    GARMIN_CONSUMER_SECRET=your_secret

# 3. Start OAuth flow
wear start dev --vendor garmin --open-browser

# 4. Pull activity data
wear pull once --vendor garmin --since 7d --type activities

​
Fitbit Integration

# 1. Register app at dev.fitbit.com
# 2. Add to .env.local:
#    FITBIT_CLIENT_ID=your_id
#    FITBIT_CLIENT_SECRET=your_secret

# 3. Start OAuth flow
wear start dev --vendor fitbit --open-browser

# 4. Pull heart rate data
wear pull once --vendor fitbit --since 7d --metrics heartrate

​
Output Formats

The CLI supports multiple output formats:

​
JSON

wear pull once --vendor whoop --since 7d --format json

​
JSONL (JSON Lines)

wear stream --vendor whoop --format jsonl --output stream.jsonl

​
CSV

wear pull once --vendor whoop --since 7d --format csv --output data.csv

​
NDJSON (Newline Delimited JSON)

wear pull once --vendor whoop --since 7d --format ndjson

​
Troubleshooting

​
Common Issues

  • Verify your credentials in .env.local
  • Check that redirect URI matches vendor settings
  • Ensure ngrok tunnel is active (for localhost)
  • Clear browser cookies and try again
# Refresh tokens
wear tokens refresh --vendor whoop
  • Check date range (some vendors limit historical data)
  • Verify device is syncing data
  • Check vendor API status
  • Enable debug mode: wear --debug pull once --vendor whoop
  • Check internet connection
  • Verify vendor API is accessible
  • Check firewall settings
  • Try with --timeout 60 flag

​
Next Steps

CLI Reference

Complete CLI command reference

OAuth Setup

Detailed OAuth configuration guide

Webhook Testing

Set up webhooks for real-time data

Integration Examples

See CLI integration examples
Author: Israel Goytom