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

``bash
npm install -g hevy-cli
`

Or run directly with npx:

`bash
npx hevy-cli --help
`

Setup

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

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

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

3. Verify it works:

`bash
hevy status
`

Commands

$3

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

$3

`bash
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 # Show detailed workout
hevy workout --json
`

$3

`bash
hevy routines # List all routines
hevy routines --json

hevy routine # Show detailed routine
hevy routine --json --kg
`

$3

`bash
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 # Show history for an exercise
hevy history -n 50 # Limit entries
hevy history --kg
`

$3

`bash
hevy folders # List routine folders
hevy folders --json
`

$3

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

$3

`bash


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 -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

$3

`bash
$ 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
`

$3

`bash


Find exercise ID

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

View history

$ hevy history D04F09B2 -n 10
`

$3

`bash
hevy workouts --all --json > workouts.json
`

$3

`bash
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:

`typescript
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

`bash
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.