Standardize command arguments by sacOO7 · Pull Request #354 · ably/ably-cli

sacOO7 · 2026-04-17T10:38:55Z

Standardized positional argument names to POSIX-compliant snake_case display.
Adds a camelToSnake transform in the custom help class to convert camelCase arg names to snake_case before oclif uppercases them. This also helps codebase to maintain camelCase argument naming across commands while keeping them verbose.
Made argument names more verbose and readable making sure consistency is well preserved across commands. Same is reflected in --help output display.

Arguments

Before	After	Help Output
`alias`	`accountAlias`	`ACCOUNT_ALIAS` instead of `ACCOUNTALIAS`
`channel`	`channelName`	`CHANNEL_NAME`
`channels`	`channelNames`	`CHANNEL_NAMES`
`"device-id"`	`deviceId`	`DEVICE_ID`
`id`	`appId`	`APP_ID`
`ruleId`	`integrationId`	`INTEGRATION_ID`
`room`	`roomName`	`ROOM_NAME`
`rooms`	`roomNames`	`ROOM_NAMES`
`serial`	`messageSerial`	`MESSAGE_SERIAL`
`space_name`	`spaceName`	`SPACE_NAME`
`type`	`annotationType`	`ANNOTATION_TYPE`

Summary

Normalize all positional argument keys to camelCase across 59 command files, replacing three inconsistent conventions (camelCase-derived like ruleId, underscore like space_name, and hyphenated like device-id) with a single camelCase convention in source code.
Add camelToSnake transform in src/help.ts that temporarily converts camelCase arg names to snake_case before oclif's formatCommand() uppercases them, producing readable UPPER_SNAKE_CASE placeholders in help output (e.g., spaceName → SPACE_NAME, messageSerial → MESSAGE_SERIAL).
Make argument names self-documenting — ambiguous names like id, serial, and channel are now appId, messageSerial, and channelName, making help output clearer without needing to read descriptions.
Update corresponding test file for spaces commands.

- Made argument names more verbose and readable - Made sure they are represented as camelCase in the codebase - Updated utils.ts to display arguments as `SNAKE_CASE`

vercel · 2026-04-17T10:38:59Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
cli-web-cli	Ready	Preview, Comment	Apr 20, 2026 4:40pm

- Added separate hook to apply camelCase to snake_case transformation - Simplified generate-doc to re-use `doc-template.md`

Copilot

Pull request overview

This PR standardizes positional argument identifiers across the CLI command sources to consistent camelCase, while ensuring the rendered help/readme placeholders remain readable as UPPER_SNAKE_CASE (via a camel→snake transform before oclif uppercases them).

Changes:

Renames positional args across commands to consistent, more descriptive camelCase keys (e.g., space_name→spaceName, room→roomName, serial→messageSerial).
Updates CustomHelp (and a new init hook for doc generation) to render arg placeholders as UPPER_SNAKE_CASE in help/readme output.
Adjusts doc generation scaffolding and updates the affected Spaces unit test assertion.

Reviewed changes

Copilot reviewed 64 out of 64 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
test/unit/commands/spaces/spaces.test.ts	Updates help-output expectation (`LOCK_ID`).
src/hooks/init/patch-arg-names.ts	Adds init hook to patch arg names during `GENERATING_DOC=true` readme generation.
src/help.ts	Adds `camelToSnake` + temporary arg-name patching during `formatCommand()` to improve help placeholders.
src/commands/stats/app.ts	Renames `id` arg to `appId` and updates usage.
src/commands/spaces/subscribe.ts	Renames `space_name` to `spaceName`.
src/commands/spaces/occupancy/subscribe.ts	Renames `space_name` to `spaceName` + updates error context.
src/commands/spaces/occupancy/get.ts	Renames `space_name` to `spaceName` + updates error context.
src/commands/spaces/members/subscribe.ts	Renames `space_name` to `spaceName`.
src/commands/spaces/members/get.ts	Renames `space_name` to `spaceName`.
src/commands/spaces/members/enter.ts	Renames `space_name` to `spaceName`.
src/commands/spaces/locks/subscribe.ts	Renames `space_name` to `spaceName`.
src/commands/spaces/locks/get.ts	Renames `space_name` to `spaceName`.
src/commands/spaces/locks/acquire.ts	Renames `space_name` to `spaceName`.
src/commands/spaces/locations/subscribe.ts	Renames `space_name` to `spaceName`.
src/commands/spaces/locations/set.ts	Renames `space_name` to `spaceName`.
src/commands/spaces/locations/get.ts	Renames `space_name` to `spaceName`.
src/commands/spaces/get.ts	Renames `space_name` to `spaceName`.
src/commands/spaces/cursors/subscribe.ts	Renames `space_name` to `spaceName`.
src/commands/spaces/cursors/set.ts	Renames `space_name` to `spaceName`.
src/commands/spaces/cursors/get.ts	Renames `space_name` to `spaceName`.
src/commands/spaces/create.ts	Renames `space_name` to `spaceName`.
src/commands/rooms/typing/subscribe.ts	Renames `room` to `roomName` + updates error context.
src/commands/rooms/typing/keystroke.ts	Renames `room` to `roomName` + updates error context.
src/commands/rooms/reactions/subscribe.ts	Renames `room` to `roomName` + updates error context.
src/commands/rooms/reactions/send.ts	Renames `room` to `roomName`.
src/commands/rooms/presence/subscribe.ts	Renames `room` to `roomName`.
src/commands/rooms/presence/get.ts	Renames `room` to `roomName` + updates error context.
src/commands/rooms/presence/enter.ts	Renames `room` to `roomName`.
src/commands/rooms/occupancy/subscribe.ts	Renames `room` to `roomName`.
src/commands/rooms/occupancy/get.ts	Renames `room` to `roomName` + updates error context.
src/commands/rooms/messages/update.ts	Renames `room`→`roomName`, `serial`→`messageSerial` throughout.
src/commands/rooms/messages/subscribe.ts	Renames `rooms` to `roomNames` for help/args key consistency.
src/commands/rooms/messages/send.ts	Renames `room` to `roomName` throughout.
src/commands/rooms/messages/reactions/subscribe.ts	Renames `room` to `roomName` + updates error context.
src/commands/rooms/messages/reactions/send.ts	Renames `room` to `roomName` (local alias retained as `room`).
src/commands/rooms/messages/reactions/remove.ts	Renames `room` to `roomName` (local alias retained as `room`).
src/commands/rooms/messages/history.ts	Renames `room` to `roomName` + updates error context.
src/commands/rooms/messages/delete.ts	Renames `room`→`roomName`, `serial`→`messageSerial` throughout.
src/commands/push/devices/remove.ts	Renames `"device-id"` arg key to `deviceId` and updates access.
src/commands/push/devices/get.ts	Renames `"device-id"` arg key to `deviceId` and updates access.
src/commands/integrations/delete.ts	Renames `integrationId` to `ruleId` and updates API calls.
src/commands/channels/update.ts	Renames `channel`→`channelName`, `serial`→`messageSerial` throughout.
src/commands/channels/subscribe.ts	Renames `channels` to `channelNames` for help/args key consistency.
src/commands/channels/publish.ts	Renames `channel` to `channelName` throughout.
src/commands/channels/presence/subscribe.ts	Renames `channel` to `channelName` + updates error context.
src/commands/channels/presence/get.ts	Renames `channel` to `channelName` + updates error context.
src/commands/channels/presence/enter.ts	Renames `channel` to `channelName` + updates error context.
src/commands/channels/occupancy/subscribe.ts	Renames `channel` to `channelName` + updates error context.
src/commands/channels/occupancy/get.ts	Renames `channel` to `channelName` + updates error context.
src/commands/channels/inspect.ts	Renames `channel` to `channelName` (URL generation).
src/commands/channels/history.ts	Renames `channel` to `channelName`.
src/commands/channels/delete.ts	Renames `channel`→`channelName`, `serial`→`messageSerial`.
src/commands/channels/append.ts	Renames `channel`→`channelName`, `serial`→`messageSerial`.
src/commands/channels/annotations/subscribe.ts	Renames `channel` to `channelName`.
src/commands/channels/annotations/publish.ts	Renames `channel`→`channelName`, `serial`→`messageSerial`, `type`→`annotationType`.
src/commands/channels/annotations/get.ts	Renames `channel`→`channelName`, `serial`→`messageSerial`.
src/commands/channels/annotations/delete.ts	Renames `channel`→`channelName`, `serial`→`messageSerial`, `type`→`annotationType`.
src/commands/bench/subscriber.ts	Renames `channel` to `channelName` throughout.
src/commands/bench/publisher.ts	Renames `channel` to `channelName` throughout (including typed args).
src/commands/apps/update.ts	Renames `id` to `appId` throughout.
src/commands/accounts/switch.ts	Renames `alias` to `accountAlias` throughout.
src/commands/accounts/logout.ts	Renames `alias` to `accountAlias` throughout.
scripts/doc-template.md	Adds a reusable readme template skeleton for doc generation.
package.json	Updates `generate-doc` to use the template and registers the new init hook.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-17T11:25:28Z

+  for (const command of config.commands) {
+    for (const arg of Object.values(command.args)) {
+      arg.name = arg.name.replaceAll(/([a-z])([A-Z])/g, "$1_$2").toLowerCase();
+    }


The camelCase→snake_case transform here duplicates the camelToSnake() logic added in src/help.ts. To avoid divergence (e.g., if the regex ever needs to change to handle acronyms/edge cases), consider extracting a small shared helper (e.g., in src/utils/) and using it in both the init hook and CustomHelp.formatCommand().

claude-code-ably-assistant · 2026-04-17T11:26:57Z

Walkthrough

This PR standardizes positional argument names across all CLI commands, making them more descriptive (channel → channelName, room → roomName, etc.) and ensuring they display as UPPER_SNAKE_CASE in help output. It introduces a camelToSnake() transform in the help class that temporarily patches arg names during formatCommand(), so internal code stays camelCase while help text renders cleanly. A new patch-arg-names init hook handles the same transformation for the doc-generation code path.

Changes

Area	Files	Summary
Commands – Channels	`channels/publish`, `subscribe`, `history`, `inspect`, `occupancy/`, `presence/`, `annotations/*`, `append`, `delete`, `update`	Renamed `channel`→`channelName`, `channels`→`channelNames`, `serial`→`messageSerial`, `type`→`annotationType`
Commands – Rooms	`rooms/messages/`, `rooms/occupancy/`, `rooms/presence/`, `rooms/reactions/`, `rooms/typing/*`	Renamed `room`→`roomName`, `rooms`→`roomNames`, `serial`→`messageSerial`
Commands – Spaces	`spaces/`, `spaces/cursors/`, `spaces/locations/`, `spaces/locks/`, `spaces/members/`, `spaces/occupancy/`	Renamed `space_name`→`spaceName` (also fixes prior underscore inconsistency)
Commands – Accounts/Apps/Stats	`accounts/logout`, `accounts/switch`, `apps/update`, `stats/app`	Renamed `alias`→`accountAlias`, `id`→`appId`
Commands – Push/Integrations/Bench	`push/devices/get`, `push/devices/remove`, `integrations/delete`, `bench/publisher`, `bench/subscriber`	Renamed `device-id`→`deviceId`, `integrationId`→`ruleId`, `channel`→`channelName`
Help	`src/help.ts`	Added `camelToSnake()` helper; patches/restores arg names around `formatCommand()` so oclif uppercases them as `UPPER_SNAKE_CASE`
Hooks	`src/hooks/init/patch-arg-names.ts` (new)	Init hook that applies `snake_case` patching when `GENERATING_DOC=true`, covering the readme generator's code path
Config	`package.json`	Registers new `patch-arg-names` init hook; simplifies `generate-doc` script to use a template file
Docs / Scripts	`scripts/doc-template.md` (new)	Extracts the boilerplate TOC/commands template previously inlined in `generate-doc`
Tests	`test/unit/commands/spaces/spaces.test.ts`	Updated assertion from `LOCKID` → `LOCK_ID` to match the new `camelToSnake` output

Review Notes

Breaking change for scripting users: Positional argument keys are internal to oclif's arg parsing, but any test or script that references arg names by key (e.g. args.channel) will break — reviewers should confirm all call sites referencing old names have been updated.
Patch-and-restore pattern in help.ts: The camelToSnake approach mutates command.args temporarily and restores it — reviewers should check for thread-safety / reentrancy if help formatting is ever called concurrently.
New init hook scope: patch-arg-names only activates when GENERATING_DOC=true; confirm this env var is set in the generate-doc script and that it has no unintended side effects in other workflows.
Test coverage gap: Only one test file was updated. Given 59 command files changed, consider whether integration/E2E tests cover the renamed args end-to-end, especially for multi-arg commands like annotations/delete (channelName, messageSerial, annotationType).
integrationId→ruleId rename: This is a semantic rename (not just formatting). Confirm no external docs, scripts, or API references use the old key name.

claude-code-ably-assistant

Review Summary

File	Status	Notes
`src/help.ts`	OK	`try/finally` restore is correct
`src/hooks/init/patch-arg-names.ts`	Minor	Duplicates `camelToSnake` logic
`src/commands/*/.ts` (59 files)	OK	Mechanical renames, all correct
`test/unit/commands/spaces/spaces.test.ts`	OK	`LOCKID` → `LOCK_ID` updated correctly

One thing worth fixing

camelToSnake logic is duplicated across two files

The regex /([a-z])([A-Z])/g with .toLowerCase() appears as a named function in src/help.ts (line 13–15) and then repeated inline in src/hooks/init/patch-arg-names.ts (line 19). If the transform ever needs to change (e.g., to handle acronyms like appID), one place gets updated and the other doesn't — causing the --help body and the generated readme to silently diverge.

The hook could import camelToSnake from help.ts, or both could import from a small shared utility. Either way, one source of truth.

Everything else looks good

The try/finally pattern in formatCommand() correctly restores arg names after oclif mutates them — no risk of the patched names leaking into subsequent calls.
The hook guards on GENERATING_DOC !== "true" so it is a no-op in normal CLI usage — zero runtime cost per invocation.
Test coverage is sufficient: the bench test's toContain("CHANNEL") still matches the new CHANNEL_NAME output (substring match), and the spaces test was correctly updated to LOCK_ID.
No this.error() calls, no JSON output contract issues, no flag architecture problems.

AndyTWF · 2026-04-17T13:47:11Z

 export default class IntegrationsDeleteCommand extends ControlBaseCommand {
  static args = {
-    integrationId: Args.string({
+    ruleId: Args.string({


In our documentation, rules refers to the conditions set on channel namespaces (forced client IDs etc). Integrations are things like Lambda, Kafka - which is what this command is doing.

I think the flag should therefore be integrationId everywhere.

Sure, will update accordingly 👍

AndyTWF · 2026-04-20T08:39:00Z

+
+  for (const command of config.commands) {
+    for (const arg of Object.values(command.args)) {
+      arg.name = arg.name.replaceAll(/([a-z])([A-Z])/g, "$1_$2").toLowerCase();


Looks like this should be something shared somewhere seeing as we have it in help.ts too

Okay, will update accordingly 👍

Standardized all command arguments

8df424c

- Made argument names more verbose and readable - Made sure they are represented as camelCase in the codebase - Updated utils.ts to display arguments as `SNAKE_CASE`

sacOO7 changed the title ~~Standardize positional argument names to POSIX-compliant snake_case display~~ Standardized all command arguments Apr 17, 2026

sacOO7 changed the title ~~Standardized all command arguments~~ Standardize all command arguments Apr 17, 2026

sacOO7 changed the title ~~Standardize all command arguments~~ Standardize command arguments Apr 17, 2026

Updated generate-doc to create commands with SNAKE_CASE args

75704a1

- Added separate hook to apply camelCase to snake_case transformation - Simplified generate-doc to re-use `doc-template.md`

vercel bot deployed to Preview April 17, 2026 11:17 View deployment

sacOO7 requested a review from Copilot April 17, 2026 11:19

Copilot started reviewing on behalf of sacOO7 April 17, 2026 11:19 View session

sacOO7 marked this pull request as ready for review April 17, 2026 11:25

Copilot AI reviewed Apr 17, 2026

View reviewed changes

sacOO7 requested a review from AndyTWF April 17, 2026 11:29

claude-code-ably-assistant bot reviewed Apr 17, 2026

View reviewed changes

sacOO7 requested a review from umair-ably April 17, 2026 11:31

AndyTWF reviewed Apr 20, 2026

View reviewed changes

Refactored integrations get, update and delete commands

895f41c

vercel bot deployed to Preview April 20, 2026 11:08 View deployment

sacOO7 requested a review from AndyTWF April 20, 2026 11:11

AndyTWF approved these changes Apr 20, 2026

View reviewed changes

sacOO7 force-pushed the fix/standardize-argument-names-output-to-snake-case branch from e53b975 to 895f41c Compare April 20, 2026 16:39

vercel bot deployed to Preview April 20, 2026 16:40 View deployment

sacOO7 merged commit fa80363 into main Apr 20, 2026
11 checks passed

sacOO7 deleted the fix/standardize-argument-names-output-to-snake-case branch April 20, 2026 16:47

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Standardize command arguments#354

Standardize command arguments#354
sacOO7 merged 3 commits intomainfrom
fix/standardize-argument-names-output-to-snake-case

sacOO7 commented Apr 17, 2026 •

edited

Loading

Uh oh!

vercel bot commented Apr 17, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 17, 2026

Uh oh!

sacOO7 Apr 20, 2026

Uh oh!

claude-code-ably-assistant bot commented Apr 17, 2026

Uh oh!

claude-code-ably-assistant bot left a comment

Uh oh!

AndyTWF Apr 17, 2026

Uh oh!

sacOO7 Apr 20, 2026

Uh oh!

sacOO7 Apr 20, 2026

Uh oh!

AndyTWF Apr 20, 2026

Uh oh!

sacOO7 Apr 20, 2026

Uh oh!

sacOO7 Apr 20, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

Conversation

sacOO7 commented Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Arguments

Summary

Uh oh!

vercel bot commented Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

sacOO7 Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

claude-code-ably-assistant bot commented Apr 17, 2026

Walkthrough

Changes

Review Notes

Uh oh!

claude-code-ably-assistant bot left a comment

Choose a reason for hiding this comment

Review Summary

One thing worth fixing

Everything else looks good

Uh oh!

AndyTWF Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

sacOO7 Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

sacOO7 Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

AndyTWF Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

sacOO7 Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

sacOO7 Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

sacOO7 commented Apr 17, 2026 •

edited

Loading

vercel bot commented Apr 17, 2026 •

edited

Loading