Unofficial CLI for Hevy workout tracking
npm install 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.
``bash`
npm install -g hevy-cli
Or run directly with npx:
`bash`
npx hevy-cli --help
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
`bash`
hevy status # Check connection and workout count
hevy status --json # Machine-readable output
`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
hevy workout
`
`bash
hevy routines # List all routines
hevy routines --json
hevy routine
hevy routine
`
`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
hevy history
hevy history
`
`bash`
hevy folders # List routine folders
hevy folders --json
`bash`
hevy count # Show total workout count
hevy count --json
`bashCreate routine from JSON file
hevy create-routine -f routine.json
hevy create-routine -f routine.json --json
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
``MIT Ā© Matt Russell
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.