trainerroad-cli 0.1.0 → 0.2.0

package/README.md

@@ -14,28 +14,48 @@ CLI to fetch TrainerRoad data for your account, including:
 - power ranking and power records
 - weight history
 
+It can also perform a small set of verified calendar writes for planned workouts:
+
+- search the workout library by zone/profile/search text/duration/level
+- fetch AI suggested workouts from TrainNow
+- recommend library workouts against target duration/level/TSS
+- fetch workout-library details by workout ID
+- add a library workout to a calendar date
+- copy an existing planned workout to another date
+- move a planned workout to a new date
+- list TrainerRoad alternate workout options
+- replace a workout with a specific alternate
+- switch a workout between inside and outside
+
 ## Install
 
-### From GitHub
+### Run without install (npx)
 
 ```bash
-npx --yes github:quinnsprouse/trainerroad-cli help
+npx --yes trainerroad-cli help
 ```
 
-### Local development
+### Global install
 
 ```bash
-git clone https://github.com/quinnsprouse/trainerroad-cli.git
-cd trainerroad-cli
-npm install
-npm exec --yes trainerroad-cli -- help
+npm install -g trainerroad-cli
+trainerroad-cli help
 ```
 
-### Global
+### Local project install
 
 ```bash
-npm install -g github:quinnsprouse/trainerroad-cli
-trainerroad-cli help
+npm install trainerroad-cli
+npx trainerroad-cli help
+```
+
+### Local development (from source)
+
+```bash
+git clone https://github.com/quinnsprouse/trainerroad-cli.git
+cd trainerroad-cli
+npm install
+npm run help
 ```
 
 ## Quickstart
@@ -56,9 +76,37 @@ trainerroad-cli past --days 30 --json
 trainerroad-cli plan --view current --json
 trainerroad-cli levels --json
 trainerroad-cli ftp --json
+trainerroad-cli today --tz America/New_York --json
+trainerroad-cli train-now --duration 60 --json
+trainerroad-cli workout-library --zone "Endurance" --profile "Sustained Power" --min-duration 45 --max-duration 75 --json
+trainerroad-cli workout-recommend --zone "Endurance" --profile "Sustained Power" --target-duration 60 --target-level 1.0 --count 3 --json
+trainerroad-cli workout-details --id 18128 --include-chart --json
+trainerroad-cli add-workout --workout-id 18128 --date 2026-03-16 --json
+trainerroad-cli copy-workout --id <planned-activity-id> --date 2026-03-16 --json
+```
+
+3. Mutate planned workouts
+
+First get a planned workout ID from `future --details`:
+
+```bash
+trainerroad-cli future --days 14 --details --json
 ```
 
-3. Discover all commands
+Then use that planned activity ID:
+
+```bash
+trainerroad-cli workout-alternates --id <planned-activity-id> --category easier --json
+trainerroad-cli move-workout --id <planned-activity-id> --to 2026-03-13 --json
+trainerroad-cli replace-workout --id <planned-activity-id> --alternate-id <workout-id> --json
+trainerroad-cli switch-workout --id <planned-activity-id> --mode outside --json
+trainerroad-cli copy-workout --id <planned-activity-id> --date 2026-03-16 --json
+```
+
+`copy-workout` is the reliable way to place an existing planned workout on another date.
+`add-workout` exists, but TrainerRoad's add endpoints are still inconsistent and may fail even after retry/reconciliation.
+
+4. Discover all commands
 
 ```bash
 trainerroad-cli help
@@ -80,6 +128,7 @@ Use `--target <username>` and/or `--public` for public mode queries.
 - `--jsonl`: one record per line
 - `--fields a,b,c`: project record fields
 - `--records-only`: lighter record payloads
+- `--tz <IANA timezone>`: localize day boundaries/timestamps (defaults to `TR_TIMEZONE` or system timezone)
 
 ## Security
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trainerroad-cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Unofficial CLI for authenticating with TrainerRoad and querying timeline/workout data",
   "main": "src/cli.mjs",
   "bin": {
@@ -21,6 +21,7 @@
     "login": "node src/cli.mjs login",
     "whoami": "node src/cli.mjs whoami",
     "timeline": "node src/cli.mjs timeline",
+    "train-now": "node src/cli.mjs train-now",
     "events": "node src/cli.mjs events",
     "annotations": "node src/cli.mjs annotations",
     "levels": "node src/cli.mjs levels",
@@ -33,6 +34,15 @@
     "ftp-prediction": "node src/cli.mjs ftp-prediction",
     "power-ranking": "node src/cli.mjs power-ranking",
     "power-records": "node src/cli.mjs power-records",
+    "workout-library": "node src/cli.mjs workout-library",
+    "workout-recommend": "node src/cli.mjs workout-recommend",
+    "workout-details": "node src/cli.mjs workout-details",
+    "add-workout": "node src/cli.mjs add-workout",
+    "copy-workout": "node src/cli.mjs copy-workout",
+    "workout-alternates": "node src/cli.mjs workout-alternates",
+    "move-workout": "node src/cli.mjs move-workout",
+    "replace-workout": "node src/cli.mjs replace-workout",
+    "switch-workout": "node src/cli.mjs switch-workout",
     "logout": "node src/cli.mjs logout"
   },
   "keywords": [

package/src/cli.mjs

@@ -31,8 +31,28 @@ import { commandLevels } from "./commands/levels.mjs";
 import { commandPlan } from "./commands/plan.mjs";
 import { commandPowerRanking, commandPowerRecords } from "./commands/power.mjs";
 import { commandTimeline } from "./commands/timeline.mjs";
+import { commandTrainNow } from "./commands/train-now.mjs";
 import { commandWeightHistory } from "./commands/weight-history.mjs";
+import { commandWorkoutLibrary } from "./commands/workout-library.mjs";
+import { commandWorkoutRecommend } from "./commands/workout-recommend.mjs";
+import { commandAddWorkout, commandCopyWorkout, commandWorkoutDetails } from "./commands/workout-tools.mjs";
+import {
+  commandMoveWorkout,
+  commandReplaceWorkout,
+  commandSwitchWorkout,
+  commandWorkoutAlternates,
+} from "./commands/workout-mutations.mjs";
 import { commandFuture, commandPast, commandToday } from "./commands/workouts.mjs";
+import {
+  formatDateTimeInTimeZone,
+  isoDateShiftInTimeZone,
+  normalizeTimeZone,
+  parseApiDateTime,
+  summarizeActivityTimeWindow,
+  toDateOnlyInTimeZone,
+} from "./lib/timezone.mjs";
+
+let ACTIVE_TIME_ZONE = normalizeTimeZone();
 
 function printGlobalHelp() {
   console.log("trainerroad-cli (unofficial)");
@@ -53,9 +73,18 @@ function printGlobalHelp() {
   console.log("Examples:");
   console.log("  node src/cli.mjs login --username quinnsprouse --password-stdin");
   console.log("  node src/cli.mjs future --days 30 --details --json");
+  console.log("  node src/cli.mjs today --tz America/New_York --json");
   console.log("  node src/cli.mjs future --from 2026-03-01 --to 2026-03-31 --min-tss 60 --fields id,title,tss --jsonl");
   console.log("  node src/cli.mjs timeline --target quinnsprouse --public --json");
   console.log("  node src/cli.mjs ftp --target quinnsprouse --public --json");
+  console.log("  node src/cli.mjs move-workout --id <planned-id> --to 2026-03-13 --json");
+  console.log("  node src/cli.mjs workout-alternates --id <planned-id> --category easier --json");
+  console.log('  node src/cli.mjs workout-library --zone "Endurance" --profile "Sustained Power" --min-duration 45 --max-duration 75 --json');
+  console.log('  node src/cli.mjs workout-recommend --zone "Endurance" --profile "Sustained Power" --target-duration 60 --target-level 1.0 --count 3 --json');
+  console.log("  node src/cli.mjs train-now --duration 60 --json");
+  console.log("  node src/cli.mjs workout-details --id 18128 --include-chart --json");
+  console.log("  node src/cli.mjs add-workout --workout-id 18128 --date 2026-03-16 --json");
+  console.log("  node src/cli.mjs copy-workout --id <planned-id> --date 2026-03-16 --json");
 }
 
 function levenshteinDistance(left, right) {
@@ -179,6 +208,7 @@ function printCommandHelp(command, flags = {}) {
       command,
       summary: def.summary,
       usage: def.usage,
+      timezoneOption: "--tz <IANA timezone> (defaults to TR_TIMEZONE or system timezone)",
       supportsAgentFilters: FILTERABLE_COMMANDS.has(command),
       agentFilterOptions: FILTERABLE_COMMANDS.has(command) ? AGENT_FILTER_OPTIONS : [],
       agentOutputOptions: FILTERABLE_COMMANDS.has(command) ? AGENT_OUTPUT_OPTIONS : [],
@@ -194,6 +224,9 @@ function printCommandHelp(command, flags = {}) {
   console.log("");
   console.log("Usage:");
   for (const line of def.usage) console.log(`  ${line}`);
+  console.log("");
+  console.log("Timezone:");
+  console.log("  --tz <IANA timezone> Override local-day bucketing (defaults: TR_TIMEZONE or system timezone).");
   if (FILTERABLE_COMMANDS.has(command)) {
     console.log("");
     console.log("Agent filters:");
@@ -234,9 +267,7 @@ function parseArgs(argv) {
 }
 
 function isoDateShift(days) {
-  const date = new Date();
-  date.setUTCDate(date.getUTCDate() + days);
-  return date.toISOString().slice(0, 10);
+  return isoDateShiftInTimeZone(days, ACTIVE_TIME_ZONE);
 }
 
 function toIsoDateFromPlanned(item) {
@@ -244,8 +275,26 @@ function toIsoDateFromPlanned(item) {
 }
 
 function toIsoDate(value) {
-  if (typeof value === "string" && value.length >= 10) return value.slice(0, 10);
-  return new Date(value).toISOString().slice(0, 10);
+  if (typeof value === "string" && value.length >= 10 && /^\d{4}-\d{2}-\d{2}/.test(value)) {
+    return value.slice(0, 10);
+  }
+  return (
+    toDateOnlyInTimeZone(value, ACTIVE_TIME_ZONE, { assumeUtcForOffsetlessDateTime: true }) ??
+    new Date(value).toISOString().slice(0, 10)
+  );
+}
+
+function formatDateTime(value) {
+  return (
+    formatDateTimeInTimeZone(value, ACTIVE_TIME_ZONE, { assumeUtcForOffsetlessDateTime: true }) ??
+    String(value ?? "")
+  );
+}
+
+function summarizeActivityTime(started, durationInSeconds) {
+  return summarizeActivityTimeWindow(started, durationInSeconds, ACTIVE_TIME_ZONE, {
+    assumeUtcForOffsetlessDateTime: true,
+  });
 }
 
 function normalizeDateOnlyInput(value, fallback) {
@@ -292,8 +341,10 @@ function normalizeFtpHistory(raw) {
       const valueRaw = item?.value ?? item?.Value ?? null;
       const value = Number(valueRaw);
       if (!dateRaw || !Number.isFinite(value)) return null;
+      const parsedDate = parseApiDateTime(dateRaw, { assumeUtcForOffsetlessDateTime: true });
+      if (!parsedDate) return null;
       return {
-        date: new Date(dateRaw).toISOString(),
+        date: parsedDate.toISOString(),
         dateOnly: toIsoDate(dateRaw),
         value,
       };
@@ -328,9 +379,11 @@ function normalizeFitnessThresholds(raw) {
       const valueRaw = item?.value ?? item?.Value ?? null;
       const value = Number(valueRaw);
       if (!dateRaw || !Number.isFinite(value)) return null;
+      const parsedDate = parseApiDateTime(dateRaw, { assumeUtcForOffsetlessDateTime: true });
+      if (!parsedDate) return null;
       return {
         id: item?.id ?? item?.Id ?? null,
-        date: new Date(dateRaw).toISOString(),
+        date: parsedDate.toISOString(),
         dateOnly: toIsoDate(dateRaw),
         value,
         isApplied: Boolean(item?.isApplied ?? item?.IsApplied),
@@ -397,9 +450,21 @@ async function readPasswordFromStdin() {
   return Buffer.concat(chunks).toString("utf8").trim();
 }
 
+function withTimeZoneMeta(payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return payload;
+  if (payload.timeZone != null) return payload;
+  return { ...payload, timeZone: ACTIVE_TIME_ZONE };
+}
+
 async function writeOutput(payload, flags, textRenderer = null) {
+  const payloadWithTimeZone = withTimeZoneMeta(payload);
+
   if (flags.jsonl) {
-    const records = Array.isArray(payload?.records) ? payload.records : Array.isArray(payload) ? payload : [];
+    const records = Array.isArray(payloadWithTimeZone?.records)
+      ? payloadWithTimeZone.records
+      : Array.isArray(payloadWithTimeZone)
+        ? payloadWithTimeZone
+        : [];
     const content = records.map((item) => JSON.stringify(item)).join("\n");
     if (flags.output) {
       await fs.writeFile(flags.output, `${content}${content ? "\n" : ""}`, "utf8");
@@ -410,9 +475,11 @@ async function writeOutput(payload, flags, textRenderer = null) {
     return;
   }
 
-  if (flags.json || typeof payload !== "string") {
+  if (flags.json || typeof payloadWithTimeZone !== "string") {
     const content =
-      typeof payload === "string" ? payload : `${JSON.stringify(payload, null, 2)}\n`;
+      typeof payloadWithTimeZone === "string"
+        ? payloadWithTimeZone
+        : `${JSON.stringify(payloadWithTimeZone, null, 2)}\n`;
     if (flags.output) {
       await fs.writeFile(flags.output, content, "utf8");
       console.log(`Wrote JSON to ${flags.output}`);
@@ -422,7 +489,7 @@ async function writeOutput(payload, flags, textRenderer = null) {
     return;
   }
 
-  const text = textRenderer ? textRenderer(payload) : String(payload);
+  const text = textRenderer ? textRenderer(payloadWithTimeZone) : String(payloadWithTimeZone);
   if (flags.output) {
     await fs.writeFile(flags.output, `${text}\n`, "utf8");
     console.log(`Wrote text to ${flags.output}`);
@@ -532,6 +599,9 @@ async function main() {
     process.exit(1);
   }
 
+  ACTIVE_TIME_ZONE = normalizeTimeZone(flags.tz ?? null);
+  process.env.TR_TIMEZONE = ACTIVE_TIME_ZONE;
+
   if (command === "help") {
     if (positionals[0]) {
       process.exit(printCommandHelp(positionals[0], flags));
@@ -550,6 +620,7 @@ async function main() {
   }
 
   const commandDeps = {
+    timeZone: ACTIVE_TIME_ZONE,
     resolveQueryContext,
     requirePrivateContext,
     applyAgentRecordFilters,
@@ -562,11 +633,14 @@ async function main() {
     normalizeDateOnlyInput,
     isoDateShift,
     filterFuturePlanned,
-    filterPastActivities,
+    filterPastActivities: (activities, fromDateIso, toDateIso) =>
+      filterPastActivities(activities, fromDateIso, toDateIso, ACTIVE_TIME_ZONE),
     sortByDateAsc,
     sortByDateDesc,
     toIsoDateFromPlanned,
     toIsoDate,
+    formatDateTime,
+    summarizeActivityTime,
     withClient,
     readPasswordFromStdin,
     normalizeFtpHistory,
@@ -594,6 +668,9 @@ async function main() {
     case "timeline":
       await commandTimeline(flags, commandDeps);
       return;
+    case "train-now":
+      await commandTrainNow(flags, commandDeps);
+      return;
     case "events":
       await commandEvents(flags, commandDeps);
       return;
@@ -630,6 +707,33 @@ async function main() {
     case "power-records":
       await commandPowerRecords(flags, commandDeps);
       return;
+    case "workout-library":
+      await commandWorkoutLibrary(flags, commandDeps);
+      return;
+    case "workout-recommend":
+      await commandWorkoutRecommend(flags, commandDeps);
+      return;
+    case "workout-details":
+      await commandWorkoutDetails(flags, commandDeps);
+      return;
+    case "add-workout":
+      await commandAddWorkout(flags, commandDeps);
+      return;
+    case "copy-workout":
+      await commandCopyWorkout(flags, commandDeps);
+      return;
+    case "workout-alternates":
+      await commandWorkoutAlternates(flags, commandDeps);
+      return;
+    case "move-workout":
+      await commandMoveWorkout(flags, commandDeps);
+      return;
+    case "replace-workout":
+      await commandReplaceWorkout(flags, commandDeps);
+      return;
+    case "switch-workout":
+      await commandSwitchWorkout(flags, commandDeps);
+      return;
     case "logout":
       await commandLogout(flags, commandDeps);
       return;
@@ -667,6 +771,9 @@ main().catch((error) => {
   if (message.includes('Invalid date "')) {
     console.error("Tip: expected date format is YYYY-MM-DD");
   }
+  if (message.includes('Invalid timezone "')) {
+    console.error("Tip: use an IANA timezone like America/New_York.");
+  }
   console.error('Run "trainerroad-cli help" or "trainerroad-cli help <command>" for usage.');
 
   if (process.env.TR_CLI_DEBUG === "1" && error?.stack) {

package/src/commands/discovery.mjs

@@ -30,6 +30,7 @@ export function buildDiscoveryPayload(level = 1, commandFilter = null) {
       "node src/cli.mjs capabilities --json",
       "node src/cli.mjs whoami --json",
       "node src/cli.mjs future --days 30 --json",
+      "node src/cli.mjs today --tz America/New_York --json",
       "node src/cli.mjs help future --json",
     ],
     commandCount: commandEntries.length,
@@ -152,6 +153,11 @@ export async function commandCapabilities(flags, deps) {
       outputOptions: AGENT_OUTPUT_OPTIONS,
     },
     outputModes: ["text", "json", "jsonl"],
+    timezone: {
+      flag: "--tz <IANA timezone>",
+      environment: "TR_TIMEZONE",
+      example: "America/New_York",
+    },
   };
 
   await writeOutput(payload, flags, () => {
@@ -160,6 +166,7 @@ export async function commandCapabilities(flags, deps) {
       "- Private mode (authenticated): full timeline + workout details.",
       "- Public mode (unauthenticated): day-level TSS/ride/planned signals + FTP history.",
       "- Commands support both via automatic mode selection and --target/--public flags.",
+      "- Timezone-aware date bucketing: use --tz or TR_TIMEZONE for local-day accuracy.",
     ].join("\n");
   });
 }

package/src/commands/train-now.mjs

@@ -0,0 +1,142 @@
+function stripHtml(value) {
+  return String(value ?? "")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&nbsp;/gi, " ")
+    .replace(/&amp;/gi, "&")
+    .replace(/&quot;/gi, '"')
+    .replace(/&#39;/gi, "'")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+const CATEGORY_NAME_MAP = {
+  climbing: "Climbing",
+  endurance: "Endurance",
+  attacking: "Attacking",
+};
+
+function normalizeCategoryName(value) {
+  const normalized = String(value ?? "").trim().toLowerCase();
+  return CATEGORY_NAME_MAP[normalized] ?? null;
+}
+
+function summarizeWorkoutInfo(info) {
+  if (!info || typeof info !== "object") return null;
+  return {
+    workoutId: info.id ?? null,
+    workoutName: info.name ?? null,
+    duration: info.duration ?? null,
+    durationMinutes:
+      Number.isFinite(Number(info.durationInSeconds)) ? Math.round(Number(info.durationInSeconds) / 60) : null,
+    tss: info.tss ?? null,
+    intensityFactor: info.intensityFactor ?? null,
+    energyKj: info.kj ?? null,
+    zoneId: info.progressionId ?? null,
+    progressionLevel: info.progressionLevel ?? null,
+    workoutDifficultyRating: info.workoutDifficultyRating ?? null,
+    isOutside: info.isOutside ?? null,
+    profileId: info.profileId ?? null,
+    imageUrl: info.picUrl ?? null,
+  };
+}
+
+function summarizeSuggestion(categoryName, suggestion, workoutInfo) {
+  return {
+    category: categoryName,
+    source: suggestion?.source ?? null,
+    workoutId: suggestion?.workoutId ?? workoutInfo?.workoutId ?? null,
+    ...workoutInfo,
+    predictionMetrics: suggestion?.predictionMetrics ?? {},
+  };
+}
+
+function flattenSuggestions(suggestions, workoutInfoById, categoryFilter = null) {
+  const categories = suggestions && typeof suggestions === "object" ? Object.entries(suggestions) : [];
+  const rows = [];
+  for (const [categoryName, items] of categories) {
+    if (categoryFilter && categoryName !== categoryFilter) continue;
+    for (const item of Array.isArray(items) ? items : []) {
+      rows.push(
+        summarizeSuggestion(
+          categoryName,
+          item,
+          workoutInfoById.get(Number(item?.workoutId)) ?? null,
+        ),
+      );
+    }
+  }
+  return rows;
+}
+
+async function requirePrivateMember(flags, deps) {
+  const { withClient } = deps;
+  const client = await withClient(flags);
+  try {
+    const memberInfo = await client.getMemberInfo();
+    return { client, memberInfo };
+  } catch {
+    throw new Error("train-now requires private authenticated mode. Login first with trainerroad-cli login.");
+  }
+}
+
+export async function commandTrainNow(flags, deps) {
+  const { isJsonMode, requirePositiveInteger, writeOutput } = deps;
+  const { client, memberInfo } = await requirePrivateMember(flags, deps);
+
+  const duration = requirePositiveInteger(flags.duration, 60);
+  const numSuggestions = requirePositiveInteger(flags["num-suggestions"], 10);
+  const categoryFilter = flags.category ? normalizeCategoryName(flags.category) : null;
+  if (flags.category && !categoryFilter) {
+    throw new Error('Invalid --category. Expected one of: climbing, endurance, attacking.');
+  }
+
+  const [status, suggestionsPayload] = await Promise.all([
+    client.getTrainNowStatus(memberInfo.username),
+    client.getTrainNowSuggestions({ duration, numSuggestions }, memberInfo.username),
+  ]);
+
+  const suggestionIds = Array.from(
+    new Set(
+      Object.values(suggestionsPayload?.suggestions ?? {})
+        .flatMap((items) => (Array.isArray(items) ? items : []))
+        .map((item) => Number(item?.workoutId))
+        .filter((value) => Number.isFinite(value)),
+    ),
+  );
+  const workoutInfo = await client.getWorkoutInformation(suggestionIds, memberInfo.username);
+  const workoutInfoById = new Map(
+    (Array.isArray(workoutInfo) ? workoutInfo : [])
+      .map((item) => [Number(item?.id), summarizeWorkoutInfo(item)])
+      .filter(([id]) => Number.isFinite(id)),
+  );
+
+  const records = flattenSuggestions(suggestionsPayload?.suggestions, workoutInfoById, categoryFilter);
+  const payload = {
+    generatedAt: new Date().toISOString(),
+    command: "train-now",
+    member: { memberId: memberInfo.memberId, username: memberInfo.username },
+    query: { duration, numSuggestions, category: categoryFilter },
+    status,
+    recommendedCategory: suggestionsPayload?.recommendedCategory ?? null,
+    hasRpePredictionServiceFailure: Boolean(suggestionsPayload?.hasRpePredictionServiceFailure),
+    count: records.length,
+    records,
+  };
+
+  if (!isJsonMode(flags)) {
+    await writeOutput(payload, flags, (value) => {
+      const lines = [
+        `TrainNow suggestions (${value.count}) duration=${value.query.duration}m`,
+      ];
+      for (const item of value.records) {
+        lines.push(
+          `- [${item.category}] ${item.workoutName ?? "(untitled)"} | workoutId=${item.workoutId} | duration=${item.durationMinutes ?? "?"}m | tss=${item.tss ?? "?"} | level=${item.progressionLevel ?? "?"}`,
+        );
+      }
+      return lines.join("\n");
+    });
+    return;
+  }
+
+  await writeOutput(payload, { ...flags, json: !flags.jsonl });
+}