@trainheroic-unofficial/cli 0.1.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -4,6 +4,13 @@ A command-line tool for the TrainHeroic coaching API. Takes credentials from the
4
4
 
5
5
  Part of the [trainheroic-unofficial](../../README.md) workspace.
6
6
 
7
+ ## Contents
8
+
9
+ - [Install](#install)
10
+ - [Usage](#usage)
11
+ - [Conventions](#conventions)
12
+ - [Develop](#develop)
13
+
7
14
  ## Install
8
15
 
9
16
  ```bash
@@ -11,39 +18,99 @@ npm install -g @trainheroic-unofficial/cli
11
18
  # or: npx @trainheroic-unofficial/cli <command>
12
19
  ```
13
20
 
21
+ Needs Node >= 18 and an existing TrainHeroic account.
22
+
14
23
  ## Usage
15
24
 
25
+ Set your TrainHeroic login in the environment (stored in plaintext and shell history — treat
26
+ it as a secret), then run a command. Every command prints JSON to stdout.
27
+
16
28
  ```bash
17
29
  export TRAINHEROIC_EMAIL="coach@example.com"
18
30
  export TRAINHEROIC_PASSWORD="..."
19
31
 
20
- trainheroic whoami
21
- trainheroic exercise resolve "Back Squat"
22
- trainheroic workout build --program 12345 --date 2026-6-22 --file day.json
32
+ trainheroic whoami # confirm auth; prints your account
33
+ trainheroic coach exercise resolve "Back Squat" # name -> exercise (id, units)
23
34
  ```
24
35
 
25
- During development, run from source with `pnpm start <args>`; after `pnpm build`, the
26
- `trainheroic` binary (`dist/cli.mjs`) does the same.
36
+ **Driving this from an AI agent?** Run `trainheroic skill` first — it prints the full
37
+ workflow guide (with copy-paste workout-spec examples) to stdout, version-matched to the
38
+ binary; `trainheroic skill --full` adds the API and workout-creation reference docs. It's the
39
+ fastest way to get the spec shapes right instead of guessing from flags.
40
+
41
+ Commands split into three groups. `whoami` and `request` are **shared** (role-agnostic).
42
+ Everything for managing a roster lives under **`coach`** — reads (`coach athletes`,
43
+ `coach programs`, `coach teams`, `coach program <id>`, …), the exercise library
44
+ (`coach exercise resolve|search|get|sync|create|forget|stats`), the workout lifecycle
45
+ (`coach workout build|read|publish|remove`), and messaging
46
+ (`coach message list|read|draft|send|delete`). Your own training lives under **`athlete`**.
47
+ Run `trainheroic` with no command for the full reference. Dates are `Y-M-D` with a 1-based
48
+ month, e.g. `2026-6-22` or `2026-06-22` for 22 June 2026.
27
49
 
28
- Run `trainheroic` with no command to print the full help. Commands group into reads
29
- (`whoami`, `athletes`, `programs`, `teams`, `program <id>`, and the rest), a raw `request`
30
- escape hatch, exercise-library operations (`resolve`, `search`, `get`, `sync`, `create`,
31
- `forget`, `stats`), the workout lifecycle (`build`, `read`, `publish`, `remove`), and
32
- messaging (`list`, `read`, `draft`, `send`, `delete`).
50
+ ### Building a workout
51
+
52
+ `coach workout build` reads a workout spec — a JSON file (`--file`), an inline argument, or
53
+ stdin — and writes it into a program on a date. `--program` is a program id (find it in the
54
+ program's URL in the TrainHeroic web app, or run `trainheroic coach programs`). The spec is
55
+ `{ blocks, instruction? }` (a bare blocks array is also accepted). Each exercise's `id` is a
56
+ library id; get one with `coach exercise resolve`. `reps` and `weight` take a scalar or a
57
+ per-set array (`"reps": [5, 5, 3]`); loads use the exercise's configured unit. The full schema
58
+ is `WorkoutSpec` in [`@trainheroic-unofficial/dto`](../dto).
59
+
60
+ ```jsonc
61
+ // day.json — one block with one exercise (id 41822 is a library exercise id)
62
+ {
63
+ "instruction": "Warm up first.",
64
+ "blocks": [
65
+ {
66
+ "title": "Strength",
67
+ "exercises": [{ "id": 41822, "sets": 5, "reps": 5, "weight": 225, "rpe": 8 }],
68
+ },
69
+ ],
70
+ }
71
+ ```
72
+
73
+ ```bash
74
+ # Build as a draft (988 is the program id):
75
+ trainheroic coach workout build --program 988 --date 2026-6-22 --file day.json
76
+
77
+ # Build and publish to athletes (publishing is athlete-facing, so it needs --yes):
78
+ trainheroic coach workout build --program 988 --date 2026-6-22 --file day.json --publish --yes
79
+ ```
80
+
81
+ ### Raw requests
82
+
83
+ For an endpoint with no dedicated command, call it directly:
84
+
85
+ ```bash
86
+ trainheroic request GET /user/simple
87
+ trainheroic request POST /some/path '{"key":"value"}' --base apis
88
+ ```
89
+
90
+ `--base` selects the host: `coach` (the default, `api.trainheroic.com`) or `apis`
91
+ (`apis.trainheroic.com`). The body can be inline JSON (as above) or `--file <path>`.
33
92
 
34
93
  ## Conventions
35
94
 
36
- - Output is JSON on stdout; errors go to stderr with a non-zero exit code.
37
- - Actions that touch an athlete or delete data require an explicit `--yes`. That covers
38
- `workout publish`, `workout remove`, `exercise forget`, `message send`, `message delete`,
39
- and `workout build --publish`.
95
+ - Output is JSON on stdout; errors go to stderr with a non-zero exit code and a readable
96
+ validation path on bad input.
97
+ - Actions that touch an athlete or delete data require an explicit `--yes`:
98
+ `coach workout publish`, `coach workout remove`, `coach exercise forget`,
99
+ `coach message send`, `coach message delete`, `athlete log-set`, and
100
+ `coach workout build --publish`. (`coach workout build` alone creates a draft; `--publish`
101
+ makes it visible to athletes, which is why that combination needs `--yes`.)
40
102
  - JSON input can be passed inline, with `--file <path>`, or piped on stdin. Inputs are
41
- validated against the shared schemas from `@trainheroic-unofficial/dto`.
103
+ validated against the shared schemas from `@trainheroic-unofficial/dto` before sending.
42
104
  - The session token and the exercise library are cached under `~/.trainheroic/`. The library
43
- file is the same shape the local server uses, so the two share a cache.
105
+ file matches the shape the local coach server (`@trainheroic-unofficial/coach-mcp`) writes,
106
+ so the CLI and that server share one cache.
44
107
 
45
108
  ## Develop
46
109
 
110
+ Run `pnpm install` once at the repo root (Node >= 24, pnpm 11), then from this package. During
111
+ development, run from source with `pnpm start <args>`; after `pnpm build`, the `trainheroic`
112
+ binary (`dist/cli.mjs`) does the same.
113
+
47
114
  ```bash
48
115
  pnpm start whoami # tsx src/cli.ts
49
116
  pnpm build # tsdown -> dist/cli.mjs