Hevy

Hevy Routine Creator

Quick Start

<skill-dir>/bin/hevy auth <key>           # Authenticate (get key from hevy.com/settings)
<skill-dir>/bin/hevy exercises search "squat"
<skill-dir>/bin/hevy routines template > routine.json
# Edit routine.json
<skill-dir>/bin/hevy routines create routine.json

For all commands: <skill-dir>/bin/hevy --help

Workflow

1. Parse workout plan - extract exercises, sets, reps, weights, rest times
2. Look up exercise IDs - hevy exercises search <name>
3. Build routine JSON - start with hevy routines template
4. Create routine - hevy routines create file.json

Critical Rules

• NEVER use @ in notes (causes silent 400 errors)
• ALWAYS wrap: {"routine": {...}} not bare object
• ALWAYS match set properties to exercise type:
  • weight_reps → weight_kg, reps
  • reps_only → reps only (NO weight!)
  • duration → duration_seconds
  • distance_duration → distance_meters, duration_seconds
  • short_distance_weight → distance_meters, weight_kg (Farmers Walk, Sled Push/Pull)
• NEVER guess IDs - always hevy exercises search

Exercise Type Decision

When unsure: hevy exercises get <id> shows the exercise type.

Interpreting Workout Plans

Supersets:

• "A1/A2", "superset", "paired" → same superset_id (integers: 0, 1, 2...)
• "Circuit" or "EMOM" → all exercises share one superset_id
• Separate exercises → superset_id: null

Rest: Goes on LAST exercise of superset only

AMRAP/Max effort: Use "reps": null

Example superset structure:

{
  "exercise_template_id": "79D0BB3A",
  "superset_id": 0,
  "rest_seconds": null,
  "sets": [{"type": "normal", "weight_kg": 80, "reps": 10}]
},
{
  "exercise_template_id": "1B2B1E7C",
  "superset_id": 0,
  "rest_seconds": 90,
  "sets": [{"type": "normal", "reps": 8}]
}

Common Exercise IDs

Use hevy exercises search for current IDs. These are reference examples:

Before Creating Custom Exercises

1. Search partial names ("row" not "cable row")
2. Check equipment variants (Barbell, Dumbbell, Cable, Machine)
3. Try alternate names ("Skull Crushers" = "Lying Tricep Extension")

Unit Conversion

User provides lbs → convert to kg: weight_kg = lbs / 2.205

Round to nearest 0.5 kg for practical loading.

Handling Search Results

Bulk Import Strategy

For programs with 10+ routines:

1. Build all JSON files first
2. Create one routine, verify it appears correctly in app
3. Create remaining with 2-second delays between calls
4. If 429 error: wait 60s, resume from failed routine

Troubleshooting

CLI vs This File