[DX-793] Migrate placeholder topic commands to BaseTopicCommand and add --json examples

umair-ably · claude · umair-ably · commit b569d4f1628c · 2026-03-11T02:26:04.000Z
Migrate 14 placeholder/index files from extending Command to
BaseTopicCommand for consistency with other topic commands.
Add missing --json examples to 5 leaf commands.

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/src/commands/apps/channel-rules/create.ts b/src/commands/apps/channel-rules/create.ts
@@ -11,6 +11,7 @@ export default class ChannelRulesCreateCommand extends ControlBaseCommand {
     '$ ably apps channel-rules create --name "chat" --persisted',
     '$ ably apps channel-rules create --name "events" --push-enabled',
     '$ ably apps channel-rules create --name "notifications" --persisted --push-enabled --app "My App"',
+    '$ ably apps channel-rules create --name "chat" --persisted --json',
   ];
 
   static flags = {
diff --git a/src/commands/apps/channel-rules/update.ts b/src/commands/apps/channel-rules/update.ts
@@ -17,6 +17,7 @@ export default class ChannelRulesUpdateCommand extends ControlBaseCommand {
     "$ ably apps channel-rules update chat --persisted",
     "$ ably apps channel-rules update events --push-enabled=false",
     '$ ably apps channel-rules update notifications --persisted --push-enabled --app "My App"',
+    "$ ably apps channel-rules update chat --persisted --json",
   ];
 
   static flags = {
diff --git a/src/commands/apps/create.ts b/src/commands/apps/create.ts
@@ -14,6 +14,7 @@ export default class AppsCreateCommand extends ControlBaseCommand {
   static examples = [
     '$ ably apps create --name "My New App"',
     '$ ably apps create --name "My New App" --tls-only',
+    '$ ably apps create --name "My New App" --json',
     '$ ABLY_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" ably apps create --name "My New App"',
   ];
 
diff --git a/src/commands/apps/set-apns-p12.ts b/src/commands/apps/set-apns-p12.ts
@@ -25,6 +25,7 @@ export default class AppsSetApnsP12Command extends ControlBaseCommand {
     "$ ably apps set-apns-p12 app-id --certificate /path/to/certificate.p12",
     '$ ably apps set-apns-p12 app-id --certificate /path/to/certificate.p12 --password "YOUR_CERTIFICATE_PASSWORD"',
     "$ ably apps set-apns-p12 app-id --certificate /path/to/certificate.p12 --use-for-sandbox",
+    "$ ably apps set-apns-p12 app-id --certificate /path/to/certificate.p12 --json",
   ];
 
   static flags = {
diff --git a/src/commands/apps/switch.ts b/src/commands/apps/switch.ts
@@ -17,6 +17,7 @@ export default class AppsSwitch extends ControlBaseCommand {
   static override examples = [
     "<%= config.bin %> <%= command.id %> APP_ID",
     "<%= config.bin %> <%= command.id %>",
+    "<%= config.bin %> <%= command.id %> APP_ID --json",
   ];
 
   static override flags = {
diff --git a/src/commands/apps/update.ts b/src/commands/apps/update.ts
@@ -20,7 +20,7 @@ export default class AppsUpdateCommand extends ControlBaseCommand {
   static examples = [
     '$ ably apps update app-id --name "Updated App Name"',
     "$ ably apps update app-id --tls-only",
-    '$ ably apps update app-id --name "Updated App Name" --tls-only',
+    '$ ably apps update app-id --name "Updated App Name" --json',
     '$ ABLY_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" ably apps update app-id --name "Updated App Name"',
   ];
 
diff --git a/src/commands/auth/keys/switch.ts b/src/commands/auth/keys/switch.ts
@@ -19,6 +19,7 @@ export default class KeysSwitchCommand extends ControlBaseCommand {
     "$ ably auth keys switch",
     "$ ably auth keys switch APP_ID.KEY_ID",
     "$ ably auth keys switch KEY_ID --app APP_ID",
+    "$ ably auth keys switch --json",
   ];
 
   static flags = {
diff --git a/src/commands/auth/keys/update.ts b/src/commands/auth/keys/update.ts
@@ -18,6 +18,7 @@ export default class KeysUpdateCommand extends ControlBaseCommand {
     '$ ably auth keys update APP_ID.KEY_ID --name "New Name"',
     '$ ably auth keys update KEY_ID --app APP_ID --capabilities "publish,subscribe"',
     '$ ably auth keys update APP_ID.KEY_ID --name "New Name" --capabilities "publish,subscribe"',
+    '$ ably auth keys update APP_ID.KEY_ID --name "New Name" --json',
   ];
 
   static flags = {
diff --git a/src/commands/bench/publisher.ts b/src/commands/bench/publisher.ts
@@ -66,6 +66,7 @@ export default class BenchPublisher extends AblyBaseCommand {
     "$ ably bench publisher my-channel",
     "$ ably bench publisher --messages 5000 --rate 10 my-channel",
     "$ ably bench publisher --transport realtime my-channel",
+    "$ ably bench publisher my-channel --json",
   ];
 
   static override flags = {
diff --git a/src/commands/bench/subscriber.ts b/src/commands/bench/subscriber.ts
@@ -33,7 +33,10 @@ export default class BenchSubscriber extends AblyBaseCommand {
 
   static override description = "Run a subscriber benchmark test";
 
-  static override examples = ["$ ably bench subscriber my-channel"];
+  static override examples = [
+    "$ ably bench subscriber my-channel",
+    "$ ably bench subscriber my-channel --json",
+  ];
 
   static override flags = {
     ...productApiFlags,
diff --git a/src/commands/config/index.ts b/src/commands/config/index.ts
@@ -1,19 +1,13 @@
-import { AblyBaseCommand } from "../../base-command.js";
-import { coreGlobalFlags } from "../../flags.js";
+import { BaseTopicCommand } from "../../base-topic-command.js";
+
+export default class ConfigIndex extends BaseTopicCommand {
+  protected topicName = "config";
+  protected commandGroup = "Configuration";
 
-export default class ConfigIndex extends AblyBaseCommand {
   static override description = "Manage Ably CLI configuration";
 
   static override examples = [
-    "<%= config.bin %> config path",
-    "<%= config.bin %> config show",
+    "<%= config.bin %> <%= command.id %> path",
+    "<%= config.bin %> <%= command.id %> show",
   ];
-
-  static override flags = {
-    ...coreGlobalFlags,
-  };
-
-  async run(): Promise<void> {
-    await this.config.runCommand("help", ["config"]);
-  }
 }
diff --git a/src/commands/config/path.ts b/src/commands/config/path.ts
@@ -8,6 +8,7 @@ export default class ConfigPath extends AblyBaseCommand {
 
   static override examples = [
     "<%= config.bin %> <%= command.id %>",
+    "<%= config.bin %> <%= command.id %> --json",
     "# Open in your preferred editor:",
     "code $(ably config path)",
     "vim $(ably config path)",
diff --git a/src/commands/connections/test.ts b/src/commands/connections/test.ts
@@ -17,6 +17,7 @@ export default class ConnectionsTest extends AblyBaseCommand {
     "$ ably connections test",
     "$ ably connections test --transport ws",
     "$ ably connections test --transport xhr",
+    "$ ably connections test --json",
   ];
 
   static override flags = {
diff --git a/src/commands/integrations/create.ts b/src/commands/integrations/create.ts
@@ -25,6 +25,7 @@ export default class IntegrationsCreateCommand extends ControlBaseCommand {
   static examples = [
     '$ ably integrations create --rule-type "http" --source-type "channel.message" --target-url "https://example.com/webhook"',
     '$ ably integrations create --rule-type "amqp" --source-type "channel.message" --channel-filter "chat:*"',
+    '$ ably integrations create --rule-type "http" --source-type "channel.message" --target-url "https://example.com/webhook" --json',
   ];
 
   static flags = {
diff --git a/src/commands/integrations/delete.ts b/src/commands/integrations/delete.ts
@@ -22,6 +22,7 @@ export default class IntegrationsDeleteCommand extends ControlBaseCommand {
     "$ ably integrations delete integration123",
     '$ ably integrations delete integration123 --app "My App"',
     "$ ably integrations delete integration123 --force",
+    "$ ably integrations delete integration123 --json",
   ];
 
   static flags = {
diff --git a/src/commands/integrations/update.ts b/src/commands/integrations/update.ts
@@ -28,6 +28,7 @@ export default class IntegrationsUpdateCommand extends ControlBaseCommand {
     "$ ably integrations update rule123 --status disabled",
     '$ ably integrations update rule123 --channel-filter "chat:*"',
     '$ ably integrations update rule123 --target-url "https://new-example.com/webhook"',
+    "$ ably integrations update rule123 --status disabled --json",
   ];
 
   static flags = {
diff --git a/src/commands/logs/channel-lifecycle/subscribe.ts b/src/commands/logs/channel-lifecycle/subscribe.ts
@@ -25,6 +25,7 @@ export default class LogsChannelLifecycleSubscribe extends AblyBaseCommand {
   static override examples = [
     "$ ably logs channel-lifecycle subscribe",
     "$ ably logs channel-lifecycle subscribe --rewind 10",
+    "$ ably logs channel-lifecycle subscribe --json",
   ];
 
   static override flags = {
diff --git a/src/commands/logs/push/subscribe.ts b/src/commands/logs/push/subscribe.ts
@@ -24,6 +24,7 @@ export default class LogsPushSubscribe extends AblyBaseCommand {
   static override examples = [
     "$ ably logs push subscribe",
     "$ ably logs push subscribe --rewind 10",
+    "$ ably logs push subscribe --json",
   ];
 
   static override flags = {
diff --git a/src/commands/queues/create.ts b/src/commands/queues/create.ts
@@ -14,6 +14,7 @@ export default class QueuesCreateCommand extends ControlBaseCommand {
     '$ ably queues create --name "my-queue"',
     '$ ably queues create --name "my-queue" --ttl 3600 --max-length 100000',
     '$ ably queues create --name "my-queue" --region "eu-west-1-a" --app "My App"',
+    '$ ably queues create --name "my-queue" --json',
   ];
 
   static flags = {
diff --git a/src/commands/queues/delete.ts b/src/commands/queues/delete.ts
@@ -22,6 +22,7 @@ export default class QueuesDeleteCommand extends ControlBaseCommand {
     "$ ably queues delete appAbc:us-east-1-a:foo",
     '$ ably queues delete appAbc:us-east-1-a:foo --app "My App"',
     "$ ably queues delete appAbc:us-east-1-a:foo --force",
+    "$ ably queues delete appAbc:us-east-1-a:foo --json",
   ];
 
   static flags = {
diff --git a/src/commands/rooms/messages/index.ts b/src/commands/rooms/messages/index.ts
@@ -1,30 +1,15 @@
-import { Command } from "@oclif/core";
+import { BaseTopicCommand } from "../../../base-topic-command.js";
+
+export default class MessagesIndex extends BaseTopicCommand {
+  protected topicName = "rooms:messages";
+  protected commandGroup = "Room message";
 
-export default class MessagesIndex extends Command {
   static override description =
     "Commands for working with chat messages in rooms";
 
   static override examples = [
-    '$ ably rooms messages send my-room "Hello world!"',
-    "$ ably rooms messages subscribe my-room",
-    "$ ably rooms messages history my-room",
-    '$ ably rooms messages reactions add my-room "message-id" "👍"',
+    '<%= config.bin %> <%= command.id %> send my-room "Hello world!"',
+    "<%= config.bin %> <%= command.id %> subscribe my-room",
+    "<%= config.bin %> <%= command.id %> history my-room",
   ];
-
-  async run(): Promise<void> {
-    this.log("Use one of the messages subcommands:");
-    this.log("");
-    this.log(
-      "  ably rooms messages send       - Send a message to a chat room",
-    );
-    this.log(
-      "  ably rooms messages subscribe  - Subscribe to messages in a chat room",
-    );
-    this.log(
-      "  ably rooms messages history    - Get historical messages from a chat room",
-    );
-    this.log(
-      "  ably rooms messages reactions  - Work with message reactions in a chat room",
-    );
-  }
 }
diff --git a/src/commands/rooms/messages/reactions/index.ts b/src/commands/rooms/messages/reactions/index.ts
@@ -1,26 +1,14 @@
-import { Command } from "@oclif/core";
+import { BaseTopicCommand } from "../../../../base-topic-command.js";
+
+export default class MessagesReactionsIndex extends BaseTopicCommand {
+  protected topicName = "rooms:messages:reactions";
+  protected commandGroup = "Message reaction";
 
-export default class MessagesReactionsIndex extends Command {
   static override description =
     "Commands for working with message reactions in chat rooms";
 
   static override examples = [
-    '$ ably rooms messages reactions send my-room "message-id" "👍"',
-    "$ ably rooms messages reactions subscribe my-room",
-    '$ ably rooms messages reactions remove my-room "message-id" "👍"',
+    '<%= config.bin %> <%= command.id %> send my-room "message-id" "\uD83D\uDC4D"',
+    "<%= config.bin %> <%= command.id %> subscribe my-room",
   ];
-
-  async run(): Promise<void> {
-    this.log("Use one of the message reactions subcommands:");
-    this.log("");
-    this.log(
-      "  ably rooms messages reactions send      - Send a reaction to a message",
-    );
-    this.log(
-      "  ably rooms messages reactions subscribe - Subscribe to message reactions in a room",
-    );
-    this.log(
-      "  ably rooms messages reactions remove    - Remove a reaction from a message",
-    );
-  }
 }
diff --git a/src/commands/rooms/occupancy.ts b/src/commands/rooms/occupancy.ts
@@ -1,19 +1,13 @@
-import { Command } from "@oclif/core";
+import { BaseTopicCommand } from "../../base-topic-command.js";
+
+export default class RoomsOccupancy extends BaseTopicCommand {
+  protected topicName = "rooms:occupancy";
+  protected commandGroup = "Room occupancy";
 
-export default class RoomsOccupancy extends Command {
   static override description = "Commands for monitoring room occupancy";
 
   static override examples = [
-    "$ ably rooms occupancy get my-room",
-    "$ ably rooms occupancy subscribe my-room",
+    "<%= config.bin %> <%= command.id %> get my-room",
+    "<%= config.bin %> <%= command.id %> subscribe my-room",
   ];
-
-  async run(): Promise<void> {
-    this.log(
-      "This is a placeholder. Please use a subcommand: get or subscribe",
-    );
-    this.log("Examples:");
-    this.log("  $ ably rooms occupancy get my-room");
-    this.log("  $ ably rooms occupancy subscribe my-room");
-  }
 }
diff --git a/src/commands/rooms/occupancy/index.ts b/src/commands/rooms/occupancy/index.ts
@@ -1,2 +1,14 @@
-export { default as get } from "./get.js";
-export { default as subscribe } from "./subscribe.js";
+import { BaseTopicCommand } from "../../../base-topic-command.js";
+
+export default class OccupancyIndex extends BaseTopicCommand {
+  protected topicName = "rooms:occupancy";
+  protected commandGroup = "Room occupancy";
+
+  static override description =
+    "Commands for working with occupancy in chat rooms";
+
+  static override examples = [
+    "<%= config.bin %> <%= command.id %> get my-room",
+    "<%= config.bin %> <%= command.id %> subscribe my-room",
+  ];
+}
diff --git a/src/commands/rooms/presence.ts b/src/commands/rooms/presence.ts
@@ -1,19 +1,13 @@
-import { Command } from "@oclif/core";
+import { BaseTopicCommand } from "../../base-topic-command.js";
+
+export default class RoomsPresence extends BaseTopicCommand {
+  protected topicName = "rooms:presence";
+  protected commandGroup = "Room presence";
 
-export default class RoomsPresence extends Command {
   static override description = "Manage presence on Ably chat rooms";
 
   static override examples = [
-    "$ ably rooms presence enter my-room",
-    "$ ably rooms presence subscribe my-room",
+    "<%= config.bin %> <%= command.id %> enter my-room",
+    "<%= config.bin %> <%= command.id %> subscribe my-room",
   ];
-
-  async run(): Promise<void> {
-    this.log(
-      "This is a placeholder. Please use a subcommand: enter or subscribe",
-    );
-    this.log("Examples:");
-    this.log("  $ ably rooms presence enter my-room");
-    this.log("  $ ably rooms presence subscribe my-room");
-  }
 }
diff --git a/src/commands/rooms/presence/enter.ts b/src/commands/rooms/presence/enter.ts
@@ -28,6 +28,7 @@ export default class RoomsPresenceEnter extends ChatBaseCommand {
     `$ ably rooms presence enter my-room --data '{"name":"User","status":"active"}'`,
     "$ ably rooms presence enter my-room --show-others",
     "$ ably rooms presence enter my-room --duration 30",
+    "$ ably rooms presence enter my-room --json",
   ];
   static override flags = {
     ...productApiFlags,
diff --git a/src/commands/rooms/presence/index.ts b/src/commands/rooms/presence/index.ts
@@ -1,2 +1,14 @@
-export { default as enter } from "./enter.js";
-export { default as subscribe } from "./subscribe.js";
+import { BaseTopicCommand } from "../../../base-topic-command.js";
+
+export default class PresenceIndex extends BaseTopicCommand {
+  protected topicName = "rooms:presence";
+  protected commandGroup = "Room presence";
+
+  static override description =
+    "Commands for working with presence in chat rooms";
+
+  static override examples = [
+    "<%= config.bin %> <%= command.id %> enter my-room",
+    "<%= config.bin %> <%= command.id %> subscribe my-room",
+  ];
+}
diff --git a/src/commands/rooms/reactions.ts b/src/commands/rooms/reactions.ts
@@ -1,19 +1,13 @@
-import { Command } from "@oclif/core";
+import { BaseTopicCommand } from "../../base-topic-command.js";
+
+export default class RoomsReactions extends BaseTopicCommand {
+  protected topicName = "rooms:reactions";
+  protected commandGroup = "Room reaction";
 
-export default class RoomsReactions extends Command {
   static override description = "Manage reactions in Ably chat rooms";
 
   static override examples = [
-    "$ ably rooms reactions send my-room thumbs_up",
-    "$ ably rooms reactions subscribe my-room",
+    "<%= config.bin %> <%= command.id %> send my-room thumbs_up",
+    "<%= config.bin %> <%= command.id %> subscribe my-room",
   ];
-
-  async run(): Promise<void> {
-    this.log(
-      "This is a placeholder. Please use a subcommand: send or subscribe",
-    );
-    this.log("Examples:");
-    this.log("  $ ably rooms reactions send my-room thumbs_up");
-    this.log("  $ ably rooms reactions subscribe my-room");
-  }
 }
diff --git a/src/commands/rooms/reactions/index.ts b/src/commands/rooms/reactions/index.ts
@@ -1,2 +1,14 @@
-export { default as send } from "./send.js";
-export { default as subscribe } from "./subscribe.js";
+import { BaseTopicCommand } from "../../../base-topic-command.js";
+
+export default class ReactionsIndex extends BaseTopicCommand {
+  protected topicName = "rooms:reactions";
+  protected commandGroup = "Room reaction";
+
+  static override description =
+    "Commands for working with reactions in chat rooms";
+
+  static override examples = [
+    "<%= config.bin %> <%= command.id %> send my-room like",
+    "<%= config.bin %> <%= command.id %> subscribe my-room",
+  ];
+}
diff --git a/src/commands/rooms/typing/index.ts b/src/commands/rooms/typing/index.ts
diff --git a/src/commands/spaces/cursors.ts b/src/commands/spaces/cursors.ts
diff --git a/src/commands/spaces/cursors/index.ts b/src/commands/spaces/cursors/index.ts
diff --git a/src/commands/spaces/locations.ts b/src/commands/spaces/locations.ts
diff --git a/src/commands/spaces/locations/index.ts b/src/commands/spaces/locations/index.ts
diff --git a/src/commands/spaces/locations/set.ts b/src/commands/spaces/locations/set.ts
diff --git a/src/commands/spaces/locks.ts b/src/commands/spaces/locks.ts
diff --git a/src/commands/spaces/locks/acquire.ts b/src/commands/spaces/locks/acquire.ts
diff --git a/src/commands/spaces/locks/index.ts b/src/commands/spaces/locks/index.ts
diff --git a/src/commands/spaces/members.ts b/src/commands/spaces/members.ts
diff --git a/src/commands/spaces/members/enter.ts b/src/commands/spaces/members/enter.ts
diff --git a/src/commands/spaces/members/index.ts b/src/commands/spaces/members/index.ts
diff --git a/src/commands/status.ts b/src/commands/status.ts
diff --git a/src/commands/support/ask.ts b/src/commands/support/ask.ts
