Hevy CLI

CLI for the Hevy workout tracking API. Query workouts, routines, exercises, and track progress.

Setup

Requires Hevy Pro subscription for API access.

1. Get API key from https://hevy.com/settings?developer
2. Set environment variable: export HEVY_API_KEY="your-key"

Commands

Status

bash
# Check configuration and connection
hevy status

Workouts

bash
# List recent workouts (default 5)
hevy workouts
hevy workouts --limit 10

# Fetch all workouts
hevy workouts --all

# Show detailed workout
hevy workout <workout-id>

# JSON output
hevy workouts --json
hevy workout <id> --json

# Show weights in kg (default is lbs)
hevy workouts --kg

Routines

bash
# List all routines
hevy routines

# Show detailed routine
hevy routine <routine-id>

# JSON output
hevy routines --json

Exercises

bash
# List all exercise templates
hevy exercises

# Search by name
hevy exercises --search "bench press"

# Filter by muscle group
hevy exercises --muscle chest

# Show only custom exercises
hevy exercises --custom

# JSON output
hevy exercises --json

Exercise History

bash
# Show history for specific exercise
hevy history <exercise-template-id>
hevy history <exercise-template-id> --limit 50

# JSON output
hevy history <exercise-template-id> --json

Creating Routines

bash
# Create routine from JSON (stdin)
echo '{"routine": {...}}' | hevy create-routine

# Create routine from file
hevy create-routine --file routine.json

# Create a routine folder
hevy create-folder "Push Pull Legs"

# Update existing routine
echo '{"routine": {...}}' | hevy update-routine <routine-id>

# Create custom exercise (checks for duplicates first!)
hevy create-exercise --title "My Exercise" --muscle chest --type weight_reps

# Force create even if duplicate exists
hevy create-exercise --title "My Exercise" --muscle chest --force

⚠️ Duplicate Prevention: create-exercise checks if an exercise with the same name already exists and will error if found. Use --force to create anyway (not recommended).

Routine JSON format:

json
{
  "routine": {
    "title": "Push Day 💪",
    "folder_id": null,
    "notes": "Chest, shoulders, triceps",
    "exercises": [
      {
        "exercise_template_id": "79D0BB3A",
        "notes": "Focus on form",
        "rest_seconds": 90,
        "sets": [
          { "type": "warmup", "weight_kg": 20, "reps": 15 },
          { "type": "normal", "weight_kg": 60, "reps": 8 }
        ]
      }
    ]
  }
}

Other

bash
# Total workout count
hevy count

# List routine folders
hevy folders

Usage Examples

User asks "What did I do at the gym?"

bash
hevy workouts

User asks "Show me my last chest workout"

bash
hevy workouts --limit 10  # Find relevant workout ID
hevy workout <id>         # Get details

User asks "How am I progressing on bench press?"

bash
hevy exercises --search "bench press"  # Get exercise template ID
hevy history <exercise-id>              # View progression

User asks "What routines do I have?"

bash
hevy routines
hevy routine <id>  # For details

User asks "Find leg exercises"

bash
hevy exercises --muscle quadriceps
hevy exercises --muscle hamstrings
hevy exercises --muscle glutes

User asks "Create a push day routine"

bash
# 1. Find exercise IDs
hevy exercises --search "bench press"
hevy exercises --search "shoulder press"
# 2. Create routine JSON with those IDs and pipe to create-routine

Notes

• Duplicate Prevention: create-exercise checks for existing exercises with the same name before creating. Use --force to override (not recommended).
• API Limitations: Hevy API does NOT support deleting or editing exercise templates - only creating. Delete exercises manually in the app.
• API Rate Limits: Be mindful when fetching all data (--all flag)
• Weights: Defaults to lbs, use --kg for kilograms
• Pagination: Most commands auto-paginate, but limit flags help reduce API calls
• IDs: Workout/routine/exercise IDs are UUIDs, shown in detailed views

API Reference

Full API docs: https://api.hevyapp.com/docs/

Available Endpoints

• GET /v1/workouts - List workouts (paginated)
• GET /v1/workouts/{id} - Get single workout
• GET /v1/workouts/count - Total workout count
• GET /v1/routines - List routines
• GET /v1/routines/{id} - Get single routine
• GET /v1/exercise_templates - List exercises
• GET /v1/exercise_templates/{id} - Get single exercise
• GET /v1/exercise_history/{id} - Exercise history
• GET /v1/routine_folders - List folders

Write Operations (supported but use carefully)

• POST /v1/workouts - Create workout
• PUT /v1/workouts/{id} - Update workout
• POST /v1/routines - Create routine
• PUT /v1/routines/{id} - Update routine
• POST /v1/exercise_templates - Create custom exercise
• POST /v1/routine_folders - Create folder

The CLI focuses on read operations. Write operations are available via the API client for programmatic use.