Hevy CLI

Use the hevy CLI to interact with Hevy fitness app data. Requires HEVY_API_KEY env var to be set.

Quick Start

# Verify access
hevy workouts count

# List recent workouts
hevy workouts list --page-size 10

# Raw JSON output for any command
hevy -j workouts list

Common Tasks

View workout history

hevy workouts list --page 1 --page-size 10
hevy workouts get \x3Cworkout-id>

Check exercise progress

# Find the exercise template ID first
hevy exercises list --page-size 100

# Then get history for that exercise
hevy exercises history \x3Ctemplate-id>
hevy exercises history \x3Ctemplate-id> --start-date 2025-01-01 --end-date 2025-02-01

Create a workout

hevy workouts create \
  --title "Push Day" \
  --start-time 2025-01-15T08:00:00Z \
  --end-time 2025-01-15T09:00:00Z \
  --exercises-json '[{"exercise_template_id":"79D0BB3A","sets":[{"type":"normal","weight_kg":60,"reps":8}]}]'

For complex exercises, use a file: --exercises-json @exercises.json

Manage routines

hevy routines list
hevy routines create --title "Upper Body" --exercises-json @routine.json
hevy routines update \x3Croutine-id> --title "Updated Name"

Organize with folders

hevy folders list
hevy folders create --name "Hypertrophy Block"

Key Patterns

• All list commands accept --page and --page-size for pagination.
• Use -j flag before the subcommand for JSON output: hevy -j workouts list.
• Exercise data for create/update uses --exercises-json accepting inline JSON or @filepath.
• Set types: normal, warmup, failure, dropset.
• IDs are returned in list/get responses -- use JSON mode (-j) to get exact IDs for subsequent commands.

Full Command Reference

See references/commands.md for complete command syntax, all flag options, enum values for exercise types/equipment/muscle groups, and the exercises JSON schema.