agentleFS
chrisdocchrisdoc/hevy-mcp/skills/hevy-cli/SKILL.md

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

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
  1. Distinctive:

    Use this skill to manage workouts in the Hevy app.

    line 8
  2. Very specific:

    Keep the key out of command arguments, JSON payloads, URLs, shell history, screenshots, logs, and responses.

    line 38
  3. Distinctive:

    If a user requests deletion of any resource, explain that deletion is not supported by the CLI or the Hevy API integration.

    line 61
  4. Distinctive:

    Run route help whenever a flag or argument is uncertain:

    line 66
  5. Very specific:

    Use the narrowest read route and date/page range that answers the question.

    line 72
  6. Very specific:

    Use --json when output will be searched, filtered, or piped.

    line 73
  7. Very specific:

    Every create/update requires --data <value> and an explicit --yes.

    line 88
  8. Very specific:

    When HTTP 403 occurs, report it as a generic API failure rather than an invalid API key.

    line 135
  9. Very specific:

    Use YYYY-MM-DD for measurement dates and ISO timestamps with timezone offsets for history/event filters.

    line 149

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

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

  • user
  • workouts list, workouts get, workouts count, workouts events
  • routines list, routines get
  • exercises search, exercises get, exercises history
  • measurements list, measurements get
  • summary

Create/update routes:

  • workouts create, workouts update <workout-id>
  • routines create, routines update <routine-id>
  • exercises create
  • folders create
  • measurements 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> --help

Use 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 \
  --json

4. 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 --json

Workout 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 — success
  • 1 — missing or invalid configuration
  • 2 — invalid command, flag, payload, or value
  • 3 — Hevy API failure
  • 4 — 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.