hevy-cli

⚠️ Unofficial CLI for Hevy
Not affiliated with or endorsed by Hevy.

A command-line interface for Hevy workout tracking. View workouts, routines, exercises, and more from your terminal.

Requires Hevy Pro for API access.

Installation

npm install -g hevy-cli

Or run directly with npx:

npx hevy-cli --help

Setup

1. Get your API key from Hevy Developer Settings (requires Hevy Pro)
2. Set the environment variable:

export HEVY_API_KEY="your-api-key-here"

Add this to your shell profile (~/.zshrc, ~/.bashrc, etc.) to persist it.

3. Verify it works:

hevy status

Commands

Status

hevy status              # Check connection and workout count
hevy status --json       # Machine-readable output

Workouts

hevy workouts            # List 5 most recent workouts
hevy workouts -n 10      # List 10 most recent
hevy workouts --all      # List all workouts (may be slow)
hevy workouts --json     # Output as JSON
hevy workouts --kg       # Show weights in kg instead of lbs

hevy workout <id>        # Show detailed workout
hevy workout <id> --json

Routines

hevy routines            # List all routines
hevy routines --json

hevy routine <id>        # Show detailed routine
hevy routine <id> --json --kg

Exercises

hevy exercises                    # List all exercise templates
hevy exercises -s "bench"         # Search by name
hevy exercises --muscle chest     # Filter by muscle group
hevy exercises --custom           # Show only custom exercises
hevy exercises --json

hevy history <exerciseId>         # Show history for an exercise
hevy history <exerciseId> -n 50   # Limit entries
hevy history <exerciseId> --kg

Folders

hevy folders             # List routine folders
hevy folders --json

Stats

hevy count               # Show total workout count
hevy count --json

Create & Update

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

# Create routine from stdin
cat routine.json | hevy create-routine

# Update existing routine
hevy update-routine <id> -f routine.json

# Create folder
hevy create-folder "Push/Pull/Legs"

# Create custom exercise
hevy create-exercise --title "My Exercise" --muscle chest --type weight_reps

Options

Global flags available on all commands:

| Flag | Description | |------|-------------| | -h, --help | Show help | | -V, --version | Show version number | | --no-color | Disable colored output | | --json | Output as JSON (where applicable) | | --kg | Show weights in kg (default: lbs) |

Environment Variables

| Variable | Description | |----------|-------------| | HEVY_API_KEY | Required. Your Hevy API key | | NO_COLOR | Disable colored output (any value) |

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | Generic failure | | 2 | Invalid usage (bad arguments) | | 3 | Authentication failure (missing/invalid API key) |

Examples

View recent workouts

$ hevy workouts -n 3

📊 3 workouts:

📅 Mon, Jan 6, 2026 - Push Day
   ⏱️  6:30 AM - 7:45 AM (1h 15min)
   💪 5 exercises, 20 sets

📅 Sat, Jan 4, 2026 - Pull Day
   ⏱️  8:00 AM - 9:10 AM (1h 10min)
   💪 6 exercises, 24 sets

Search exercises and view history

# Find exercise ID
$ hevy exercises -s "bench press" --json | jq '.[0].id'
"D04F09B2"

# View history
$ hevy history D04F09B2 -n 10

Export workouts to JSON

hevy workouts --all --json > workouts.json

Create a routine

cat << 'EOF' | hevy create-routine
{
  "routine": {
    "title": "Quick Push",
    "exercises": [
      {
        "exercise_template_id": "D04F09B2",
        "sets": [
          { "type": "normal", "weight_kg": 60, "reps": 10 },
          { "type": "normal", "weight_kg": 60, "reps": 10 },
          { "type": "normal", "weight_kg": 60, "reps": 10 }
        ]
      }
    ]
  }
}
EOF

API Client

This package also exports a TypeScript client for programmatic use:

import { HevyClient } from 'hevy-cli';

const client = new HevyClient({ apiKey: process.env.HEVY_API_KEY });

const workouts = await client.getRecentWorkouts(5);
const routines = await client.getAllRoutines();
const exercises = await client.searchExerciseTemplates('squat');

Development

git clone https://github.com/mjrussell/hevy-cli
cd hevy-cli
npm install
npm run build
node dist/cli.js --help

License

MIT © Matt Russell

Disclaimer

This is an unofficial tool created by the community. Hevy is a trademark of Hevy Inc. This project is not affiliated with, endorsed by, or connected to Hevy in any way.

Requires Hevy Pro subscription for API access.