Hevy

Interact with the Hevy fitness app via the hevy-cli command-line tool. Use when the user wants to view, create, or update workouts, routines, exercise templates, or routine folders in their Hevy account. Triggers on requests involving workout tracking, exercise history, routine management, or any Hevy-related data operations.

Security Scan

The skill's instructions require a Hevy CLI and an API key, but the published metadata does not declare those requirements — this mismatch and the lack of a trustworthy source/homepage make the package inconsistent and worth caution.

Purpose & Capability

The SKILL.md clearly expects the 'hevy' CLI and an HEVY_API_KEY environment variable (or --api-key flag) to interact with a Hevy account, but the registry metadata declares no required binaries and no required env vars. A Hevy integration legitimately needs an API key and the CLI binary; the metadata omission is an incoherence that could hide missing permissions or setup expectations.

Instruction Scope

The runtime instructions stay on-topic (list/create/update workouts, routines, templates). They instruct use of --exercises-json @filepath, which is normal for this tool but also enables sending file contents to the remote API if a filepath is provided. The instructions do not ask for unrelated files or credentials, but they assume the agent or user will supply file paths and the 'hevy' binary.

Install Mechanism

There is no install spec (instruction-only), which is lower risk, but the skill implicitly requires an external 'hevy' CLI binary to be present on PATH. The metadata does not declare this requirement; users should confirm how the CLI will be provided/installed before use.

Credentials

Functionality reasonably requires an HEVY_API_KEY (and the docs state it), but the skill's declared required env vars and primary credential are empty. That mismatch is a red flag — the skill will need a secret credential to function but the registry entry does not advertise it, preventing informed permission decisions.

Persistence & Privilege

The skill does not request always: true and does not appear to modify other skills or system-wide settings. It will run only when invoked or when the agent chooses to call it (default model invocation allowed).

What to consider before installing

Do not install blindly. Confirm the source and homepage of this skill (none provided). Ask the publisher to: (1) declare that the 'hevy' CLI binary is required, (2) list HEVY_API_KEY as a required credential in the metadata, and (3) explain how the CLI will be installed or supplied. If you proceed, only provide a Hevy API key you trust and avoid using @filepath arguments that could cause the agent/CLI to read and transmit sensitive local files. If you cannot verify the publisher, prefer a skill with a known source or one that uses an official API integration with clear metadata.

Hevy CLI

Use the hevy CLI to interact with Hevy fitness app data. Requires HEVY_API_KEY env var to be set.

Quick Start

# Verify access
hevy workouts count

# List recent workouts
hevy workouts list --page-size 10

# Raw JSON output for any command
hevy -j workouts list

Common Tasks

View workout history

hevy workouts list --page 1 --page-size 10
hevy workouts get <workout-id>

Check exercise progress

# Find the exercise template ID first
hevy exercises list --page-size 100

# Then get history for that exercise
hevy exercises history <template-id>
hevy exercises history <template-id> --start-date 2025-01-01 --end-date 2025-02-01

Create a workout

hevy workouts create \
  --title "Push Day" \
  --start-time 2025-01-15T08:00:00Z \
  --end-time 2025-01-15T09:00:00Z \
  --exercises-json '[{"exercise_template_id":"79D0BB3A","sets":[{"type":"normal","weight_kg":60,"reps":8}]}]'

For complex exercises, use a file: --exercises-json @exercises.json

Manage routines

hevy routines list
hevy routines create --title "Upper Body" --exercises-json @routine.json
hevy routines update <routine-id> --title "Updated Name"

Organize with folders

hevy folders list
hevy folders create --name "Hypertrophy Block"

Key Patterns

• All list commands accept --page and --page-size for pagination.
• Use -j flag before the subcommand for JSON output: hevy -j workouts list.
• Exercise data for create/update uses --exercises-json accepting inline JSON or @filepath.
• Set types: normal, warmup, failure, dropset.
• IDs are returned in list/get responses -- use JSON mode (-j) to get exact IDs for subsequent commands.

Full Command Reference

See references/commands.md for complete command syntax, all flag options, enum values for exercise types/equipment/muscle groups, and the exercises JSON schema.