Standardize command arguments

package.json

@@ -51,7 +51,7 @@
     "prepare": "[ -d .git ] && [ -d .githooks ] && git config core.hooksPath .githooks || true; pnpm run build && CI=true ABLY_INTERACTIVE=false oclif manifest",
     "postinstall": "[ \"$CI\" = \"true\" ] || (test -f ./dist/scripts/postinstall-welcome.js && node ./dist/scripts/postinstall-welcome.js || echo \"Skipping welcome script (not found)\")",
     "preversion": "pnpm run prepare",
-    "generate-doc": "rm -f OCLIF_AUTOGENERATED_DOC.md && printf '<!-- toc -->\\n<!-- tocstop -->\\n<!-- usage -->\\n<!-- usagestop -->\\n<!-- commands -->\\n<!-- commandsstop -->\\n' > OCLIF_AUTOGENERATED_DOC.md && (GENERATING_DOC=true NO_COLOR=1 oclif readme --readme-path OCLIF_AUTOGENERATED_DOC.md)",
+    "generate-doc": "cp scripts/doc-template.md OCLIF_AUTOGENERATED_DOC.md && GENERATING_DOC=true NO_COLOR=1 oclif readme --readme-path OCLIF_AUTOGENERATED_DOC.md",
     "validate": "./scripts/pre-push-validation.sh",
     "pre-commit": "pnpm validate",
     "ai-init": "echo 'AI Assistant Instructions:' && cat .claude/CLAUDE.md",
@@ -78,7 +78,8 @@
     "hooks": {
       "init": [
         "./dist/src/hooks/init/alias-command",
-        "./dist/src/hooks/init/version-flag"
+        "./dist/src/hooks/init/version-flag",
+        "./dist/src/hooks/init/patch-arg-names"
       ],
       "command_not_found": "./dist/src/hooks/command_not_found/did-you-mean"
     },

scripts/doc-template.md

@@ -0,0 +1,6 @@
+<!-- toc -->
+<!-- tocstop -->
+<!-- usage -->
+<!-- usagestop -->
+<!-- commands -->
+<!-- commandsstop -->

src/commands/accounts/logout.ts

@@ -6,7 +6,7 @@ import { promptForConfirmation } from "../../utils/prompt-confirmation.js";
 
 export default class AccountsLogout extends ControlBaseCommand {
   static override args = {
-    alias: Args.string({
+    accountAlias: Args.string({
       description:
         "Alias of the account to log out from (defaults to current account)",
       required: false,
@@ -32,7 +32,7 @@ export default class AccountsLogout extends ControlBaseCommand {
 
     // Determine which account to log out from
     const targetAlias =
-      args.alias || this.configManager.getCurrentAccountAlias();
+      args.accountAlias || this.configManager.getCurrentAccountAlias();
 
     if (!targetAlias) {
       this.fail(

src/commands/accounts/switch.ts

@@ -7,7 +7,7 @@ import { formatResource } from "../../utils/output.js";
 
 export default class AccountsSwitch extends ControlBaseCommand {
   static override args = {
-    alias: Args.string({
+    accountAlias: Args.string({
       description: "Alias of the account to switch to",
       required: false,
     }),
@@ -49,8 +49,8 @@ export default class AccountsSwitch extends ControlBaseCommand {
     }
 
     // If alias is provided, switch directly
-    if (args.alias) {
-      await this.switchToAccount(args.alias, accounts, flags);
+    if (args.accountAlias) {
+      await this.switchToAccount(args.accountAlias, accounts, flags);
       return;
     }
 

src/commands/apps/update.ts

@@ -5,7 +5,7 @@ import { formatLabel, formatResource } from "../../utils/output.js";
 
 export default class AppsUpdateCommand extends ControlBaseCommand {
   static args = {
-    id: Args.string({
+    appId: Args.string({
       description: "App ID to update",
       required: true,
     }),
@@ -44,13 +44,13 @@ export default class AppsUpdateCommand extends ControlBaseCommand {
         "At least one update parameter (--name or --tls-only) must be provided",
         flags,
         "appUpdate",
-        { appId: args.id },
+        { appId: args.appId },
       );
     }
 
     try {
       const controlApi = this.createControlApi(flags);
-      this.logProgress(`Updating app ${formatResource(args.id)}`, flags);
+      this.logProgress(`Updating app ${formatResource(args.appId)}`, flags);
 
       const updateData: { name?: string; tlsOnly?: boolean } = {};
 
@@ -62,7 +62,7 @@ export default class AppsUpdateCommand extends ControlBaseCommand {
         updateData.tlsOnly = flags["tls-only"];
       }
 
-      const app = await controlApi.updateApp(args.id, updateData);
+      const app = await controlApi.updateApp(args.appId, updateData);
 
       if (this.shouldOutputJson(flags)) {
         this.logJsonResult(
@@ -101,7 +101,7 @@ export default class AppsUpdateCommand extends ControlBaseCommand {
       this.logSuccessMessage("App updated successfully.", flags);
     } catch (error) {
       this.fail(error, flags, "appUpdate", {
-        appId: args.id,
+        appId: args.appId,
       });
     }
   }

src/commands/bench/publisher.ts

@@ -38,7 +38,7 @@ interface PublisherFlags {
 }
 
 interface PublisherArgs {
-  channel: string;
+  channelName: string;
 }
 
 // Interface for message payload
@@ -54,7 +54,7 @@ interface BenchmarkPayload {
 
 export default class BenchPublisher extends AblyBaseCommand {
   static override args = {
-    channel: Args.string({
+    channelName: Args.string({
       description: "The channel name to publish to",
       required: true,
     }),
@@ -162,7 +162,9 @@ export default class BenchPublisher extends AblyBaseCommand {
     };
 
     try {
-      channel = client.channels.get(args.channel, { params: { rewind: "1" } });
+      channel = client.channels.get(args.channelName, {
+        params: { rewind: "1" },
+      });
 
       // Set up channel state logging
       this.setupChannelStateLogging(channel, flags, {
@@ -174,7 +176,7 @@ export default class BenchPublisher extends AblyBaseCommand {
         metrics,
         messageTracking,
         flags,
-        args.channel,
+        args.channelName,
       );
 
       await this.enterPresence(
@@ -496,7 +498,7 @@ export default class BenchPublisher extends AblyBaseCommand {
 
     const summaryData = {
       actualRateMsgsPerSec: avgRate,
-      channel: args.channel,
+      channel: args.channelName,
       echoLatencyAvgMs: avgEchoLatency,
       echoLatencyP50Ms: echoP50,
       echoLatencyP90Ms: echoP90,
@@ -536,7 +538,7 @@ export default class BenchPublisher extends AblyBaseCommand {
       });
       summaryTable.push(
         ["Test ID", testId],
-        ["Channel", args.channel],
+        ["Channel", args.channelName],
         ["Transport", flags.transport],
         ["Messages sent", `${metrics.messagesSent}/${messageCount}`],
         [

src/commands/bench/subscriber.ts

@@ -21,7 +21,7 @@ interface TestMetrics {
 
 export default class BenchSubscriber extends AblyBaseCommand {
   static override args = {
-    channel: Args.string({
+    channelName: Args.string({
       description: "The channel name to subscribe to",
       required: true,
     }),
@@ -89,11 +89,11 @@ export default class BenchSubscriber extends AblyBaseCommand {
     };
 
     try {
-      const channel = this.handleChannel(client, args.channel, flags);
+      const channel = this.handleChannel(client, args.channelName, flags);
 
       // Show initial status
       this.logProgress(
-        `Attaching to channel: ${formatResource(args.channel)}`,
+        `Attaching to channel: ${formatResource(args.channelName)}`,
         flags,
       );
 
@@ -108,13 +108,13 @@ export default class BenchSubscriber extends AblyBaseCommand {
         flags,
         "benchmark",
         "subscriberReady",
-        `Subscriber ready on channel: ${args.channel}`,
-        { channel: args.channel },
+        `Subscriber ready on channel: ${args.channelName}`,
+        { channel: args.channelName },
       );
 
       // Show success message
       this.logSuccessMessage(
-        `Subscribed to channel: ${formatResource(args.channel)}. Waiting for benchmark messages.`,
+        `Subscribed to channel: ${formatResource(args.channelName)}. Waiting for benchmark messages.`,
         flags,
       );
 

src/commands/channels/annotations/delete.ts

@@ -11,15 +11,15 @@ import { formatResource } from "../../../utils/output.js";
 
 export default class ChannelsAnnotationsDelete extends AblyBaseCommand {
   static override args = {
-    channel: Args.string({
+    channelName: Args.string({
       description: "The channel name",
       required: true,
     }),
-    serial: Args.string({
+    messageSerial: Args.string({
       description: "The serial of the message to remove annotation from",
       required: true,
     }),
-    type: Args.string({
+    annotationType: Args.string({
       description:
         "The annotation type (e.g., reactions:flag.v1, reactions:multiple.v1)",
       required: true,
@@ -47,9 +47,9 @@ export default class ChannelsAnnotationsDelete extends AblyBaseCommand {
 
   async run(): Promise<void> {
     const { args, flags } = await this.parse(ChannelsAnnotationsDelete);
-    const channelName = args.channel;
-    const serial = args.serial;
-    const type = args.type;
+    const channelName = args.channelName;
+    const serial = args.messageSerial;
+    const type = args.annotationType;
 
     let client: Ably.Realtime | null = null;
 

src/commands/channels/annotations/get.ts

@@ -16,11 +16,11 @@ import type { AnnotationDisplayFields } from "../../../utils/output.js";
 
 export default class ChannelsAnnotationsGet extends AblyBaseCommand {
   static override args = {
-    channel: Args.string({
+    channelName: Args.string({
       description: "The channel name",
       required: true,
     }),
-    serial: Args.string({
+    messageSerial: Args.string({
       description: "The serial of the message to get annotations for",
       required: true,
     }),
@@ -46,8 +46,8 @@ export default class ChannelsAnnotationsGet extends AblyBaseCommand {
 
   async run(): Promise<void> {
     const { args, flags } = await this.parse(ChannelsAnnotationsGet);
-    const channelName = args.channel;
-    const serial = args.serial;
+    const channelName = args.channelName;
+    const serial = args.messageSerial;
 
     try {
       const rest = await this.createAblyRestClient(flags);

src/commands/channels/annotations/publish.ts

@@ -11,15 +11,15 @@ import { formatResource } from "../../../utils/output.js";
 
 export default class ChannelsAnnotationsPublish extends AblyBaseCommand {
   static override args = {
-    channel: Args.string({
+    channelName: Args.string({
       description: "The channel name",
       required: true,
     }),
-    serial: Args.string({
+    messageSerial: Args.string({
       description: "The serial of the message to annotate",
       required: true,
     }),
-    type: Args.string({
+    annotationType: Args.string({
       description:
         "The annotation type (e.g., reactions:flag.v1, reactions:multiple.v1)",
       required: true,
@@ -58,9 +58,9 @@ export default class ChannelsAnnotationsPublish extends AblyBaseCommand {
 
   async run(): Promise<void> {
     const { args, flags } = await this.parse(ChannelsAnnotationsPublish);
-    const channelName = args.channel;
-    const serial = args.serial;
-    const type = args.type;
+    const channelName = args.channelName;
+    const serial = args.messageSerial;
+    const type = args.annotationType;
 
     try {
       const summarization = extractSummarizationType(type);

src/commands/channels/annotations/subscribe.ts

@@ -17,7 +17,7 @@ import type { AnnotationDisplayFields } from "../../../utils/output.js";
 
 export default class ChannelsAnnotationsSubscribe extends AblyBaseCommand {
   static override args = {
-    channel: Args.string({
+    channelName: Args.string({
       description: "The channel name to subscribe to annotations on",
       required: true,
     }),
@@ -47,7 +47,7 @@ export default class ChannelsAnnotationsSubscribe extends AblyBaseCommand {
 
   async run(): Promise<void> {
     const { args, flags } = await this.parse(ChannelsAnnotationsSubscribe);
-    const channelName = args.channel;
+    const channelName = args.channelName;
 
     try {
       this.client = await this.createAblyRealtimeClient(flags);

src/commands/channels/append.ts

@@ -8,11 +8,11 @@ import { formatResource } from "../../utils/output.js";
 
 export default class ChannelsAppend extends AblyBaseCommand {
   static override args = {
-    channel: Args.string({
+    channelName: Args.string({
       description: "The channel name",
       required: true,
     }),
-    serial: Args.string({
+    messageSerial: Args.string({
       description: "The serial of the message to append to",
       required: true,
     }),
@@ -51,8 +51,8 @@ export default class ChannelsAppend extends AblyBaseCommand {
 
   async run(): Promise<void> {
     const { args, flags } = await this.parse(ChannelsAppend);
-    const channelName = args.channel;
-    const serial = args.serial;
+    const channelName = args.channelName;
+    const serial = args.messageSerial;
 
     try {
       const rest = await this.createAblyRestClient(flags);

src/commands/channels/delete.ts

@@ -7,11 +7,11 @@ import { formatResource } from "../../utils/output.js";
 
 export default class ChannelsDelete extends AblyBaseCommand {
   static override args = {
-    channel: Args.string({
+    channelName: Args.string({
       description: "The channel name",
       required: true,
     }),
-    serial: Args.string({
+    messageSerial: Args.string({
       description: "The serial of the message to delete",
       required: true,
     }),
@@ -36,8 +36,8 @@ export default class ChannelsDelete extends AblyBaseCommand {
 
   async run(): Promise<void> {
     const { args, flags } = await this.parse(ChannelsDelete);
-    const channelName = args.channel;
-    const serial = args.serial;
+    const channelName = args.channelName;
+    const serial = args.messageSerial;
 
     try {
       const rest = await this.createAblyRestClient(flags);

src/commands/channels/history.ts

@@ -22,7 +22,7 @@ import {
 
 export default class ChannelsHistory extends AblyBaseCommand {
   static override args = {
-    channel: Args.string({
+    channelName: Args.string({
       description: "Channel name to retrieve history for",
       required: true,
     }),
@@ -62,7 +62,7 @@ export default class ChannelsHistory extends AblyBaseCommand {
 
   async run(): Promise<void> {
     const { args, flags } = await this.parse(ChannelsHistory);
-    const channelName = args.channel;
+    const channelName = args.channelName;
     let client: Ably.Rest | null;
 
     try {

src/commands/channels/inspect.ts

@@ -6,7 +6,7 @@ import { formatResource } from "../../utils/output.js";
 
 export default class ChannelsInspect extends AblyBaseCommand {
   static override args = {
-    channel: Args.string({
+    channelName: Args.string({
       description: "The name of the channel to inspect in the Ably dashboard",
       required: true,
     }),
@@ -52,7 +52,7 @@ export default class ChannelsInspect extends AblyBaseCommand {
     if (dashboardHost && !/^https?:\/\//i.test(dashboardHost)) {
       dashboardHost = `https://${dashboardHost}`;
     }
-    const url = `${dashboardHost}/accounts/${accountId}/apps/${appId}/channels/${encodeURIComponent(args.channel)}`;
+    const url = `${dashboardHost}/accounts/${accountId}/apps/${appId}/channels/${encodeURIComponent(args.channelName)}`;
 
     if (this.shouldOutputJson(flags)) {
       this.logJsonResult({ channel: { url } }, flags);