← Back to CLI Utilities
CLI Utilities by @nsampre

hevycli

Access and analyze Hevy fitness tracking data including workouts, routines

0
Source Code

Hevy CLI Skill

Description

Access and analyze Hevy fitness tracking data including workouts, routines, and exercise templates via the command line.

When to Use

Use this skill when the user asks to:

  • View their workout history or recent workouts
  • Get details about a specific workout
  • Check their total workout count
  • List or view their workout routines
  • Browse exercise templates
  • Export workout data as JSON
  • Analyze their fitness progress over time

Prerequisites

  • User must have hevycli installed (go install github.com/nsampre/hevycli@latest)
  • User must have configured their Hevy API key (hevycli config set-api-key <key>)
  • User must have a Hevy Pro subscription

Available Commands

Configuration

# Set API key
hevycli config set-api-key <api-key-uuid>

# View current config
hevycli config show

Workouts

# List recent workouts
hevycli workouts list [--page N] [--page-size N] [--format json|table]

# Get detailed workout information (accepts full UUID or 8-char short ID)
hevycli workouts get <workout-id>

# Get total workout count
hevycli workouts count

Routines

# List routines
hevycli routines list [--page N] [--page-size N] [--format json|table]

# Get routine details (accepts full UUID or 8-char short ID)
hevycli routines get <routine-id>

Exercises

# List exercise templates
hevycli exercises list [--page N] [--page-size N] [--format json|table]

# Get exercise template details
hevycli exercises get <template-id>

Global Flags

  • --format - Output format: table (default) or json
  • --debug - Enable debug output for API requests

Usage Examples

Example 1: View Recent Workout History

hevycli workouts list --page-size 5

Example 2: Get Detailed Workout with Sets and Reps

# Using short ID (first 8 characters)
hevycli workouts get f75e9c13

# Or using full UUID
hevycli workouts get f75e9c13-32d7-407d-9715-011f5d5698fa

Example 3: Export Data for Analysis

# Export all workouts as JSON
hevycli workouts list --format json > workouts.json

# Export routines
hevycli routines list --format json > routines.json

Example 4: Check Progress

# View total workouts completed
hevycli workouts count

# List exercise templates to find specific exercise IDs
hevycli exercises list

Tips for Claude

  1. Use JSON format for analysis: When helping users analyze their data, use --format json to get structured data that can be parsed and analyzed.

  2. Short IDs are supported: Users can copy short IDs from workouts list output and use them directly in workouts get commands.

  3. Pagination: API max page size is 10. Use pagination (--page N) to access older workouts.

  4. Error handling: If a command fails:

    • Check if API key is configured (hevycli config show)
    • Verify the user has Hevy Pro subscription
    • Check if the ID exists or is valid

  5. Data insights: After retrieving workout data, you can:

    • Calculate training volume (weight × reps × sets)
    • Track progression over time
    • Identify patterns in workout frequency
    • Suggest rest day intervals

Example Interaction

User: "Show me my last 3 workouts"

Claude:

hevycli workouts list --page-size 3

User: "Get details on the first workout"

Claude:

# Using the short ID from the list output
hevycli workouts get f75e9c13

User: "How many total workouts have I completed?"

Claude:

hevycli workouts count

Notes

  • The tool reads data only - it does not create or modify workouts
  • All timestamps are in ISO 8601 format
  • Weights are always displayed in kilograms
  • Distances are in meters, durations in seconds
  • Table output handles emoji in workout titles (may have minor alignment issues depending on terminal)