hevy-cli

Make your AI agent the perfect personal trainer.

A terminal client for Hevy that turns your AI agent into a fitness coach — it reads your workouts, detects plateaus, checks your recovery, and tells you what to train next. Deterministic --json output, single-binary install, and a SKILL.md any agent picks up instantly.

Use with AI Agents · Install · Features · WHOOP

---

🤖 Use with AI Agents

hevy-cli gives your agent everything it needs to coach you. No scraping, no browser, no API wrangling — just structured data from one binary.

What your agent can do with this

Agent task	Command	What it gets
"Should I train today?"	hevy readiness --json	WHOOP recovery + last session + muscle fatigue
"What should I train?"	hevy plan --json	Days since each muscle group, suggested split
"Am I stalling?"	hevy plateau --json	Exercises with no weight increase across sessions
"How's my week?"	hevy week --json	Volume, sessions, duration, muscle coverage
"Keep me accountable"	hevy streak --json	Consecutive training weeks, consistency %
"Show my PRs"	hevy pr --all --json	Personal records across all exercises

Setup for your agent

# 1. Install the binary
curl -sL https://github.com/dhruvkelawala/hevy-cli/releases/latest/download/hevy_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz | tar xz -C /tmp && mv /tmp/hevy ~/.local/bin/

# 2. Set the API key
export GO_HEVY_API_KEY="your-hevy-api-key"

# 3. Drop the skill file into your agent's workspace
cp SKILL.md ~/.openclaw/workspace/skills/hevy-cli/

The SKILL.md tells agents how to install, authenticate, and use every command — it's the only file your agent needs.

Works with

• OpenClaw — drop SKILL.md into the skills directory, agent auto-discovers it
• Claude Code — add SKILL.md to your project, Claude Code reads it as context
• Codex — pipe --json output into agent context, or use AGENTS.md references
• Any agent framework — it's a single binary with structured JSON output, no SDK needed

---

🚀 Install

# macOS / Linux — download latest binary
curl -sL https://github.com/dhruvkelawala/hevy-cli/releases/latest/download/hevy_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz | tar xz -C /tmp && mv /tmp/hevy ~/.local/bin/

# Or via Go
go install github.com/dhruvkelawala/hevy-cli@latest

Then authenticate:

hevy init
# or: export GO_HEVY_API_KEY="your-key"

---

🏋️ Features

See your training at a glance

$ hevy week
sessions          2
total_volume      19,599kg
avg_duration_min  73.4
muscle_groups     chest(1), lats(1), biceps(1), triceps(1), quads(1), hamstrings(1)

$ hevy streak
Current streak: 5 weeks (since Mar 2)

$ hevy calendar
March 2026
Mo Tu We Th Fr Sa Su
[2]  3  4  5  6 [7]  8
[9] [10] 11 [12] 13 14 15
[16] 17 [18] [19] 20 21 22
23 24 [25] 26 [27] 28 29
[30] [31]

Track your strength

$ hevy pr --all
Squat (Barbell)            70.00kg × 12
Barbell Bench Press        55.00kg × 8
Bent Over Row              50.00kg × 12
Chest Press (Machine)      40.00kg × 12

$ hevy progress "Squat"
Squat (Barbell) — last 2 sessions
Mar 18  65.00kg  █████████████
Mar 30  70.00kg  ██████████████

$ hevy volume "Squat"
Squat (Barbell) volume
Mar 18  2,080kg  ████████
Mar 30  3,420kg  ██████████████

Know what to train next

$ hevy plan
Last trained:
  chest       0 days ago (Tue)
  back        0 days ago (Tue)
  legs        1 day ago (Mon)
  shoulders   5 days ago (Thu)

Suggested next: Pull
Reason: shoulders haven't been hit in 5 days

$ hevy split
TYPE   COUNT  PERCENTAGE
Legs       3  27%
Upper      3  27%
Pull       2  18%
Push       1   9%

Detect problems before they stall you

$ hevy plateau
Bench Press (Barbell)     50.00kg  stalled 4 sessions
Overhead Press            35.00kg  stalled 3 sessions

$ hevy consistency
Mar 2026   12 sessions   75% hit rate
Feb 2026    0 sessions    0%

$ hevy fatigue
No RPE data found. Log RPE in Hevy to enable fatigue tracking.

🟢 WHOOP Readiness

Combine your WHOOP recovery data with training history for a single "should I train today?" answer.

$ hevy readiness
🟢 WHOOP Recovery: 89%  |  HRV: 78ms  |  RHR: 56bpm

Status: GREEN — full send. heavy compounds ok.
Last trained: Upper (Mar 31)
Avoid today: back, biceps, chest, shoulders, triceps
Suggested: Pull

Recovery history (last 7 days):
Mon  89%  ████████
Sun  39%  ███
Sat  99%  █████████
Fri  66%  ██████

# Optional fallback if WHOOP is unavailable
hevy readiness --no-whoop

How the WHOOP integration works

hevy-cli talks to the WHOOP API natively from Go.

For normal usage, hevy readiness:

• loads credentials from ~/.whoop/credentials.json
• loads tokens from ~/.whoop/token.json
• refreshes WHOOP OAuth tokens in Go when needed
• fetches recovery history from https://api.prod.whoop.com/developer/v2/recovery

hevy-cli then parses the recovery score, HRV, and resting heart rate, combines that with your recent Hevy workouts, and produces a readiness recommendation.

If WHOOP isn't configured, hevy-cli falls back to a simpler readiness heuristic based on your recent training history. You can also force that mode with:

hevy readiness --no-whoop

Integrate your WHOOP account with hevy-cli

WHOOP setup steps

1. Create a WHOOP developer app at https://developer.whoop.com
2. Set up WHOOP credentials in ~/.whoop/credentials.json
3. Complete the OAuth flow so tokens are saved to ~/.whoop/token.json
4. Run:

hevy readiness

You do not need the OpenClaw whoop-tracker Python helper for normal readiness usage.

whoop_path remains in config only for backward compatibility with older setups and is no longer used by the native readiness path.

---

📋 All 30+ Commands

Core — workouts, exercises, routines

Command	What it does
hevy status	Verify API access
hevy me	User profile
hevy count	Total workout count
hevy workouts	List recent workouts
hevy workout <id>	Show/mutate a workout
hevy last	Most recent workout
hevy today	Today's workout
hevy routines	List routines
hevy routine <id>	Routine details
hevy exercises	Search exercise templates
hevy exercise <id>	Exercise details
hevy history <id>	Exercise history
hevy export --format csv	Export all workouts

Analytics — track, compare, visualize

Command	What it does
hevy progress "Squat"	ASCII progression chart
hevy streak	Weekly streak tracker
hevy pr --all	All personal records
hevy week	Weekly summary
hevy diff	Compare last two workouts
hevy volume "Squat"	Volume over time
hevy muscles	Muscle groups hit this week
hevy calendar	ASCII workout calendar
hevy search upper	Search workouts

Advanced — plan, detect, recover

Command	What it does
hevy plan	Suggest next workout
hevy consistency	Training consistency report
hevy plateau	Detect stalled exercises
hevy supersets	Superset pairings
hevy fatigue	RPE trend analysis
hevy split	Actual training split
hevy records	All-time vs current bests
hevy rest	Time efficiency
hevy readiness	WHOOP + training readiness

Utility

Command	What it does
hevy config	Show/update config
hevy config set	Set a config value
hevy completion zsh	Shell completions
hevy init	Interactive setup
hevy version	Print version

---

⚙️ Output modes

hevy workouts              # table (default)
hevy workouts --json       # JSON
hevy workouts --compact    # one-liner
hevy last --lbs            # pounds
hevy last --kg             # kilograms

---

🛠️ Development

git clone https://github.com/dhruvkelawala/hevy-cli.git
cd hevy-cli
go build ./...
go test ./...
go vet ./...

Releases are built automatically via GoReleaser on tag push.

---

License

MIT