trainerroad-cli 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.3.0 - 2026-03-25
+
+- Added richer command help with examples, required-flag metadata, and machine-readable help payloads.
+- Improved agent-facing failure messages so missing required flags fail fast with actionable retry guidance.
+- Added `--dry-run` previews for calendar mutation commands.
+- Made convergent mutation commands idempotent when the requested end state is already satisfied.
+- Fixed login default return-path handling so it follows the provided username.
+- Added automated tests covering CLI help/error behavior and write-command dry-run/no-op semantics.

package/README.md

@@ -27,6 +27,14 @@ It can also perform a small set of verified calendar writes for planned workouts
 - replace a workout with a specific alternate
 - switch a workout between inside and outside
 
+## Agent-Friendly Behavior
+
+- Non-interactive by default. Inputs are flags or stdin, not prompts.
+- Progressive disclosure. Use `trainerroad-cli help <command>` or `trainerroad-cli discover`.
+- Command help includes concrete examples and flag descriptions.
+- Write commands support `--dry-run` previews.
+- Common retry cases are idempotent no-ops instead of duplicate calendar writes.
+
 ## Install
 
 ### Run without install (npx)
@@ -82,6 +90,7 @@ trainerroad-cli workout-library --zone "Endurance" --profile "Sustained Power" -
 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 add-workout --workout-id 18128 --date 2026-03-16 --dry-run
 trainerroad-cli copy-workout --id <planned-activity-id> --date 2026-03-16 --json
 ```
 
@@ -97,6 +106,7 @@ 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 --dry-run
 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
@@ -130,6 +140,15 @@ Use `--target <username>` and/or `--public` for public mode queries.
 - `--records-only`: lighter record payloads
 - `--tz <IANA timezone>`: localize day boundaries/timestamps (defaults to `TR_TIMEZONE` or system timezone)
 
+## Help
+
+```bash
+trainerroad-cli help
+trainerroad-cli help future
+trainerroad-cli future --help
+trainerroad-cli help move-workout --json
+```
+
 ## Security
 
 - Session cookies are stored in `.trainerroad/session.json`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trainerroad-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Unofficial CLI for authenticating with TrainerRoad and querying timeline/workout data",
   "main": "src/cli.mjs",
   "bin": {
@@ -9,10 +9,12 @@
   },
   "files": [
     "src",
+    "CHANGELOG.md",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
+    "test": "node --test",
     "recon": "node scripts/recon.mjs",
     "cli": "node src/cli.mjs",
     "help": "node src/cli.mjs help",

package/src/cli.mjs

@@ -17,7 +17,9 @@ import {
   AGENT_FILTER_OPTIONS,
   AGENT_OUTPUT_OPTIONS,
   COMMAND_FLAG_ALLOWLIST,
+  COMMAND_REQUIRED_FLAGS,
   COMMANDS,
+  FLAG_DETAILS,
   FILTERABLE_COMMANDS,
   GLOBAL_NOTES,
   PROJECT_NOTICE,
@@ -66,25 +68,27 @@ function printGlobalHelp() {
   for (const note of GLOBAL_NOTES) console.log(`  - ${note}`);
   console.log("");
   console.log("Progressive disclosure:");
-  console.log("  node src/cli.mjs discover --level 1");
-  console.log("  node src/cli.mjs discover --level 2");
-  console.log("  node src/cli.mjs discover --command future --level 3 --json");
+  console.log("  trainerroad-cli discover --level 1");
+  console.log("  trainerroad-cli discover --level 2");
+  console.log("  trainerroad-cli discover --command future --level 3 --json");
+  console.log("");
+  console.log('Use "trainerroad-cli <command> --help" for command-specific options and examples.');
   console.log("");
   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");
+  console.log("  trainerroad-cli login --username quinnsprouse --password-stdin");
+  console.log("  trainerroad-cli future --days 30 --details --json");
+  console.log("  trainerroad-cli today --tz America/New_York --json");
+  console.log("  trainerroad-cli future --from 2026-03-01 --to 2026-03-31 --min-tss 60 --fields id,title,tss --jsonl");
+  console.log("  trainerroad-cli timeline --target quinnsprouse --public --json");
+  console.log("  trainerroad-cli ftp --target quinnsprouse --public --json");
+  console.log("  trainerroad-cli move-workout --id <planned-id> --to 2026-03-13 --dry-run");
+  console.log("  trainerroad-cli workout-alternates --id <planned-id> --category easier --json");
+  console.log('  trainerroad-cli workout-library --zone "Endurance" --profile "Sustained Power" --min-duration 45 --max-duration 75 --json');
+  console.log('  trainerroad-cli workout-recommend --zone "Endurance" --profile "Sustained Power" --target-duration 60 --target-level 1.0 --count 3 --json');
+  console.log("  trainerroad-cli train-now --duration 60 --json");
+  console.log("  trainerroad-cli workout-details --id 18128 --include-chart --json");
+  console.log("  trainerroad-cli add-workout --workout-id 18128 --date 2026-03-16 --dry-run");
+  console.log("  trainerroad-cli copy-workout --id <planned-id> --date 2026-03-16 --json");
 }
 
 function levenshteinDistance(left, right) {
@@ -197,6 +201,45 @@ function validateCommandFlags(command, flags) {
   return { unknownFlags, allowlist: Array.from(allowlist) };
 }
 
+function formatFlagLabel(name) {
+  const detail = FLAG_DETAILS[name] ?? {};
+  return `--${name}${detail.placeholder ? ` ${detail.placeholder}` : ""}`;
+}
+
+function getCommandHelpOptions(command) {
+  const allowlist = Array.from(COMMAND_FLAG_ALLOWLIST[command] ?? []);
+  const requiredFlags = new Set(COMMAND_REQUIRED_FLAGS[command] ?? []);
+  return allowlist.map((name) => ({
+    name,
+    label: formatFlagLabel(name),
+    description: FLAG_DETAILS[name]?.description ?? "No description available.",
+    required: requiredFlags.has(name),
+  }));
+}
+
+function formatMissingRequiredFlagMessage(command, flagName) {
+  const def = COMMANDS[command];
+  const requiredFlags = (COMMAND_REQUIRED_FLAGS[command] ?? []).map((name) => `--${name}`);
+  const usageLines = Array.isArray(def?.usage) ? def.usage : [];
+  const exampleLines = Array.isArray(def?.examples) ? def.examples : [];
+  const lines = [`Missing required flag --${flagName} for "trainerroad-cli ${command}".`];
+
+  if (requiredFlags.length > 0) {
+    lines.push("", `Required flags: ${requiredFlags.join(", ")}`);
+  }
+  if (usageLines.length > 0) {
+    lines.push("", "Usage:");
+    for (const line of usageLines) lines.push(`  ${line}`);
+  }
+  if (exampleLines.length > 0) {
+    lines.push("", "Examples:");
+    for (const line of exampleLines) lines.push(`  ${line}`);
+  }
+
+  lines.push("", `Run "trainerroad-cli help ${command}" for more detail.`);
+  return lines.join("\n");
+}
+
 function printCommandHelp(command, flags = {}) {
   const def = COMMANDS[command];
   if (!def) {
@@ -204,11 +247,16 @@ function printCommandHelp(command, flags = {}) {
     return 1;
   }
   if (flags.json) {
+    const options = getCommandHelpOptions(command);
     const payload = {
       command,
       summary: def.summary,
       usage: def.usage,
-      timezoneOption: "--tz <IANA timezone> (defaults to TR_TIMEZONE or system timezone)",
+      examples: def.examples ?? [],
+      options,
+      requiredFlags: options.filter((option) => option.required).map((option) => option.name),
+      nonInteractive: true,
+      supportsDryRun: options.some((option) => option.name === "dry-run"),
       supportsAgentFilters: FILTERABLE_COMMANDS.has(command),
       agentFilterOptions: FILTERABLE_COMMANDS.has(command) ? AGENT_FILTER_OPTIONS : [],
       agentOutputOptions: FILTERABLE_COMMANDS.has(command) ? AGENT_OUTPUT_OPTIONS : [],
@@ -225,18 +273,15 @@ function printCommandHelp(command, flags = {}) {
   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("Options:");
+  for (const option of getCommandHelpOptions(command)) {
+    const suffix = option.required ? " [required]" : "";
+    console.log(`  ${option.label.padEnd(34)} ${option.description}${suffix}`);
+  }
+  if (Array.isArray(def.examples) && def.examples.length > 0) {
     console.log("");
-    console.log("Agent filters:");
-    for (const option of AGENT_FILTER_OPTIONS) {
-      console.log(`  ${option.flag.padEnd(14)} ${option.description}`);
-    }
-    console.log("Agent output options:");
-    for (const option of AGENT_OUTPUT_OPTIONS) {
-      console.log(`  ${option.flag.padEnd(14)} ${option.description}`);
-    }
+    console.log("Examples:");
+    for (const line of def.examples) console.log(`  ${line}`);
   }
   return 0;
 }
@@ -643,6 +688,13 @@ async function main() {
     summarizeActivityTime,
     withClient,
     readPasswordFromStdin,
+    requireFlag: (commandName, incomingFlags, flagName) => {
+      const value = incomingFlags[flagName];
+      if (value === undefined || value === null || value === "") {
+        throw new Error(formatMissingRequiredFlagMessage(commandName, flagName));
+      }
+      return value;
+    },
     normalizeFtpHistory,
     getLastItem,
     normalizeFitnessThresholds,

package/src/commands/auth.mjs

@@ -1,14 +1,15 @@
 export async function commandLogin(flags, deps) {
   const { withClient, readPasswordFromStdin, writeOutput } = deps;
   const client = await withClient(flags);
+  const username = flags.username ?? process.env.TR_USERNAME ?? null;
   const password =
     flags["password-stdin"]
       ? await readPasswordFromStdin()
       : flags.password ?? process.env.TR_PASSWORD ?? null;
   const result = await client.login({
-    username: flags.username ?? process.env.TR_USERNAME ?? null,
+    username,
     password,
-    returnPath: flags["return-path"] ?? "/app/career/quinnsprouse",
+    returnPath: flags["return-path"] ?? (username ? `/app/career/${username}` : "/app/career"),
   });
   await writeOutput(result, { ...flags, json: true });
 }

package/src/commands/discovery.mjs

@@ -12,6 +12,7 @@ export function buildDiscoveryPayload(level = 1, commandFilter = null) {
       name,
       summary: def.summary,
       usage: level >= 2 ? def.usage : undefined,
+      examples: level >= 2 ? def.examples : undefined,
       supportsAgentFilters: FILTERABLE_COMMANDS.has(name),
       agentFilters: level >= 3 && FILTERABLE_COMMANDS.has(name) ? AGENT_FILTER_OPTIONS : undefined,
       agentOutputOptions:
@@ -27,11 +28,11 @@ export function buildDiscoveryPayload(level = 1, commandFilter = null) {
       level3: "Apply --from/--to/--type/--contains/--min-tss/--max-tss/--sort/--result-limit/--fields.",
     },
     firstSteps: [
-      "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",
+      "trainerroad-cli capabilities --json",
+      "trainerroad-cli whoami --json",
+      "trainerroad-cli future --days 30 --json",
+      "trainerroad-cli today --tz America/New_York --json",
+      "trainerroad-cli help future --json",
     ],
     commandCount: commandEntries.length,
     commands: commandEntries,
@@ -42,17 +43,17 @@ export function buildDiscoveryPayload(level = 1, commandFilter = null) {
       {
         pattern: "Summarize future workouts in a date window",
         command:
-          "node src/cli.mjs future --from 2026-03-01 --to 2026-03-31 --fields id,title,tss,date --sort date --json",
+          "trainerroad-cli future --from 2026-03-01 --to 2026-03-31 --fields id,title,tss,date --sort date --json",
       },
       {
         pattern: "Find hard completed rides",
         command:
-          "node src/cli.mjs past --days 90 --details --min-tss 80 --sort tss-desc --result-limit 20 --jsonl",
+          "trainerroad-cli past --days 90 --details --min-tss 80 --sort tss-desc --result-limit 20 --jsonl",
       },
       {
         pattern: "Extract only fields for downstream tools",
         command:
-          "node src/cli.mjs today --details --fields recordType,name,started,tss --json",
+          "trainerroad-cli today --details --fields recordType,name,started,tss --json",
       },
     ];
   }

package/src/commands/workout-mutations.mjs

@@ -1,14 +1,6 @@
 const ALTERNATE_CATEGORIES = new Set(["similar", "easier", "harder", "longer", "shorter"]);
 const SWITCH_MODES = new Set(["inside", "outside"]);
 
-function requireFlag(flags, name) {
-  const value = flags[name];
-  if (value === undefined || value === null || value === "") {
-    throw new Error(`Missing required flag --${name}.`);
-  }
-  return value;
-}
-
 function toIsoDateFromApiDate(date) {
   if (!date || typeof date !== "object") return null;
   const year = String(date.year ?? "").padStart(4, "0");
@@ -69,18 +61,10 @@ async function requirePrivateMember(flags, deps) {
   return { client, memberInfo };
 }
 
-async function fetchBeforeAfter(flags, deps, mutate) {
-  const { client, memberInfo } = await requirePrivateMember(flags, deps);
-  const plannedActivityId = String(requireFlag(flags, "id"));
-  const before = await client.getPlannedActivity(plannedActivityId, memberInfo.username);
-  const mutation = await mutate({ client, memberInfo, plannedActivityId, before });
-  const after = await client.getPlannedActivity(plannedActivityId, memberInfo.username);
-  return { client, memberInfo, plannedActivityId, before, after, mutation };
-}
-
 export async function commandWorkoutAlternates(flags, deps) {
-  const { isJsonMode, writeOutput } = deps;
+  const { isJsonMode, requireFlag, writeOutput } = deps;
   const category = String(flags.category ?? "similar").toLowerCase();
+  const plannedActivityId = String(requireFlag("workout-alternates", flags, "id"));
   if (!ALTERNATE_CATEGORIES.has(category)) {
     throw new Error(
       `Invalid --category "${category}". Expected one of: ${Array.from(ALTERNATE_CATEGORIES).join(", ")}.`,
@@ -88,7 +72,6 @@ export async function commandWorkoutAlternates(flags, deps) {
   }
 
   const { client, memberInfo } = await requirePrivateMember(flags, deps);
-  const plannedActivityId = String(requireFlag(flags, "id"));
   const plannedActivity = await client.getPlannedActivity(plannedActivityId, memberInfo.username);
   const alternates = await client.getPlannedActivityAlternates(
     plannedActivityId,
@@ -128,14 +111,47 @@ export async function commandWorkoutAlternates(flags, deps) {
 }
 
 export async function commandMoveWorkout(flags, deps) {
-  const { isJsonMode, writeOutput } = deps;
-  const newDate = String(requireFlag(flags, "to"));
-  const { memberInfo, plannedActivityId, before, after, mutation } = await fetchBeforeAfter(
-    flags,
-    deps,
-    async ({ client, memberInfo, plannedActivityId }) =>
-      client.movePlannedActivity(plannedActivityId, newDate, memberInfo.username),
-  );
+  const { isJsonMode, requireFlag, toBoolean, writeOutput } = deps;
+  const dryRun = toBoolean(flags["dry-run"], false);
+  const plannedActivityId = String(requireFlag("move-workout", flags, "id"));
+  const newDate = String(requireFlag("move-workout", flags, "to"));
+  const { client, memberInfo } = await requirePrivateMember(flags, deps);
+  const before = await client.getPlannedActivity(plannedActivityId, memberInfo.username);
+  const beforeSummary = summarizePlannedActivity(before);
+  const noop = beforeSummary?.date === newDate;
+
+  if (dryRun || noop) {
+    const payload = {
+      generatedAt: new Date().toISOString(),
+      command: "move-workout",
+      member: { memberId: memberInfo.memberId, username: memberInfo.username },
+      query: { plannedActivityId, to: newDate },
+      dryRun,
+      noop,
+      before: beforeSummary,
+      after: noop ? beforeSummary : { ...beforeSummary, date: newDate },
+      mutation: null,
+      message: noop
+        ? `Workout is already scheduled on ${newDate}.`
+        : `Would move ${beforeSummary?.workoutName ?? "workout"} to ${newDate}.`,
+    };
+
+    if (!isJsonMode(flags)) {
+      await writeOutput(payload, flags, (value) => {
+        if (value.noop) {
+          return `No changes: plannedActivityId=${value.query.plannedActivityId} is already on ${value.query.to}`;
+        }
+        return `Would move ${value.before?.workoutName ?? "workout"} | plannedActivityId=${value.query.plannedActivityId} | ${value.before?.date ?? "?"} -> ${value.query.to}\nNo changes made.`;
+      });
+      return;
+    }
+
+    await writeOutput(payload, { ...flags, json: !flags.jsonl });
+    return;
+  }
+
+  const mutation = await client.movePlannedActivity(plannedActivityId, newDate, memberInfo.username);
+  const after = await client.getPlannedActivity(plannedActivityId, memberInfo.username);
 
   const payload = {
     generatedAt: new Date().toISOString(),
@@ -158,22 +174,54 @@ export async function commandMoveWorkout(flags, deps) {
 }
 
 export async function commandReplaceWorkout(flags, deps) {
-  const { isJsonMode, toBoolean, writeOutput } = deps;
-  const alternateWorkoutId = Number(requireFlag(flags, "alternate-id"));
+  const { isJsonMode, requireFlag, toBoolean, writeOutput } = deps;
+  const dryRun = toBoolean(flags["dry-run"], false);
+  const plannedActivityId = String(requireFlag("replace-workout", flags, "id"));
+  const alternateWorkoutId = Number(requireFlag("replace-workout", flags, "alternate-id"));
   if (!Number.isFinite(alternateWorkoutId)) {
     throw new Error(`Invalid --alternate-id "${flags["alternate-id"]}". Expected a numeric workout ID.`);
   }
   const updateDuration = toBoolean(flags["update-duration"], false);
+  const { client, memberInfo } = await requirePrivateMember(flags, deps);
+  const before = await client.getPlannedActivity(plannedActivityId, memberInfo.username);
+  const beforeSummary = summarizePlannedActivity(before);
+  const noop = Number(beforeSummary?.workoutId) === alternateWorkoutId;
 
-  const { memberInfo, plannedActivityId, before, after, mutation } = await fetchBeforeAfter(
-    flags,
-    deps,
-    async ({ client, memberInfo, plannedActivityId }) =>
-      client.replacePlannedActivityWithAlternate(plannedActivityId, alternateWorkoutId, {
-        updateDuration,
-        usernameForReferer: memberInfo.username,
-      }),
-  );
+  if (dryRun || noop) {
+    const payload = {
+      generatedAt: new Date().toISOString(),
+      command: "replace-workout",
+      member: { memberId: memberInfo.memberId, username: memberInfo.username },
+      query: { plannedActivityId, alternateWorkoutId, updateDuration },
+      dryRun,
+      noop,
+      before: beforeSummary,
+      after: noop ? beforeSummary : null,
+      mutation: null,
+      message: noop
+        ? `Workout already uses alternate workout ${alternateWorkoutId}.`
+        : `Would replace workout ${beforeSummary?.workoutId ?? "?"} with ${alternateWorkoutId}.`,
+    };
+
+    if (!isJsonMode(flags)) {
+      await writeOutput(payload, flags, (value) => {
+        if (value.noop) {
+          return `No changes: plannedActivityId=${value.query.plannedActivityId} already uses workoutId=${value.query.alternateWorkoutId}`;
+        }
+        return `Would replace workout | plannedActivityId=${value.query.plannedActivityId} | workoutId=${value.before?.workoutId ?? "?"} -> alternateWorkoutId=${value.query.alternateWorkoutId}\nNo changes made.`;
+      });
+      return;
+    }
+
+    await writeOutput(payload, { ...flags, json: !flags.jsonl });
+    return;
+  }
+
+  const mutation = await client.replacePlannedActivityWithAlternate(plannedActivityId, alternateWorkoutId, {
+    updateDuration,
+    usernameForReferer: memberInfo.username,
+  });
+  const after = await client.getPlannedActivity(plannedActivityId, memberInfo.username);
 
   const payload = {
     generatedAt: new Date().toISOString(),
@@ -196,18 +244,50 @@ export async function commandReplaceWorkout(flags, deps) {
 }
 
 export async function commandSwitchWorkout(flags, deps) {
-  const { isJsonMode, writeOutput } = deps;
-  const mode = String(requireFlag(flags, "mode")).toLowerCase();
+  const { isJsonMode, requireFlag, toBoolean, writeOutput } = deps;
+  const dryRun = toBoolean(flags["dry-run"], false);
+  const plannedActivityId = String(requireFlag("switch-workout", flags, "id"));
+  const mode = String(requireFlag("switch-workout", flags, "mode")).toLowerCase();
   if (!SWITCH_MODES.has(mode)) {
     throw new Error(`Invalid --mode "${mode}". Expected one of: ${Array.from(SWITCH_MODES).join(", ")}.`);
   }
+  const { client, memberInfo } = await requirePrivateMember(flags, deps);
+  const before = await client.getPlannedActivity(plannedActivityId, memberInfo.username);
+  const beforeSummary = summarizePlannedActivity(before);
+  const noop = beforeSummary?.isOutside === (mode === "outside");
 
-  const { memberInfo, plannedActivityId, before, after, mutation } = await fetchBeforeAfter(
-    flags,
-    deps,
-    async ({ client, memberInfo, plannedActivityId }) =>
-      client.switchPlannedActivityMode(plannedActivityId, mode, memberInfo.username),
-  );
+  if (dryRun || noop) {
+    const payload = {
+      generatedAt: new Date().toISOString(),
+      command: "switch-workout",
+      member: { memberId: memberInfo.memberId, username: memberInfo.username },
+      query: { plannedActivityId, mode },
+      dryRun,
+      noop,
+      before: beforeSummary,
+      after: noop ? beforeSummary : { ...beforeSummary, isOutside: mode === "outside" },
+      mutation: null,
+      message: noop
+        ? `Workout is already in ${mode} mode.`
+        : `Would switch workout to ${mode} mode.`,
+    };
+
+    if (!isJsonMode(flags)) {
+      await writeOutput(payload, flags, (value) => {
+        if (value.noop) {
+          return `No changes: plannedActivityId=${value.query.plannedActivityId} is already ${value.query.mode}`;
+        }
+        return `Would switch workout | plannedActivityId=${value.query.plannedActivityId} | outside=${value.before?.isOutside} -> ${value.query.mode === "outside"}\nNo changes made.`;
+      });
+      return;
+    }
+
+    await writeOutput(payload, { ...flags, json: !flags.jsonl });
+    return;
+  }
+
+  const mutation = await client.switchPlannedActivityMode(plannedActivityId, mode, memberInfo.username);
+  const after = await client.getPlannedActivity(plannedActivityId, memberInfo.username);
 
   const payload = {
     generatedAt: new Date().toISOString(),

package/src/commands/workout-tools.mjs

@@ -100,14 +100,6 @@ function summarizeChart(chartData, pointLimit = 200) {
   };
 }
 
-function requireFlag(flags, name) {
-  const value = flags[name];
-  if (value === undefined || value === null || value === "") {
-    throw new Error(`Missing required flag --${name}.`);
-  }
-  return value;
-}
-
 async function requirePrivateMember(flags, deps) {
   const { withClient } = deps;
   const client = await withClient(flags);
@@ -125,30 +117,6 @@ async function sleep(ms) {
   await new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-async function findPlannedWorkoutOnDate(client, memberInfo, dateIso, workoutId) {
-  const timeline = await client.getTimeline(memberInfo.memberId, memberInfo.username);
-  const candidateIds = (Array.isArray(timeline?.plannedActivities) ? timeline.plannedActivities : [])
-    .filter((item) => {
-      const date = item?.date;
-      const asIso = date
-        ? `${String(date.year).padStart(4, "0")}-${String(date.month).padStart(2, "0")}-${String(date.day).padStart(2, "0")}`
-        : null;
-      return asIso === dateIso;
-    })
-    .map((item) => item.id)
-    .filter(Boolean);
-
-  if (candidateIds.length === 0) return null;
-  const details = await client.getPlannedActivitiesByIds(
-    memberInfo.memberId,
-    memberInfo.username,
-    candidateIds,
-  );
-  const matches = details.filter((item) => Number(item?.workout?.id) === Number(workoutId));
-  if (matches.length === 0) return null;
-  return matches.sort((a, b) => String(b.modified ?? "").localeCompare(String(a.modified ?? "")))[0];
-}
-
 async function listPlannedWorkoutsOnDate(client, memberInfo, dateIso) {
   const timeline = await client.getTimeline(memberInfo.memberId, memberInfo.username);
   const candidateIds = (Array.isArray(timeline?.plannedActivities) ? timeline.plannedActivities : [])
@@ -167,8 +135,8 @@ async function listPlannedWorkoutsOnDate(client, memberInfo, dateIso) {
 }
 
 export async function commandWorkoutDetails(flags, deps) {
-  const { isJsonMode, requirePositiveInteger, toBoolean, writeOutput } = deps;
-  const workoutId = Number(requireFlag(flags, "id"));
+  const { isJsonMode, requireFlag, requirePositiveInteger, toBoolean, writeOutput } = deps;
+  const workoutId = Number(requireFlag("workout-details", flags, "id"));
   if (!Number.isFinite(workoutId)) {
     throw new Error(`Invalid --id "${flags.id}". Expected a numeric workout ID.`);
   }
@@ -217,9 +185,10 @@ export async function commandWorkoutDetails(flags, deps) {
 }
 
 export async function commandAddWorkout(flags, deps) {
-  const { isJsonMode, toBoolean, writeOutput } = deps;
-  const workoutId = Number(requireFlag(flags, "workout-id"));
-  const dateIso = String(requireFlag(flags, "date"));
+  const { isJsonMode, requireFlag, toBoolean, writeOutput } = deps;
+  const dryRun = toBoolean(flags["dry-run"], false);
+  const workoutId = Number(requireFlag("add-workout", flags, "workout-id"));
+  const dateIso = String(requireFlag("add-workout", flags, "date"));
   if (!Number.isFinite(workoutId)) {
     throw new Error(`Invalid --workout-id "${flags["workout-id"]}". Expected a numeric workout ID.`);
   }
@@ -232,6 +201,54 @@ export async function commandAddWorkout(flags, deps) {
     throw new Error(`Workout ${workoutId} was not found in the library.`);
   }
 
+  const existingOnDate = await listPlannedWorkoutsOnDate(client, memberInfo, dateIso);
+  const beforeIds = new Set(existingOnDate.map((item) => item.id));
+  const matchingExisting = existingOnDate
+    .filter((item) => {
+      const plannedWorkoutId = Number(item?.workout?.id);
+      const plannedOutside = item?.workout?.isOutside;
+      return plannedWorkoutId === workoutId && (plannedOutside == null || plannedOutside === outside);
+    })
+    .map((item) => summarizePlannedActivity(item))
+    .filter(Boolean);
+
+  if (dryRun) {
+    const payload = {
+      generatedAt: new Date().toISOString(),
+      command: "add-workout",
+      member: { memberId: memberInfo.memberId, username: memberInfo.username },
+      query: { workoutId, date: dateIso, outside },
+      dryRun,
+      noop: false,
+      workout,
+      existingMatches: matchingExisting,
+      created: null,
+      attempts: [],
+      warnings:
+        matchingExisting.length > 0
+          ? [`Found ${matchingExisting.length} matching workout(s) already scheduled on ${dateIso}.`]
+          : [],
+      message: `Would add workout ${workoutId} to ${dateIso}.`,
+    };
+
+    if (!isJsonMode(flags)) {
+      await writeOutput(payload, flags, (value) => {
+        const lines = [
+          `Would add ${value.workout?.workoutName ?? "workout"} to ${value.query.date} | workoutId=${value.query.workoutId}`,
+        ];
+        if (value.warnings.length > 0) {
+          lines.push(...value.warnings.map((warning) => `Warning: ${warning}`));
+        }
+        lines.push("No changes made.");
+        return lines.join("\n");
+      });
+      return;
+    }
+
+    await writeOutput(payload, { ...flags, json: !flags.jsonl });
+    return;
+  }
+
   const attempts = await client.tryAddWorkoutToCalendar(workoutId, dateIso, {
     outside,
     usernameForReferer: memberInfo.username,
@@ -239,7 +256,10 @@ export async function commandAddWorkout(flags, deps) {
 
   let created = null;
   for (let attempt = 0; attempt < 4; attempt += 1) {
-    created = await findPlannedWorkoutOnDate(client, memberInfo, dateIso, workoutId);
+    const afterTarget = await listPlannedWorkoutsOnDate(client, memberInfo, dateIso);
+    created = afterTarget.find(
+      (item) => !beforeIds.has(item.id) && Number(item?.workout?.id) === Number(workoutId),
+    );
     if (created) break;
     await sleep(750);
   }
@@ -277,13 +297,55 @@ export async function commandAddWorkout(flags, deps) {
 }
 
 export async function commandCopyWorkout(flags, deps) {
-  const { isJsonMode, writeOutput } = deps;
-  const sourcePlannedActivityId = String(requireFlag(flags, "id"));
-  const targetDate = String(requireFlag(flags, "date"));
+  const { isJsonMode, requireFlag, toBoolean, writeOutput } = deps;
+  const dryRun = toBoolean(flags["dry-run"], false);
+  const sourcePlannedActivityId = String(requireFlag("copy-workout", flags, "id"));
+  const targetDate = String(requireFlag("copy-workout", flags, "date"));
   const { client, memberInfo } = await requirePrivateMember(flags, deps);
   const source = await client.getPlannedActivity(sourcePlannedActivityId, memberInfo.username);
   const beforeTarget = await listPlannedWorkoutsOnDate(client, memberInfo, targetDate);
   const beforeIds = new Set(beforeTarget.map((item) => item.id));
+  const matchingExisting = beforeTarget
+    .filter((item) => Number(item?.workout?.id) === Number(source?.workout?.id))
+    .map((item) => summarizePlannedActivity(item))
+    .filter(Boolean);
+
+  if (dryRun) {
+    const payload = {
+      generatedAt: new Date().toISOString(),
+      command: "copy-workout",
+      member: { memberId: memberInfo.memberId, username: memberInfo.username },
+      query: { sourcePlannedActivityId, date: targetDate },
+      dryRun,
+      noop: false,
+      source: summarizePlannedActivity(source),
+      existingMatches: matchingExisting,
+      created: null,
+      mutation: null,
+      warnings:
+        matchingExisting.length > 0
+          ? [`Found ${matchingExisting.length} matching workout(s) already scheduled on ${targetDate}.`]
+          : [],
+      message: `Would copy workout to ${targetDate}.`,
+    };
+
+    if (!isJsonMode(flags)) {
+      await writeOutput(payload, flags, (value) => {
+        const lines = [
+          `Would copy ${value.source?.workoutName ?? "workout"} to ${value.query.date} | sourcePlannedActivityId=${value.query.sourcePlannedActivityId}`,
+        ];
+        if (value.warnings.length > 0) {
+          lines.push(...value.warnings.map((warning) => `Warning: ${warning}`));
+        }
+        lines.push("No changes made.");
+        return lines.join("\n");
+      });
+      return;
+    }
+
+    await writeOutput(payload, { ...flags, json: !flags.jsonl });
+    return;
+  }
 
   const mutation = await client.copyPlannedActivity(sourcePlannedActivityId, targetDate, memberInfo.username);
 

package/src/lib/command-manifest.mjs

@@ -2,172 +2,272 @@ export const COMMANDS = {
   help: {
     summary: "Show global help or command help.",
     usage: [
-      "node src/cli.mjs help",
-      "node src/cli.mjs help <command>",
-      "node src/cli.mjs <command> --help",
+      "trainerroad-cli help",
+      "trainerroad-cli help <command>",
+      "trainerroad-cli <command> --help",
+    ],
+    examples: [
+      "trainerroad-cli help future",
+      "trainerroad-cli help future --json",
     ],
   },
   discover: {
     summary: "Agent-oriented command discovery with progressive disclosure levels.",
     usage: [
-      "node src/cli.mjs discover",
-      "node src/cli.mjs discover --level 1|2|3 [--json]",
-      "node src/cli.mjs discover --command future --level 3 --json",
+      "trainerroad-cli discover",
+      "trainerroad-cli discover --level 1|2|3 [--json]",
+      "trainerroad-cli discover --command future --level 3 --json",
+    ],
+    examples: [
+      "trainerroad-cli discover --level 1",
+      "trainerroad-cli discover --command workout-library --level 3 --json",
     ],
   },
   capabilities: {
     summary: "Show supported auth/data capabilities (private + public modes).",
-    usage: ["node src/cli.mjs capabilities [--json]"],
+    usage: ["trainerroad-cli capabilities [--json]"],
+    examples: ["trainerroad-cli capabilities --json"],
   },
   login: {
     summary: "Authenticate and persist cookie session for private data access.",
     usage: [
-      "node src/cli.mjs login --username <u> --password <p> [--return-path /app/career/<username>]",
-      "node src/cli.mjs login --username <u> --password-stdin",
+      "trainerroad-cli login --username <username> --password <password> [--return-path /app/career/<username>]",
+      "trainerroad-cli login --username <username> --password-stdin",
+    ],
+    examples: [
+      "trainerroad-cli login --username quinnsprouse --password-stdin",
+      "TR_PASSWORD='<password>' trainerroad-cli login --username quinnsprouse",
     ],
   },
   whoami: {
     summary: "Fetch authenticated member profile info (`/app/api/member-info`).",
-    usage: ["node src/cli.mjs whoami [--json]"],
+    usage: ["trainerroad-cli whoami [--json]"],
+    examples: ["trainerroad-cli whoami --json"],
   },
   timeline: {
     summary: "Get profile summary (private full timeline or public TSS-derived summary).",
     usage: [
-      "node src/cli.mjs timeline [--target <username>] [--public] [--full] [--json]",
-      "node src/cli.mjs timeline --target quinnsprouse --public --json",
+      "trainerroad-cli timeline [--target <username>] [--public] [--full] [--json]",
+    ],
+    examples: [
+      "trainerroad-cli timeline --json",
+      "trainerroad-cli timeline --target quinnsprouse --public --json",
     ],
   },
   "train-now": {
     summary: "Fetch TrainerRoad AI suggested workouts (TrainNow) for a target duration (private mode).",
     usage: [
-      "node src/cli.mjs train-now [--duration <minutes>] [--num-suggestions <n>] [--category climbing|endurance|attacking] [--json|--jsonl]",
+      "trainerroad-cli train-now [--duration <minutes>] [--num-suggestions <count>] [--category climbing|endurance|attacking] [--json|--jsonl]",
+    ],
+    examples: [
+      "trainerroad-cli train-now --duration 60 --json",
+      "trainerroad-cli train-now --duration 90 --category endurance --json",
     ],
   },
   events: {
     summary: "Show calendar events/races from timeline (private mode).",
     usage: [
-      "node src/cli.mjs events [--full] [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--type <value>] [--contains <text>] [--min-tss <n>] [--max-tss <n>] [--sort date|date-desc|name|name-desc|tss|tss-desc] [--result-limit <n>] [--fields a,b] [--records-only] [--json|--jsonl]",
+      "trainerroad-cli events [--full] [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--type <value>] [--contains <text>] [--min-tss <number>] [--max-tss <number>] [--sort date|date-desc|name|name-desc|tss|tss-desc] [--result-limit <count>] [--fields a,b] [--records-only] [--json|--jsonl]",
+    ],
+    examples: [
+      "trainerroad-cli events --from 2026-03-01 --to 2026-03-31 --json",
+      "trainerroad-cli events --contains gravel --sort date --result-limit 10 --json",
     ],
   },
   annotations: {
     summary: "Show timeline annotations (time off, notes, illness/injury markers) (private mode).",
     usage: [
-      "node src/cli.mjs annotations [--full] [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--type <value>] [--contains <text>] [--sort date|date-desc|name|name-desc] [--result-limit <n>] [--fields a,b] [--records-only] [--json|--jsonl]",
+      "trainerroad-cli annotations [--full] [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--type <value>] [--contains <text>] [--sort date|date-desc|name|name-desc] [--result-limit <count>] [--fields a,b] [--records-only] [--json|--jsonl]",
+    ],
+    examples: [
+      "trainerroad-cli annotations --from 2026-01-01 --json",
+      "trainerroad-cli annotations --contains injury --sort date-desc --json",
     ],
   },
   levels: {
     summary: "Show progression levels by zone (private mode).",
     usage: [
-      "node src/cli.mjs levels [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--type <zone|progressionId>] [--contains <text>] [--sort name|name-desc|date|date-desc] [--result-limit <n>] [--fields a,b] [--records-only] [--json|--jsonl]",
+      "trainerroad-cli levels [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--type <zone|progressionId>] [--contains <text>] [--sort name|name-desc|date|date-desc] [--result-limit <count>] [--fields a,b] [--records-only] [--json|--jsonl]",
+    ],
+    examples: [
+      "trainerroad-cli levels --json",
+      "trainerroad-cli levels --type endurance --json",
     ],
   },
   plan: {
     summary: "Show training plan data (current plan, phases, or all plans) (private mode).",
     usage: [
-      "node src/cli.mjs plan [--view current|phases|plans] [--full] [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--type <value>] [--contains <text>] [--sort date|date-desc|name|name-desc] [--result-limit <n>] [--fields a,b] [--records-only] [--json|--jsonl]",
+      "trainerroad-cli plan [--view current|phases|plans] [--full] [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--type <value>] [--contains <text>] [--sort date|date-desc|name|name-desc] [--result-limit <count>] [--fields a,b] [--records-only] [--json|--jsonl]",
+    ],
+    examples: [
+      "trainerroad-cli plan --view current --json",
+      "trainerroad-cli plan --view phases --json",
     ],
   },
   "weight-history": {
     summary: "Show historical body-weight entries (private mode).",
     usage: [
-      "node src/cli.mjs weight-history [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--contains <text>] [--sort date|date-desc] [--result-limit <n>] [--fields a,b] [--records-only] [--json|--jsonl]",
+      "trainerroad-cli weight-history [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--contains <text>] [--sort date|date-desc] [--result-limit <count>] [--fields a,b] [--records-only] [--json|--jsonl]",
+    ],
+    examples: [
+      "trainerroad-cli weight-history --json",
+      "trainerroad-cli weight-history --from 2026-01-01 --sort date-desc --json",
     ],
   },
   today: {
     summary: "Show today's planned/completed activity for private or public profile mode.",
     usage: [
-      "node src/cli.mjs today [--date YYYY-MM-DD] [--target <username>] [--public] [--details] [--type <value>] [--contains <text>] [--min-tss <n>] [--max-tss <n>] [--sort date|date-desc|tss|tss-desc] [--result-limit <n>] [--fields a,b] [--records-only] [--json|--jsonl]",
+      "trainerroad-cli today [--date YYYY-MM-DD] [--target <username>] [--public] [--details] [--type <value>] [--contains <text>] [--min-tss <number>] [--max-tss <number>] [--sort date|date-desc|tss|tss-desc] [--result-limit <count>] [--fields a,b] [--records-only] [--json|--jsonl]",
+    ],
+    examples: [
+      "trainerroad-cli today --json",
+      "trainerroad-cli today --target quinnsprouse --public --tz America/New_York --json",
     ],
   },
   future: {
     summary: "Show future plan data for private or public profile mode.",
     usage: [
-      "node src/cli.mjs future [--days <n>] [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--target <username>] [--public] [--details] [--type <value>] [--contains <text>] [--min-tss <n>] [--max-tss <n>] [--sort date|date-desc|tss|tss-desc] [--result-limit <n>] [--fields a,b] [--records-only] [--json|--jsonl]",
+      "trainerroad-cli future [--days <count>] [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--target <username>] [--public] [--details] [--type <value>] [--contains <text>] [--min-tss <number>] [--max-tss <number>] [--sort date|date-desc|tss|tss-desc] [--result-limit <count>] [--fields a,b] [--records-only] [--json|--jsonl]",
+    ],
+    examples: [
+      "trainerroad-cli future --days 30 --json",
+      "trainerroad-cli future --from 2026-03-01 --to 2026-03-31 --fields id,title,tss,date --json",
     ],
   },
   past: {
     summary: "Show past activity data for private or public profile mode.",
     usage: [
-      "node src/cli.mjs past [--days <n>] [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--limit <n>] [--target <username>] [--public] [--details] [--type <value>] [--contains <text>] [--min-tss <n>] [--max-tss <n>] [--sort date|date-desc|tss|tss-desc] [--result-limit <n>] [--fields a,b] [--records-only] [--json|--jsonl]",
+      "trainerroad-cli past [--days <count>] [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--limit <count>] [--target <username>] [--public] [--details] [--type <value>] [--contains <text>] [--min-tss <number>] [--max-tss <number>] [--sort date|date-desc|tss|tss-desc] [--result-limit <count>] [--fields a,b] [--records-only] [--json|--jsonl]",
+    ],
+    examples: [
+      "trainerroad-cli past --days 30 --json",
+      "trainerroad-cli past --days 90 --min-tss 80 --sort tss-desc --result-limit 20 --jsonl",
     ],
   },
   ftp: {
     summary: "Show FTP snapshot and FTP history (private or public mode).",
     usage: [
-      "node src/cli.mjs ftp [--target <username>] [--public] [--history-limit <n>] [--json|--jsonl]",
+      "trainerroad-cli ftp [--target <username>] [--public] [--history-limit <count>] [--json|--jsonl]",
+    ],
+    examples: [
+      "trainerroad-cli ftp --json",
+      "trainerroad-cli ftp --target quinnsprouse --public --history-limit 12 --json",
     ],
   },
   "ftp-prediction": {
     summary: "Show AI FTP detection eligibility/status and progression impact (private mode).",
-    usage: ["node src/cli.mjs ftp-prediction [--json]"],
+    usage: ["trainerroad-cli ftp-prediction [--json]"],
+    examples: ["trainerroad-cli ftp-prediction --json"],
   },
   "power-ranking": {
     summary: "Show best-power percentile ranking by duration (private mode).",
-    usage: ["node src/cli.mjs power-ranking [--json|--jsonl]"],
+    usage: ["trainerroad-cli power-ranking [--json|--jsonl]"],
+    examples: ["trainerroad-cli power-ranking --json"],
   },
   "power-records": {
     summary: "Show date-range personal power records from TrainerRoad PR endpoint (private mode).",
     usage: [
-      "node src/cli.mjs power-records [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD] [--row-type 100|101] [--indoor-only true|false] [--limit <n>] [--full] [--json|--jsonl]",
+      "trainerroad-cli power-records [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD] [--row-type 100|101] [--indoor-only true|false] [--limit <count>] [--full] [--json|--jsonl]",
+    ],
+    examples: [
+      "trainerroad-cli power-records --start-date 2026-01-01 --end-date 2026-03-01 --json",
+      "trainerroad-cli power-records --row-type 101 --indoor-only true --limit 20 --jsonl",
     ],
   },
   "workout-library": {
     summary: "Search the TrainerRoad workout library with agent-friendly filters (private mode).",
     usage: [
-      'node src/cli.mjs workout-library [--search <text>] [--zone <name>|--zone-id <id>] [--profile <name>|--profile-id <id>] [--outside true|false] [--has-instructions true|false] [--min-duration <minutes>] [--max-duration <minutes>] [--min-tss <n>] [--max-tss <n>] [--min-level <n>] [--max-level <n>] [--sort level|level-desc|duration|duration-desc|tss|tss-desc|name|name-desc] [--limit <n>] [--page-size <n>] [--json|--jsonl]',
+      "trainerroad-cli workout-library [--search <text>] [--zone <name>|--zone-id <id>] [--profile <name>|--profile-id <id>] [--outside true|false] [--has-instructions true|false] [--min-duration <minutes>] [--max-duration <minutes>] [--min-tss <number>] [--max-tss <number>] [--min-level <number>] [--max-level <number>] [--sort level|level-desc|duration|duration-desc|tss|tss-desc|name|name-desc] [--limit <count>] [--page-size <count>] [--json|--jsonl]",
+    ],
+    examples: [
+      "trainerroad-cli workout-library --zone Endurance --profile \"Sustained Power\" --min-duration 45 --max-duration 75 --json",
+      "trainerroad-cli workout-library --search Baxter --limit 5 --json",
     ],
   },
   "workout-recommend": {
     summary: "Recommend library workouts by ranking candidates against target duration/level/TSS (private mode).",
     usage: [
-      'node src/cli.mjs workout-recommend [--search <text>] [--zone <name>|--zone-id <id>] [--profile <name>|--profile-id <id>] [--outside true|false] [--has-instructions true|false] [--min-duration <minutes>] [--max-duration <minutes>] [--min-tss <n>] [--max-tss <n>] [--min-level <n>] [--max-level <n>] [--target-duration <minutes>] [--target-tss <n>] [--target-level <n>] [--count <n>] [--candidate-limit <n>] [--page-size <n>] [--sort level|level-desc|duration|duration-desc|tss|tss-desc|name|name-desc] [--json|--jsonl]',
+      "trainerroad-cli workout-recommend [--search <text>] [--zone <name>|--zone-id <id>] [--profile <name>|--profile-id <id>] [--outside true|false] [--has-instructions true|false] [--min-duration <minutes>] [--max-duration <minutes>] [--min-tss <number>] [--max-tss <number>] [--min-level <number>] [--max-level <number>] [--target-duration <minutes>] [--target-tss <number>] [--target-level <number>] [--count <count>] [--candidate-limit <count>] [--page-size <count>] [--sort level|level-desc|duration|duration-desc|tss|tss-desc|name|name-desc] [--json|--jsonl]",
+    ],
+    examples: [
+      "trainerroad-cli workout-recommend --zone Endurance --profile \"Sustained Power\" --target-duration 60 --target-level 1.0 --count 3 --json",
+      "trainerroad-cli workout-recommend --search threshold --target-duration 90 --count 5 --json",
     ],
   },
   "workout-details": {
     summary: "Fetch detailed workout-library metadata for a workout ID (private mode).",
     usage: [
-      "node src/cli.mjs workout-details --id <workout-id> [--include-chart true|false] [--chart-point-limit <n>] [--json|--jsonl]",
+      "trainerroad-cli workout-details --id <workout-id> [--include-chart true|false] [--chart-point-limit <count>] [--json|--jsonl]",
+    ],
+    examples: [
+      "trainerroad-cli workout-details --id 18128 --json",
+      "trainerroad-cli workout-details --id 18128 --include-chart --chart-point-limit 50 --json",
     ],
   },
   "add-workout": {
     summary: "Add a library workout to the calendar on a target date (private mode; reconciles flaky API responses).",
     usage: [
-      "node src/cli.mjs add-workout --workout-id <workout-id> --date YYYY-MM-DD [--outside true|false] [--json|--jsonl]",
+      "trainerroad-cli add-workout --workout-id <workout-id> --date YYYY-MM-DD [--outside true|false] [--dry-run] [--json|--jsonl]",
+    ],
+    examples: [
+      "trainerroad-cli add-workout --workout-id 18128 --date 2026-03-16 --dry-run",
+      "trainerroad-cli add-workout --workout-id 18128 --date 2026-03-16 --json",
     ],
   },
   "copy-workout": {
     summary: "Copy an existing planned workout to another date (private mode).",
     usage: [
-      "node src/cli.mjs copy-workout --id <planned-activity-id> --date YYYY-MM-DD [--json|--jsonl]",
+      "trainerroad-cli copy-workout --id <planned-activity-id> --date YYYY-MM-DD [--dry-run] [--json|--jsonl]",
+    ],
+    examples: [
+      "trainerroad-cli copy-workout --id 123456 --date 2026-03-16 --dry-run",
+      "trainerroad-cli copy-workout --id 123456 --date 2026-03-16 --json",
     ],
   },
   "workout-alternates": {
     summary: "List alternate workout options for a planned workout (private mode).",
     usage: [
-      "node src/cli.mjs workout-alternates --id <planned-activity-id> [--category similar|easier|harder|longer|shorter] [--json|--jsonl]",
+      "trainerroad-cli workout-alternates --id <planned-activity-id> [--category similar|easier|harder|longer|shorter] [--json|--jsonl]",
+    ],
+    examples: [
+      "trainerroad-cli workout-alternates --id 123456 --json",
+      "trainerroad-cli workout-alternates --id 123456 --category easier --json",
     ],
   },
   "move-workout": {
     summary: "Move a planned workout to a different date (private mode).",
     usage: [
-      "node src/cli.mjs move-workout --id <planned-activity-id> --to YYYY-MM-DD [--json|--jsonl]",
+      "trainerroad-cli move-workout --id <planned-activity-id> --to YYYY-MM-DD [--dry-run] [--json|--jsonl]",
+    ],
+    examples: [
+      "trainerroad-cli move-workout --id 123456 --to 2026-03-13 --dry-run",
+      "trainerroad-cli move-workout --id 123456 --to 2026-03-13 --json",
     ],
   },
   "replace-workout": {
     summary: "Replace a planned workout with a specific alternate workout ID (private mode).",
     usage: [
-      "node src/cli.mjs replace-workout --id <planned-activity-id> --alternate-id <workout-id> [--update-duration true|false] [--json|--jsonl]",
+      "trainerroad-cli replace-workout --id <planned-activity-id> --alternate-id <workout-id> [--update-duration true|false] [--dry-run] [--json|--jsonl]",
+    ],
+    examples: [
+      "trainerroad-cli replace-workout --id 123456 --alternate-id 18128 --dry-run",
+      "trainerroad-cli replace-workout --id 123456 --alternate-id 18128 --json",
     ],
   },
   "switch-workout": {
     summary: "Switch a planned workout between inside and outside variants (private mode).",
     usage: [
-      "node src/cli.mjs switch-workout --id <planned-activity-id> --mode inside|outside [--json|--jsonl]",
+      "trainerroad-cli switch-workout --id <planned-activity-id> --mode inside|outside [--dry-run] [--json|--jsonl]",
+    ],
+    examples: [
+      "trainerroad-cli switch-workout --id 123456 --mode outside --dry-run",
+      "trainerroad-cli switch-workout --id 123456 --mode outside --json",
     ],
   },
   logout: {
     summary: "Clear local persisted session.",
-    usage: ["node src/cli.mjs logout"],
+    usage: ["trainerroad-cli logout"],
+    examples: ["trainerroad-cli logout"],
   },
 };
 
@@ -176,6 +276,7 @@ export const PROJECT_NOTICE = "Unofficial tool. Not affiliated with or endorsed
 export const GLOBAL_NOTES = [
   PROJECT_NOTICE,
   "Environment: TR_USERNAME, TR_PASSWORD, TR_SESSION_FILE, TR_TIMEZONE",
+  "Non-interactive by default: pass flags or stdin; commands do not prompt.",
   "Timezone: --tz <IANA timezone> (for example America/New_York).",
   "Output modes: default JSON, --json, --jsonl, --output <path>",
   "Session file default: .trainerroad/session.json",
@@ -183,6 +284,7 @@ export const GLOBAL_NOTES = [
   "Public mode: username-based endpoint (`/app/api/tss/{username}`) with limited detail.",
   "Agent filters: --from --to --type --contains --min-tss --max-tss --sort --result-limit --fields",
   "Agent output: --records-only",
+  "Write commands: use --dry-run to preview calendar mutations before applying them.",
 ];
 
 export const AGENT_FILTER_OPTIONS = [
@@ -216,6 +318,160 @@ export const FILTERABLE_COMMANDS = new Set([
   "weight-history",
 ]);
 
+export const COMMAND_REQUIRED_FLAGS = {
+  "workout-details": ["id"],
+  "add-workout": ["workout-id", "date"],
+  "copy-workout": ["id", "date"],
+  "workout-alternates": ["id"],
+  "move-workout": ["id", "to"],
+  "replace-workout": ["id", "alternate-id"],
+  "switch-workout": ["id", "mode"],
+};
+
+export const FLAG_DETAILS = {
+  help: { description: "Show command help and exit." },
+  output: { placeholder: "<path>", description: "Write command output to a file instead of stdout." },
+  json: { description: "Emit machine-readable JSON output." },
+  jsonl: { description: "Emit newline-delimited JSON records." },
+  "session-file": {
+    placeholder: "<path>",
+    description: "Override the persisted session file path.",
+  },
+  username: { placeholder: "<username>", description: "TrainerRoad account username." },
+  password: {
+    placeholder: "<password>",
+    description: "TrainerRoad account password. Prefer --password-stdin or TR_PASSWORD.",
+  },
+  "password-stdin": {
+    description: "Read the password from stdin so the command stays non-interactive and shell-history safe.",
+  },
+  "return-path": {
+    placeholder: "<path>",
+    description: "Override the login ReturnUrl used during the auth flow.",
+  },
+  level: { placeholder: "1|2|3", description: "Discovery detail level." },
+  command: { placeholder: "<command>", description: "Limit discovery/help output to one command." },
+  target: { placeholder: "<username>", description: "Public TrainerRoad profile username to query." },
+  public: {
+    description: "Force public-mode requests even when an authenticated session exists.",
+  },
+  full: { description: "Return fuller upstream payload data when the command supports it." },
+  duration: { placeholder: "<minutes>", description: "Requested workout duration in minutes." },
+  "num-suggestions": {
+    placeholder: "<count>",
+    description: "Maximum TrainNow suggestions to request.",
+  },
+  category: {
+    placeholder: "<value>",
+    description: "Command-specific category filter (for example easier, endurance, or outside).",
+  },
+  from: { placeholder: "YYYY-MM-DD", description: "Inclusive lower date bound." },
+  to: { placeholder: "YYYY-MM-DD", description: "Inclusive upper date bound or move target date." },
+  type: { placeholder: "<value>", description: "Command-specific record type filter." },
+  contains: { placeholder: "<text>", description: "Case-insensitive substring filter." },
+  "min-tss": { placeholder: "<number>", description: "Minimum TSS threshold." },
+  "max-tss": { placeholder: "<number>", description: "Maximum TSS threshold." },
+  sort: { placeholder: "<mode>", description: "Command-specific sort mode." },
+  "result-limit": { placeholder: "<count>", description: "Limit records after filters are applied." },
+  fields: { placeholder: "a,b,c", description: "Project record fields for leaner downstream payloads." },
+  "records-only": {
+    description: "Return only the envelope and records arrays when supported.",
+  },
+  view: { placeholder: "current|phases|plans", description: "Plan view to return." },
+  date: { placeholder: "YYYY-MM-DD", description: "Target calendar date." },
+  details: { description: "Include additional workout/activity detail in the payload." },
+  days: { placeholder: "<count>", description: "Relative day window size." },
+  limit: { placeholder: "<count>", description: "Upstream or record limit for the command." },
+  "history-limit": {
+    placeholder: "<count>",
+    description: "Maximum FTP history entries to include.",
+  },
+  "start-date": { placeholder: "YYYY-MM-DD", description: "Personal records window start date." },
+  "end-date": { placeholder: "YYYY-MM-DD", description: "Personal records window end date." },
+  "row-type": {
+    placeholder: "100|101",
+    description: "TrainerRoad PR row type to query.",
+  },
+  "indoor-only": {
+    placeholder: "true|false",
+    description: "Restrict personal-record queries to indoor rides.",
+  },
+  slot: {
+    placeholder: "<value>",
+    description: "Reserved upstream query slot used by the power-records endpoint.",
+  },
+  search: { placeholder: "<text>", description: "Free-text workout search query." },
+  zone: { placeholder: "<name>", description: "Workout zone name filter." },
+  "zone-id": { placeholder: "<id>", description: "Workout zone numeric identifier." },
+  profile: { placeholder: "<name>", description: "Workout profile name filter." },
+  "profile-id": { placeholder: "<id>", description: "Workout profile numeric identifier." },
+  outside: {
+    placeholder: "true|false",
+    description: "Filter or create the outside workout variant where supported.",
+  },
+  "has-instructions": {
+    placeholder: "true|false",
+    description: "Filter workouts by whether text instructions exist.",
+  },
+  "min-duration": { placeholder: "<minutes>", description: "Minimum workout duration." },
+  "max-duration": { placeholder: "<minutes>", description: "Maximum workout duration." },
+  "min-level": { placeholder: "<number>", description: "Minimum workout progression level." },
+  "max-level": { placeholder: "<number>", description: "Maximum workout progression level." },
+  "target-duration": {
+    placeholder: "<minutes>",
+    description: "Target duration used when ranking recommended workouts.",
+  },
+  "target-tss": {
+    placeholder: "<number>",
+    description: "Target TSS used when ranking recommended workouts.",
+  },
+  "target-level": {
+    placeholder: "<number>",
+    description: "Target progression level used when ranking recommended workouts.",
+  },
+  count: { placeholder: "<count>", description: "Number of recommendations to return." },
+  "candidate-limit": {
+    placeholder: "<count>",
+    description: "Maximum candidate workouts to score before ranking.",
+  },
+  "page-size": {
+    placeholder: "<count>",
+    description: "Upstream workout library page size.",
+  },
+  id: { placeholder: "<id>", description: "Workout, planned activity, or record identifier." },
+  "include-chart": {
+    placeholder: "true|false",
+    description: "Include workout chart/sample data in workout-details.",
+  },
+  "chart-point-limit": {
+    placeholder: "<count>",
+    description: "Maximum chart points returned with --include-chart.",
+  },
+  "workout-id": {
+    placeholder: "<workout-id>",
+    description: "TrainerRoad workout library identifier.",
+  },
+  "dry-run": {
+    description: "Preview the write command and exit without mutating the calendar.",
+  },
+  "alternate-id": {
+    placeholder: "<workout-id>",
+    description: "Alternate workout ID to apply during replace-workout.",
+  },
+  "update-duration": {
+    placeholder: "true|false",
+    description: "Let TrainerRoad update the duration during replace-workout.",
+  },
+  mode: {
+    placeholder: "inside|outside",
+    description: "Target workout delivery mode for switch-workout.",
+  },
+  tz: {
+    placeholder: "<IANA timezone>",
+    description: "Override local-day bucketing (defaults to TR_TIMEZONE or system timezone).",
+  },
+};
+
 function trimFlagPrefix(flag) {
   return String(flag ?? "").replace(/^--/, "").trim();
 }
@@ -238,6 +494,7 @@ const SHARED_FLAGS = {
   jsonAndJsonl: ["json", "jsonl"],
   agentFilters: AGENT_FILTER_OPTIONS.map((option) => trimFlagPrefix(option.flag)),
   agentOutput: AGENT_OUTPUT_OPTIONS.map((option) => trimFlagPrefix(option.flag)),
+  writeSafety: ["dry-run"],
 };
 
 export const COMMAND_FLAG_ALLOWLIST = {
@@ -460,6 +717,7 @@ export const COMMAND_FLAG_ALLOWLIST = {
     SHARED_FLAGS.jsonAndJsonl,
     SHARED_FLAGS.session,
     SHARED_FLAGS.credentials,
+    SHARED_FLAGS.writeSafety,
     ["workout-id", "date", "outside"],
   ),
   "copy-workout": mergeFlagGroups(
@@ -468,6 +726,7 @@ export const COMMAND_FLAG_ALLOWLIST = {
     SHARED_FLAGS.jsonAndJsonl,
     SHARED_FLAGS.session,
     SHARED_FLAGS.credentials,
+    SHARED_FLAGS.writeSafety,
     ["id", "date"],
   ),
   "workout-alternates": mergeFlagGroups(
@@ -484,6 +743,7 @@ export const COMMAND_FLAG_ALLOWLIST = {
     SHARED_FLAGS.jsonAndJsonl,
     SHARED_FLAGS.session,
     SHARED_FLAGS.credentials,
+    SHARED_FLAGS.writeSafety,
     ["id", "to"],
   ),
   "replace-workout": mergeFlagGroups(
@@ -492,6 +752,7 @@ export const COMMAND_FLAG_ALLOWLIST = {
     SHARED_FLAGS.jsonAndJsonl,
     SHARED_FLAGS.session,
     SHARED_FLAGS.credentials,
+    SHARED_FLAGS.writeSafety,
     ["id", "alternate-id", "update-duration"],
   ),
   "switch-workout": mergeFlagGroups(
@@ -500,6 +761,7 @@ export const COMMAND_FLAG_ALLOWLIST = {
     SHARED_FLAGS.jsonAndJsonl,
     SHARED_FLAGS.session,
     SHARED_FLAGS.credentials,
+    SHARED_FLAGS.writeSafety,
     ["id", "mode"],
   ),
   logout: mergeFlagGroups(SHARED_FLAGS.help, SHARED_FLAGS.output, SHARED_FLAGS.session),

package/src/trainerroad-client.mjs

@@ -191,7 +191,7 @@ export class TrainerRoadClient {
   async login({
     username = this.username,
     password = this.password,
-    returnPath = "/app/career/quinnsprouse",
+    returnPath = username ? `/app/career/${username}` : "/app/career",
   } = {}) {
     if (!username || !password) {
       throw new Error("Username and password are required for login.");