Hevy CLI

A command-line interface for the Hevy fitness tracking app. Manage your workouts, routines, and exercises directly from the terminal.

TLDR

# Install
$> go install github.com/nsampre/hevycli@latest

# Configure with your API key from https://hevy.com/settings?developer
$> hevycli config set-api-key <your-api-key-uuid>

# View your workout history
$> hevycli workouts list

┌──────────────────────────────────────┬──────────────────────┬──────────────────┬───────────┬──────────┐
│                  ID                  │        TITLE         │       DATE       │ EXERCISES │ DURATION │
├──────────────────────────────────────┼──────────────────────┼──────────────────┼───────────┼──────────┤
│ f75e9c13-32d7-407d-9715-011f5d5698fa │ Morning workout ☀️    │ 2025-06-19 04:21 │ 5         │ 38m      │
│ 9544ef0f-ccfb-4943-afb8-0ebf677c2e26 │ Morning workout ☀️    │ 2025-06-18 05:35 │ 6         │ 48m      │
│ a856d5f3-6210-4522-8f9d-167d98254e43 │ Morning workout ☀️    │ 2025-06-13 05:00 │ 6         │ 54m      │
│ 34a12b2b-bb18-496c-bab5-37c49b474fcd │ Morning workout ☀️    │ 2025-06-10 06:23 │ 5         │ 45m      │
│ 1682b279-6b4f-4b38-b8f0-37760deaf184 │ Afternoon workout 💪 │ 2025-06-07 13:31 │ 5         │ 37m      │
│ 5c101486-c9fb-41c2-ba53-21e2a0f4b2cd │ Morning workout ☀️    │ 2025-06-05 04:53 │ 6         │ 35m      │
│ ba663cbc-107f-4b9c-9871-b39102d2660c │ Morning workout ☀️    │ 2025-06-03 05:08 │ 5         │ 33m      │
│ 78f694da-7e2d-4d0b-85f1-c2058f37ce85 │ Morning workout ☀️    │ 2025-05-27 05:03 │ 4         │ 32m      │
│ 8cea716c-2d37-4d4e-99c7-cf5e633d9dc2 │ Morning workout ☀️    │ 2025-05-26 05:25 │ 4         │ 44m      │
│ 98965cac-d64f-47e8-abae-53fe4edf50ab │ Morning workout ☀️    │ 2025-05-23 04:29 │ 5         │ 36m      │
└──────────────────────────────────────┴──────────────────────┴──────────────────┴───────────┴──────────┘

$> hevycli workouts get f75e9c13-32d7-407d-9715-011f5d5698fa

Workout: Morning workout ☀️
ID: f75e9c13-32d7-407d-9715-011f5d5698fa
Short ID:
Date: 2025-06-19 04:21
Duration: 38 minutes

Exercises (5):

1. Hip Abduction (Machine)
┌─────┬────────┬────────────────┬──────┬─────────────────┬─────────────────┬─────┐
│ SET │  TYPE  │ WEIGHT  ( KG ) │ REPS │ DISTANCE  ( M ) │ DURATION  ( S ) │ RPE │
├─────┼────────┼────────────────┼──────┼─────────────────┼─────────────────┼─────┤
│ 1   │ normal │ 85.0           │ 10   │ -               │ -               │ -   │
│ 2   │ normal │ 90.0           │ 10   │ -               │ -               │ -   │
│ 3   │ normal │ 95.0           │ 12   │ -               │ -               │ -   │
└─────┴────────┴────────────────┴──────┴─────────────────┴─────────────────┴─────┘

2. Hip Adduction (Machine)
┌─────┬────────┬────────────────┬──────┬─────────────────┬─────────────────┬─────┐
│ SET │  TYPE  │ WEIGHT  ( KG ) │ REPS │ DISTANCE  ( M ) │ DURATION  ( S ) │ RPE │
├─────┼────────┼────────────────┼──────┼─────────────────┼─────────────────┼─────┤
│ 1   │ normal │ 95.0           │ 10   │ -               │ -               │ -   │
│ 2   │ normal │ 95.0           │ 10   │ -               │ -               │ -   │
│ 3   │ normal │ 95.0           │ 10   │ -               │ -               │ -   │
└─────┴────────┴────────────────┴──────┴─────────────────┴─────────────────┴─────┘

3. Leg Press Horizontal (Machine)
┌─────┬────────┬────────────────┬──────┬─────────────────┬─────────────────┬─────┐
│ SET │  TYPE  │ WEIGHT  ( KG ) │ REPS │ DISTANCE  ( M ) │ DURATION  ( S ) │ RPE │
├─────┼────────┼────────────────┼──────┼─────────────────┼─────────────────┼─────┤
│ 1   │ normal │ 181.0          │ 8    │ -               │ -               │ -   │
│ 2   │ normal │ 181.0          │ 8    │ -               │ -               │ -   │
│ 3   │ normal │ 181.0          │ 8    │ -               │ -               │ -   │
└─────┴────────┴────────────────┴──────┴─────────────────┴─────────────────┴─────┘

4. Bulgarian Split Squat
┌─────┬────────┬────────────────┬──────┬─────────────────┬─────────────────┬─────┐
│ SET │  TYPE  │ WEIGHT  ( KG ) │ REPS │ DISTANCE  ( M ) │ DURATION  ( S ) │ RPE │
├─────┼────────┼────────────────┼──────┼─────────────────┼─────────────────┼─────┤
│ 1   │ normal │ 30.0           │ 16   │ -               │ -               │ -   │
│ 2   │ normal │ 30.0           │ 16   │ -               │ -               │ -   │
│ 3   │ normal │ 30.0           │ 16   │ -               │ -               │ -   │
└─────┴────────┴────────────────┴──────┴─────────────────┴─────────────────┴─────┘

5. Sumo Squat (Dumbbell)
┌─────┬────────┬────────────────┬──────┬─────────────────┬─────────────────┬─────┐
│ SET │  TYPE  │ WEIGHT  ( KG ) │ REPS │ DISTANCE  ( M ) │ DURATION  ( S ) │ RPE │
├─────┼────────┼────────────────┼──────┼─────────────────┼─────────────────┼─────┤
│ 1   │ normal │ 15.0           │ 12   │ -               │ -               │ -   │
│ 2   │ normal │ 15.0           │ 12   │ -               │ -               │ -   │
│ 3   │ normal │ 15.0           │ 12   │ -               │ -               │ -   │
└─────┴────────┴────────────────┴──────┴─────────────────┴─────────────────┴─────┘

# Get detailed workout information (supports short IDs)
hevycli workouts get 437d04ad

# View total workout count
hevycli workouts count
# Output: Total workouts: 247

# List your routines
hevycli routines list

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

Prerequisites

• Go 1.24.0 or later
• Hevy Pro subscription
• Hevy API key (get it from https://hevy.com/settings?developer)

Installation

Install via Go

The easiest way to install:

go install github.com/nsampre/hevycli@latest

This will install the hevycli binary to your $GOPATH/bin directory (usually ~/go/bin).

Make sure $GOPATH/bin is in your PATH:

export PATH=$PATH:$(go env GOPATH)/bin

Build from source

git clone https://github.com/nsampre/hevycli.git
cd hevycli
go build -o hevycli .

For a smaller binary:

go build -ldflags="-s -w" -o hevycli .

Install to system

sudo cp hevycli /usr/local/bin/

Configuration

Set your Hevy API key:

hevycli config set-api-key <your-api-key-uuid>

View current configuration:

hevycli config show

Environment Variable

You can also set your API key via environment variable:

export HEVY_API_KEY=<your-api-key-uuid>

Usage

Global Flags

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

Workouts

List recent workouts:

hevycli workouts list
hevycli workouts list --page 2 --page-size 20
hevycli workouts list --format json

Get workout details:

hevycli workouts get <workout-id>

Get total workout count:

hevycli workouts count

Routines

List routines:

hevycli routines list
hevycli routines list --page 2

Get routine details:

hevycli routines get <routine-id>

Exercises

List exercise templates:

hevycli exercises list
hevycli exercises list --page 2 --page-size 20

Get exercise template details:

hevycli exercises get <template-id>

Get exercise history:

hevycli exercises history <template-id>
hevycli exercises history <template-id> --from 2024-01-01

Examples

# View your last 5 workouts
hevycli workouts list --page-size 5

# Get detailed information about a specific workout
hevycli workouts get abc123def456

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

# Check progress on bench press over time
hevycli exercises history <bench-press-template-id> --from 2024-01-01

# See total workout count
hevycli workouts count

Project Structure

hevycli/
├── cmd/                    # CLI commands
│   ├── root.go            # Root command & global flags
│   ├── config.go          # Configuration commands
│   ├── workouts.go        # Workout commands
│   ├── routines.go        # Routine commands
│   └── exercises.go       # Exercise commands
├── internal/
│   ├── api/               # API client
│   │   ├── client.go      # HTTP client
│   │   ├── types.go       # API types
│   │   ├── workouts.go    # Workout endpoints
│   │   ├── routines.go    # Routine endpoints
│   │   └── exercises.go   # Exercise endpoints
│   ├── config/            # Configuration management
│   │   └── config.go      # Config loading/saving
│   └── display/           # Output formatting
│       └── format.go      # Table/JSON formatting
├── main.go                # Entry point
├── go.mod                 # Go module definition
└── README.md              # This file

Development

Build

go build -o hevycli.

Run tests

go test ./...

Format code

go fmt ./...

Update dependencies

go mod tidy

API Reference

This CLI uses the official Hevy API: https://api.hevyapp.com/docs/

License

This project is not officially associated with Hevy. Use at your own risk.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.