@trainheroic-unofficial/cli

A command-line tool for the TrainHeroic API. Takes credentials from the environment, prints JSON.

Part of the trainheroic-unofficial workspace.

Contents

• Install
• Usage
• Conventions
• Develop

Install

npm install -g @trainheroic-unofficial/cli
# or: npx @trainheroic-unofficial/cli <command>

Needs Node >= 18 and an existing TrainHeroic account.

Usage

Set your TrainHeroic login in the environment (stored in plaintext and shell history, so treat it as a secret), then run a command. Every command prints JSON to stdout.

export TRAINHEROIC_EMAIL="[email protected]"
export TRAINHEROIC_PASSWORD="..."

trainheroic whoami                                # confirm auth; prints your account
trainheroic coach exercise resolve "Back Squat"   # name -> exercise (id, units)

Driving this from an AI agent? Run trainheroic skill first. It prints the full workflow guide (with copy-paste workout-spec examples) to stdout, version-matched to the binary. trainheroic skill --full adds the API and workout-creation reference docs, which is the quickest path to getting spec shapes right.

whoami and request are role-agnostic shared commands. Roster management lives under coach, covering reads (coach athletes, coach programs, coach teams, coach program <id>, …), the exercise library (coach exercise resolve|search|get|sync|create|forget|stats), the workout lifecycle (coach workout build|read|publish|remove), and messaging (coach message list|read|draft|send|delete). Your own training data lives under athlete. Run trainheroic with no command for the full reference. Dates are Y-M-D with a 1-based month, e.g. 2026-6-22 or 2026-06-22 for 22 June 2026.

Building a workout

coach workout build reads a workout spec (a JSON file via --file, an inline argument, or stdin) and writes it into a program on a date. --program is a program id (find it in the program's URL in the TrainHeroic web app, or run trainheroic coach programs). The spec is { blocks, instruction? } (a bare blocks array is also accepted). Each exercise's id is a library id; get one with coach exercise resolve. reps and weight take a scalar or a per-set array ("reps": [5, 5, 3]). reps is the primary value slot and weight is the secondary slot, so either can represent distance or time on an exercise configured that way. State primaryUnit for reps and secondaryUnit for weight using the fixed units returned by coach exercise resolve. The build stops before writing if a unit differs. The full schema is WorkoutSpec in @trainheroic-unofficial/dto.

// day.json: one block with one exercise (id 41822 is a library exercise id)
{
  "instruction": "Warm up first.",
  "blocks": [
    {
      "title": "Strength",
      "exercises": [
        {
          "id": 41822,
          "sets": 5,
          "reps": 5,
          "primaryUnit": "reps",
          "weight": 225,
          "secondaryUnit": "lb",
          "rpe": 8,
        },
      ],
    },
  ],
}

# Build as a draft (988 is the program id):
trainheroic coach workout build --program 988 --date 2026-6-22 --file day.json

# Build and publish to athletes (publishing is athlete-facing, so it needs --yes):
trainheroic coach workout build --program 988 --date 2026-6-22 --file day.json --publish --yes

Conventions

• Output is JSON on stdout; errors go to stderr with a non-zero exit code and a readable validation path on bad input.
• Actions that touch an athlete or delete data require an explicit --yes: coach workout publish, coach workout remove, coach exercise forget, coach message send, coach message delete, athlete log-set, athlete prescribe-set, and coach workout build --publish. (coach workout build alone creates a draft; --publish makes it visible to athletes, which is why that combination needs --yes.)
• JSON input can be passed inline, with --file <path>, or piped on stdin. Inputs are validated against the shared schemas from @trainheroic-unofficial/dto before sending.
• The session token and the exercise library are cached under ~/.trainheroic/. The library file matches the shape the local coach server (@trainheroic-unofficial/coach-mcp) writes, so the CLI and that server share one cache.

Develop

Run pnpm install once at the repo root (Node >= 24, pnpm 11), then from this package. During development, run from source with pnpm start <args>; after pnpm build, the trainheroic binary (dist/cli.mjs) does the same.

pnpm start whoami   # tsx src/cli.ts
pnpm build          # tsdown -> dist/cli.mjs
pnpm typecheck
pnpm test
pnpm exec vitest run test/parse.test.ts