hevy-cli
Skill541 starsChanged 2 months agoMITView on GitHub
Manage Hevy workouts from the terminal: read and summarize training data, search exercise templates, and create or update workouts, routines, exercises, folders, or body measurements.
- Reads credentials
- Installs packages
In this repository11 other files it gives its agents.
- AGENTS.mdAGENTS.md
- build-mcpbSkill
- build-mcp-serverSkill
- code-reviewSkill
- diagnosing-bugsSkill
- improve-codebase-architectureSkill
- sentrySkill
- thermo-nuclear-code-quality-reviewSkill
- using-entireSkill
- wayfinderSkill
- hevy-workoutsSkill
The file
We split this skill into the rules it gives an agent
9 rules. About 0 are common, 3 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 8
Use this skill to manage workouts in the Hevy app.
- Very specific: line 38
Keep the key out of command arguments, JSON payloads, URLs, shell history, screenshots, logs, and responses.
- Distinctive: line 61
If a user requests deletion of any resource, explain that deletion is not supported by the CLI or the Hevy API integration.
- Distinctive: line 66
Run route help whenever a flag or argument is uncertain:
- Very specific: line 72
Use the narrowest read route and date/page range that answers the question.
- Very specific: line 73
Use --json when output will be searched, filtered, or piped.
- Very specific: line 88
Every create/update requires --data <value> and an explicit --yes.
- Very specific: line 135
When HTTP 403 occurs, report it as a generic API failure rather than an invalid API key.
- Very specific: line 149
Use YYYY-MM-DD for measurement dates and ISO timestamps with timezone offsets for history/event filters.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Hevy CLI
Use this skill to manage workouts in the Hevy app. The CLI supports reads, creates, and updates. Deletion is unsupported.
1. Install or run the published package
# One-off use; npm downloads the published package when needed.
npx @chrisdoc/hevy-cli --help
# Local project install.
npm i @chrisdoc/hevy-cli
npx hevy --help
# Persistent global install.
npm i -g @chrisdoc/hevy-cli
hevy --helpThe package requires Node.js 24 or newer. Use npx --yes
@chrisdoc/hevy-cli ... in non-interactive scripts. Installation is verified
when npx @chrisdoc/hevy-cli --version or hevy --version prints a version.
2. Configure the API key
The CLI reads credentials only from HEVY_API_KEY:
export HEVY_API_KEY='<your-hevy-api-key>'Keep the key out of command arguments, JSON payloads, URLs, shell history,
screenshots, logs, and responses. --help and --version work without it.
3. Choose a route
Read routes:
userworkouts list,workouts get,workouts count,workouts eventsroutines list,routines getexercises search,exercises get,exercises historymeasurements list,measurements getsummary
Create/update routes:
workouts create,workouts update <workout-id>routines create,routines update <routine-id>exercises createfolders createmeasurements create <YYYY-MM-DD>,measurements update <YYYY-MM-DD>
The CLI exposes no delete, update-exercise-template, or update-folder routes. If a user requests deletion of any resource, explain that deletion is not supported by the CLI or the Hevy API integration. Suggest a supported alternative, such as archiving the resource in Hevy if available or replacing it.
Run route help whenever a flag or argument is uncertain:
npx @chrisdoc/hevy-cli <command> --helpUse the narrowest read route and date/page range that answers the question.
Use --json when output will be searched, filtered, or piped.
For exercise work, search first and use the exact returned template ID. Create a custom exercise only when the required movement is absent:
npx @chrisdoc/hevy-cli exercises search "bench press" --json
npx @chrisdoc/hevy-cli exercises history <exercise-template-id> \
--start-date 2026-07-01T00:00:00Z \
--end-date 2026-07-31T23:59:59Z \
--json4. Supply mutation data safely
Every create/update requires --data <value> and an explicit --yes.
--noYes, omission, or any value other than true is rejected before the
CLI reads a file/stdin or calls Hevy. --data accepts inline JSON, @path
for a UTF-8 JSON file, or @- for JSON from stdin. Keys are camelCase and
payloads are wrapperless; do not submit { "workout": ... } or snake_case.
# Inline folder creation
npx @chrisdoc/hevy-cli folders create \
--data '{"name":"Strength"}' --yes
# Workout creation from a file
npx @chrisdoc/hevy-cli workouts create \
--data @workout.json --yes --json
# Piped full routine replacement
cat routine.json | npx @chrisdoc/hevy-cli routines update routine-123 \
--data @- --yes --json
# Numeric measurement update
npx @chrisdoc/hevy-cli measurements update 2026-07-27 \
--data '{"weightKg":80.5}' --yes --json
# Explicit-null measurement clearing
npx @chrisdoc/hevy-cli measurements update 2026-07-27 \
--data '{"fatPercent":null}' --yes --jsonWorkout and routine updates are full replacements. Include every exercise and
set that should remain; omitted content is not preserved. A routine update
cannot move a routine to another folder because Hevy's PUT endpoint has no
folderId.
Measurement updates are patches over Hevy's replacement PUT. The CLI reads the
existing date first, preserves omitted fields, replaces supplied numbers, and
uses explicit null to clear a field. Measurement create needs at least one
numeric field; update needs at least one supplied field. The date is the
positional argument and cannot appear in --data.
5. Handle writes and errors
Writes are never retried automatically. Creates are not idempotent, and an uncertain network result may already have committed. Verify an uncertain write with a read before deciding whether to retry. A duplicate measurement date is an API conflict (HTTP 409). HTTP 403 is a generic API failure because Hevy also uses it for routine and custom-exercise quotas.
When HTTP 403 occurs, report it as a generic API failure rather than an invalid
API key. Check the operation's permissions and routine/custom-exercise quota.
HTTP 401 is the authentication failure that should prompt checking
HEVY_API_KEY.
Successful --json commands write one JSON value plus newline to stdout.
Errors write one sanitized line to stderr. Exit codes:
0— success1— missing or invalid configuration2— invalid command, flag, payload, or value3— Hevy API failure4— network or timeout failure
Use YYYY-MM-DD for measurement dates and ISO timestamps with timezone
offsets for history/event filters. Quote user-provided queries and IDs.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

