SuperAPI AI Directory

ably-new-command

Coding & development

View repository

Updated 10-15 19:49

About this skill

Ably CLI New Command

This skill helps you create new commands for the Ably CLI, including the command file, test file, and any needed index/topic files. The Ably CLI is built on oclif (TypeScript) and has strict conventions that every command must follow.

Step 1: Identify the command pattern

Every command in this CLI falls into one of these patterns. Pick the right one based on what the command does:

Pattern When to use Base class Client Example
Subscribe Long-running event listener AblyBaseCommand Realtime channels subscribe, rooms messages subscribe
Publish/Send Send messages AblyBaseCommand REST or Realtime channels publish, rooms messages send
History Query past messages/events AblyBaseCommand REST channels history, rooms messages history
Get One-shot query for current state AblyBaseCommand REST channels occupancy get, rooms occupancy get
List Enumerate resources via REST API AblyBaseCommand REST channels list, rooms list
Enter Join presence/space then optionally listen AblyBaseCommand Realtime channels presence enter, spaces members enter
REST Mutation One-shot REST mutation (no subscription) AblyBaseCommand REST rooms messages update, rooms messages delete
CRUD Create/read/update/delete via Control API ControlBaseCommand Control API (HTTP) integrations create, queues delete

Specialized base classes — some command groups have dedicated base classes that handle common setup (client lifecycle, cleanup, shared flags):

Pattern Base class When to use Source
Chat commands ChatBaseCommand rooms messages, rooms reactions, rooms typing, rooms occupancy src/chat-base-command.ts
Spaces commands SpacesBaseCommand spaces members, spaces locks, spaces cursors, spaces locations src/spaces-base-command.ts
Stats commands StatsBaseCommand stats app, stats account src/stats-base-command.ts

If your command falls into one of these groups, extend the specialized base class instead of AblyBaseCommand or ControlBaseCommand directly. Exception: if your command only needs a REST client (e.g., history queries that don't enter a space or join a room), you may use AblyBaseCommand directly — the specialized base class is most valuable when the command needs realtime connections, cleanup lifecycle, or shared setup like room.attach() / space.enter().

When to call room.attach() / space.enter()

Not every Chat/Spaces command needs room.attach() or space.enter(). Before adding attachment, check whether the SDK method you're calling requires an active realtime connection or is a pure REST call:

Needs room.attach() Does NOT need room.attach()
Subscribe (realtime listener) Send (REST via chatApi.sendMessage)
Presence enter/get/update/leave Update (REST via chatApi.updateMessage)
Occupancy subscribe Delete (REST via chatApi.deleteMessage)
Typing keystroke/stop Annotate/append (REST mutation)
Reactions send (realtime publish) History queries (REST via chatApi.history)
Reactions subscribe Occupancy get (REST via chatApi.getOccupancy)

How it works in the SDK: Methods that go through this._chatApi.* are REST calls and don't need attachment. Methods that use this._channel.publish(), this._channel.presence.*, or subscribe to channel events require the realtime channel to be attached. Room-level reactions use this._channel.publish() (realtime), but messages send/update/delete use this._chatApi.* (REST).

Rule of thumb: If the SDK method is a one-shot REST call (returns a Promise with a result, no callback/listener), you do NOT need room.attach(). Just call chatClient.rooms.get(roomId) to get the room handle and invoke the method directly. Attaching unnecessarily adds latency and creates a realtime connection that isn't needed.

How to verify: Check the Chat SDK source or typedoc — methods that are REST-based don't require the room to be in an attached state. When in doubt, test without room.attach() — if the SDK method works, attachment isn't needed.

Step 2: Create the command file

File location

Commands map to the filesystem: ably <topic> <subtopic> <action> lives at src/commands/<topic>/<subtopic>/<action>.ts.

If the topic/subtopic doesn't exist yet, you also need an index file at src/commands/<topic>/<subtopic>/index.ts (or src/commands/<topic>/index.ts for top-level topics). The index file is a simple topic descriptor — read an existing one like src/commands/channels/index.ts for the pattern.

Imports and base class

Product API commands (channels, rooms, spaces, presence, pub/sub):

import { Args, Flags } from "@oclif/core";
import * as Ably from "ably";
import chalk from "chalk";

import { AblyBaseCommand } from "../../base-command.js";
import { productApiFlags, clientIdFlag } from "../../flags.js";
import { formatResource, formatSuccess, formatProgress, formatListening, formatTimestamp, formatClientId, formatEventType, formatLabel, formatHeading, formatIndex } from "../../utils/output.js";

Control API commands (apps, integrations, queues, keys, rules, push config):

import { Args, Flags } from "@oclif/core";
import chalk from "chalk";

import { ControlBaseCommand } from "../../control-base-command.js";
import { formatResource, formatSuccess, formatLabel, formatHeading } from "../../utils/output.js";

Chat commands (rooms messages, reactions, typing, occupancy):

import { Args, Flags } from "@oclif/core";
import chalk from "chalk";

import { ChatBaseCommand } from "../../chat-base-command.js";
import { productApiFlags, clientIdFlag } from "../../flags.js";
import { formatResource, formatSuccess, formatProgress, formatListening } from "../../utils/output.js";

Spaces commands (spaces members, locks, cursors, locations):

import { Args, Flags } from "@oclif/core";
import chalk from "chalk";

import { SpacesBaseCommand } from "../../spaces-base-command.js";
import { productApiFlags, clientIdFlag } from "../../flags.js";
import { formatResource, formatSuccess, formatProgress, formatListening, formatClientId } from "../../utils/output.js";

Stats commands (stats app, stats account):

import { Args, Flags } from "@oclif/core";

import { StatsBaseCommand } from "../../stats-base-command.js";

Import depth: These examples use ../../ which is correct for src/commands/<topic>/<action>.ts. For deeper nesting like src/commands/<topic>/<subtopic>/<action>.ts, add one more ../ per level (e.g., ../../../base-command.js). Always count the directory levels from your command file back to src/.

Flag sets

Choose the right combination — never add flags a command doesn't need:

// Product API command
static override flags = {
  ...productApiFlags,          // Always for product API commands
  ...clientIdFlag,             // See below for when to include this
  // command-specific flags here
};

// Control API command — flags come from ControlBaseCommand.globalFlags automatically
static flags = {
  ...ControlBaseCommand.globalFlags,
  app: Flags.string({
    description: "The app ID or name (defaults to current app)",
    required: false,
  }),
  // command-specific flags here
};

Control API helper methods:

  • await this.requireAppId(flags) — resolves and validates the app ID, returns Promise<string> (non-nullable). Calls this.fail() internally if no app found — no manual null check needed.
  • await this.runControlCommand(flags, api => api.method(appId)) — creates the Control API client, executes the call, and handles errors in one step. Returns Promise<T> (non-nullable). Useful for single API calls; for multi-step flows, use this.createControlApi(flags) directly.

When to include clientIdFlag: Add ...clientIdFlag to commands where client identity affects the operation: subscribe, publish, enter, set, acquire, update, delete, append, annotate. The reason is that users may want to test auth scenarios — e.g., "can client B update client A's message?" — so they need the ability to set their client ID. Do NOT add to read-only queries (get, get-all, history, occupancy get) — Ably capabilities are operation-based, not clientId-based, so client identity is irrelevant for pure reads.

For history commands, also use timeRangeFlags:

import { productApiFlags, timeRangeFlags } from "../../flags.js";
import { parseTimestamp } from "../../utils/time.js";

static override flags = {
  ...productApiFlags,
  ...timeRangeFlags,
  // ...
};

For history and list commands, use pagination utilities:

import {
  buildPaginationNext,
  collectPaginatedResults,
  formatPaginationLog,
} from "../../utils/pagination.js";

// In run():
const { items, hasMore, pagesConsumed } = await collectPaginatedResults(firstPage, flags.limit);
const paginationWarning = formatPaginationLog(pagesConsumed, items.length, true); // true for history (billable)
if (paginationWarning && !this.shouldOutputJson(flags)) {
  this.log(paginationWarning);
}
// For JSON output:
const next = buildPaginationNext(hasMore, lastTimestamp); // lastTimestamp only for history commands
this.logJsonResult({ [domainKey]: items, hasMore, ...(next && { next }) }, flags);

For list commands that need client-side filtering (e.g., rooms/spaces with prefix), use collectFilteredPaginatedResults:

import { collectFilteredPaginatedResults } from "../../utils/pagination.js";

const { items, hasMore, pagesConsumed } = await collectFilteredPaginatedResults(
  firstPage, flags.limit, (item) => item.name.startsWith(prefix),
);

Command metadata

export default class TopicAction extends AblyBaseCommand {
  // Imperative mood, sentence case, no trailing period
  static override description = "Subscribe to presence events on a channel";

  static override examples = [
    "$ ably channels presence subscribe my-channel",
    "$ ably channels presence subscribe my-channel --json",
  ];

  static override args = {
    channel: Args.string({
      description: "The channel name",
      required: true,
    }),
  };

Flag naming conventions

  • All kebab-case: --my-flag (never camelCase)
  • --app: "The app ID or name (defaults to current app)"
  • --limit: "Maximum number of results to return (default: N)"
  • --duration: "Automatically exit after N seconds", alias -D
  • --rewind: "Number of messages to rewind when subscribing (default: 0)"
  • Channels use "publish", Rooms use "send" (matches SDK terminology)

Output patterns

The base command provides five logging helpers: this.logProgress(msg, flags), this.logSuccessMessage(msg, flags), this.logListening(msg, flags), this.logHolding(msg, flags), this.logWarning(msg, flags). These do NOT need shouldOutputJson guards. In non-JSON mode they all emit formatted text on stderr. In JSON mode: logProgress and logSuccessMessage are silent (no-ops — the JSON result/event records already convey progress and success), while logListening (status: "listening"), logHolding (status: "holding"), and logWarning (status: "warning") emit structured JSON on stdout. logSuccessMessage should be placed inside the else block after logJsonResult for readability. Only human-readable data output (field labels, headings, record blocks) needs the if/else guard:

// Progress/success/listening — no guard needed, helpers handle both modes
this.logProgress("Attaching to channel: " + formatResource(channelName), flags);

// After success:
this.logSuccessMessage("Subscribed to channel: " + formatResource(channelName) + ".", flags);
this.logListening("Listening for messages.", flags);

// JSON output — nest data under a domain key, not spread at top level.
// Envelope provides top-level: type, command, success.
// One-shot single result — singular domain key:
if (this.shouldOutputJson(flags)) {
  this.logJsonResult({ message: messageData }, flags);
  // → {"type":"result","command":"...","success":true,"message":{...}}
}

// One-shot collection result — plural domain key + optional metadata:
if (this.shouldOutputJson(flags)) {
  this.logJsonResult({ messages: items, total: items.length }, flags);
}

// Streaming events — singular domain key:
if (this.shouldOutputJson(flags)) {
  this.logJsonEvent({ message: messageData }, flags);
  // → {"type":"event","command":"...","message":{...}}
}

Output helper reference — all exported from src/utils/output.ts:

Helper Usage Example
formatProgress(msg) Action in progress — appends ... automatically formatProgress("Attaching to channel")
formatSuccess(msg) Green checkmark — always end with . (period, not !) formatSuccess("Subscribed to channel " + formatResource(name) + ".")
formatWarning(msg) Yellow ⚠ — for non-fatal warnings. Don't prefix with "Warning:" formatWarning("Persistence is automatically enabled.")
formatListening(msg) Dim text — auto-appends "Press Ctrl+C to exit." formatListening("Listening for messages.")
formatResource(name) Cyan — for resource names, never use quotes formatResource(channelName)
formatTimestamp(ts) Dim [timestamp] — for event streams formatTimestamp(isoString)
formatMessageTimestamp(ts) Converts Ably message timestamp to ISO string formatMessageTimestamp(message.timestamp)
formatCountLabel(n, singular, plural?) Cyan count + pluralized label formatCountLabel(3, "message") → "3 messages"
formatLimitWarning(count, limit, name) Yellow warning if results truncated, null otherwise formatLimitWarning(items.length, flags.limit, "items")
formatPresenceAction(action) Returns { symbol, color } for enter/leave/update formatPresenceAction("enter") → { symbol: "✓", color: chalk.green }
formatClientId(id) Blue — for client identity display formatClientId(msg.clientId)
formatEventType(type) Yellow — for event/action type labels formatEventType("enter")
formatLabel(text) Dim with colon — for field labels in structured output formatLabel("Platform") → dim "Platform:"
formatHeading(text) Bold — for record headings in list output formatHeading("Device ID: " + id)
formatIndex(n) Dim bracketed number — for history ordering formatIndex(1) → dim "[1]"

Rules:

  • formatProgress("Action text") — appends ... automatically, never add it manually
  • formatSuccess("Completed action.") — green checkmark, always end with . (period, not !)
  • formatListening("Listening for X.") — dim text, automatically appends "Press Ctrl+C to exit."
  • formatResource(name) — cyan colored, never use quotes around resource names. Exception: do not use formatResource() or any ANSI-producing helper inside this.fail() message strings — fail() passes the message into the JSON error envelope, where ANSI codes would corrupt the output. Use plain quoted strings in error messages instead.
  • formatTimestamp(ts) — dim [timestamp] for event streams
  • formatClientId(id) — blue, for client identity in events
  • formatEventType(type) — yellow, for event/action labels
  • formatLabel(text) — dim with colon, for field labels
  • formatHeading(text) — bold, for record headings in lists
  • formatIndex(n) — dim bracketed number, for history ordering
  • Use this.fail() for all errors (see Error handling below), never this.log(chalk.red(...))
  • Never use console.log or console.error — always this.log() for data or the logging helpers for status messages
  • Use this.logProgress(msg, flags), this.logSuccessMessage(msg, flags), this.logListening(msg, flags), this.logHolding(msg, flags), this.logWarning(msg, flags) for status messages — no shouldOutputJson guard needed. In non-JSON mode all emit to stderr. In JSON mode: logProgress and logSuccessMessage are silent; logListening (status: "listening"), logHolding (status: "holding"), and logWarning (status: "warning") emit structured JSON on stdout
  • Do NOT use the old pattern this.logToStderr(formatProgress/Success/Listening/Warning(...)) — use the helpers instead
  • formatPaginationLog() output still uses this.logToStderr() directly (not a helper yet)
  • formatLabel(), formatHeading(), formatIndex(), formatTimestamp(), formatClientId(), formatEventType() → this.log() inside the non-JSON branch

JSON envelope — reserved keys

logJsonResult(data, flags) and logJsonEvent(data, flags) are shorthand for this.log(this.formatJsonRecord("result"|"event", data, flags)). The envelope wraps data in {type, command, success?, ...data} and silently strips these reserved keys from your data to prevent collisions:

  • type — always stripped (envelope's own type field)
  • command — always stripped (envelope's own command field)
  • success — stripped from "error" records (always false); for "result" records, data's success overrides the envelope's default true

Pitfall: If your event data has a type field (e.g., from an SDK event object), it will be silently dropped. Use a different key name:

// WRONG — event.type is silently stripped by the envelope
this.logJsonEvent({ type: event.type, message, room }, flags);

// CORRECT — use "eventType" to avoid collision with envelope's "type"
this.logJsonEvent({ eventType: event.type, message, room }, flags);

Similarly, for batch results with a success/failure summary, don't use success as the key — it collides with the envelope's success: true:

// WRONG — data's "success" overrides envelope's "success"
this.logJsonResult({ success: errors === 0, published, errors }, flags);

// CORRECT — use "allSucceeded" for the batch summary
this.logJsonResult({ allSucceeded: errors === 0, published, errors }, flags);

Error handling

Choose the right mechanism based on intent:

Intent Method Behavior
Stop the command (fatal error) this.fail(error, flags, component) Logs event, emits JSON error envelope if --json, exits. Returns never — execution stops, no return; needed.
Warn and continue (non-fatal) this.warn() or this.logToStderr() Prints warning, execution continues normally.
Reject inside Promise callbacks reject(new Error(...)) Propagates to await, where the catch block calls this.fail().

All fatal errors flow through this.fail(), which uses CommandError (src/errors/command-error.ts) to preserve Ably error codes and HTTP status codes:

this.fail(): never   ← the single funnel (logs event, emits JSON, exits)
    ↓ internally calls
this.error()         ← oclif exit (ONLY inside fail, nowhere else)

In command run() methods, use this.fail() for all errors. It always exits — returns never, so no return; is needed after calling it. It logs the CLI event, preserves structured error data, emits JSON error envelope when --json is active, and calls this.error() for human-readable output. It accepts an Error object or a plain string message.

Component name casing: All component strings use camelCase — both in this.fail() and logCliEvent(). Single-word components are plain lowercase ("room", "auth"). Multi-word components use camelCase ("channelPublish", "roomPresenceSubscribe"). This matches CLI conventions for log tags and keeps output like [channelPublish] Error: ... readable.

// In catch blocks — pass the error object
try {
  // All fallible calls go inside try-catch, including base class methods
  // like createControlApi, createAblyRealtimeClient, etc.
  const controlApi = this.createControlApi(flags);
  const result = await controlApi.someMethod(appId, data);
  // ...
} catch (error) {
  this.fail(
    error,
    flags,
    "channelPublish",     // camelCase — e.g., "channelPublish", "presenceEnter"
    { channel: args.channel },  // optional context for logging
  );
}

// logCliEvent uses the same camelCase convention
this.logCliEvent(flags, "room", "attaching", `Attaching to room ${roomName}`);
this.logCliEvent(flags, "presence", "subscribed", "Subscribed to presence events");

// For validation / early exit — pass a string message (no return; needed)
if (!appId) {
  this.fail(
    'No app specified. Use --app flag or select an app with "ably apps switch"',
    flags,
    "app",
  );
}

In base class utility methods (e.g., createControlApi, createAblyRealtimeClient, parseJsonFlag), use this.fail() for fatal errors — the same pattern as in command run() methods. The fail() method returns never, so TypeScript knows execution stops and won't require a return value after the call.

Do NOT use this.error() directly — it is an internal implementation detail of fail. Calling this.error() directly skips event logging and doesn't respect --json mode.

Safe to use this.fail() in both try and catch — this.fail() automatically detects if the error was already processed by a prior this.fail() call (by checking for the oclif property) and re-throws it instead of double-processing. This means you can freely call this.fail() for validation inside a try block without worrying about the catch block calling this.fail() again.

Error hints — fail() appends a CLI-specific hint from src/utils/errors.ts if one exists for the Ably error code. If your command may surface an error code not yet in the hints map, fetch https://ably.com/docs/platform/errors/codes using WebFetch to get the official description before adding a hint. Do NOT rely on memory or assumptions about what an error code means — always fetch the doc. Hints must only contain actionable CLI advice, not restate the upstream error message.

JSON error envelope structure — CommandError.toJsonData(hint?) nests error details under an error object: { error: { message, code?, statusCode?, hint? }, ...context }. Context fields (e.g., channel, room) sit alongside the error key, not inside it.

Inline error extraction — For commands that report per-item errors inline (batch publish, connections test), use extractErrorInfo(error) from src/utils/errors.ts instead of this.fail(). It returns { message, code?, statusCode?, href? } — suitable for embedding in result objects:

import { extractErrorInfo } from "../../utils/errors.js";
// In a batch loop:
const result = { error: extractErrorInfo(error), index, success: false };

Pattern-specific implementation

Read references/patterns.md for the full implementation template matching your pattern (Subscribe, Publish/Send, History, Enter/Presence, List, CRUD/Control API). Each template includes the correct flags, run() method structure, and output conventions.

Step 3: Create the test file

Read references/testing.md for the full test scaffold matching your command type (Realtime mock, REST mock, Control API with nock, E2E subscribe, E2E CRUD). Test files go at test/unit/commands/<path-matching-command>.test.ts.

Step 4: Create index files if needed

If you're adding a new topic or subtopic, create an index file using BaseTopicCommand:

// src/commands/push/index.ts
import { BaseTopicCommand } from "../../base-topic-command.js";

export default class Push extends BaseTopicCommand {
  protected topicName = "push";
  protected commandGroup = "Push notification";

  static override description = "Manage push notifications";

  static override examples = [
    "<%= config.bin %> <%= command.id %> devices list",
    "<%= config.bin %> <%= command.id %> config show",
  ];
}

For nested subtopics (e.g., push devices):

// src/commands/push/devices/index.ts
import { BaseTopicCommand } from "../../../base-topic-command.js";

export default class PushDevices extends BaseTopicCommand {
  protected topicName = "push:devices";
  protected commandGroup = "Push device";

  static override description = "Manage push device registrations";

  static override examples = [
    "<%= config.bin %> <%= command.id %> list",
    "<%= config.bin %> <%= command.id %> get DEVICE_ID",
  ];
}

The topicName must match the oclif command ID prefix (colons for nesting). The commandGroup is used in the help display as "Ably {commandGroup} commands:".

Step 5: Web CLI restrictions

If the new command shouldn't be available in the web CLI, add it to the appropriate array in src/base-command.ts:

  • WEB_CLI_RESTRICTED_COMMANDS — for commands that don't make sense in a web context
  • WEB_CLI_ANONYMOUS_RESTRICTED_COMMANDS — for commands that expose account/app data
  • INTERACTIVE_UNSUITABLE_COMMANDS — for commands that don't work in interactive mode

Security rule: The web CLI runs on a shared server — any command that reads files from the filesystem reads the server's files, not the user's local machine, which can expose server contents. There is no file-upload mechanism in the web CLI to transfer local files. So for any command that reads files, choose one of:

  1. Block the command — add it to WEB_CLI_RESTRICTED_COMMANDS when the entire command is meaningless without local files (e.g. push config set-fcm/set-apns exist only to upload a credentials file).
  2. Disable just the file read — when the command is still useful with inline input (e.g. push publish/batch-publish/devices save accept JSON inline), load the input through the this.resolveJsonInput(input, label, flags, component) base-command helper. It reads @file/path inputs from disk in local mode but, in web CLI mode, treats the input as literal data and rejects @file references — so the command keeps working without a server-side file-read sink. Never call fs.readFileSync directly on flag/arg values; always go through resolveJsonInput so the web-CLI restriction is inherited rather than re-implemented (and re-missed) per command.

Step 6: Validate

After creating command and test files, always run:

pnpm prepare        # Build + update manifest
pnpm generate-doc       # Regenerate command documentation
pnpm exec eslint .  # Lint (must be 0 errors)
pnpm test:unit      # Run tests

Maintaining this skill

This skill is the source of truth for command conventions. The review skills (ably-review, ably-codebase-review) and CLAUDE.md reference the same patterns. If you change conventions here — or if the underlying source code changes (base classes, helpers, flags, error handling) — update all three locations:

  1. This file (SKILL.md) and its references/ templates
  2. ably-review/SKILL.md and ably-codebase-review/SKILL.md — review checks must match current patterns
  3. .claude/CLAUDE.md — project-level docs that all agents see

See the "Keeping Skills Up to Date" section in CLAUDE.md for the full list of triggers.

Checklist

  • Command file at correct path under src/commands/
  • Correct base class (AblyBaseCommand, ControlBaseCommand, ChatBaseCommand, SpacesBaseCommand, or StatsBaseCommand)
  • Correct flag set (productApiFlags vs ControlBaseCommand.globalFlags)
  • clientIdFlag only if command needs client identity
  • Human data output wrapped in if (!this.shouldOutputJson(flags)) — but logProgress, logSuccessMessage, logListening, logWarning helpers do NOT need guards
  • Status messages use base command helpers (this.logProgress, this.logSuccessMessage, this.logListening, this.logWarning) — NOT this.logToStderr(formatProgress/Success/Listening/Warning(...))
  • Output formatters used correctly for data display (formatResource, formatTimestamp, formatClientId, formatEventType, formatLabel, formatHeading, formatIndex)
  • logSuccessMessage() messages end with . (period)
  • Non-JSON data output uses multi-line labeled blocks (see patterns.md "Human-Readable Output Format"), not tables or custom grids
  • Non-JSON output exposes all available SDK fields (same data as JSON mode, omitting only null/empty values)
  • SDK types imported directly (import type { CursorUpdate } from "@ably/spaces") — no local interface redefinitions of SDK types (display interfaces in src/utils/ are fine)
  • Field coverage checked against SDK type definitions (node_modules/ably/ably.d.ts, node_modules/@ably/spaces/dist/mjs/types.d.ts)
  • Subscribe commands do NOT fetch initial state — they only listen for new events (use get-all for current state)
  • Resource names use formatResource(name), never quoted
  • JSON output uses logJsonResult() (one-shot) or logJsonEvent() (streaming), not direct formatJsonRecord()
  • JSON data nested under a domain key (singular for events/single items, plural for collections) — not spread at top level (see patterns.md "JSON Data Nesting Convention")
  • room.attach() / space.enter() only called when the SDK method requires a realtime connection (subscribe, send, presence) — NOT for REST mutations (update, delete, annotate, history)
  • Subscribe/enter commands use this.waitAndTrackCleanup(flags, component, flags.duration) (not waitUntilInterruptedOrTimeout)
  • Error handling uses this.fail() exclusively, not this.error() or this.log(chalk.red(...))
  • Component strings are camelCase: single-word lowercase ("room", "auth"), multi-word camelCase ("channelPublish", "roomPresenceSubscribe")
  • At least one --json example in static examples
  • Test file at matching path under test/unit/commands/
  • Tests use correct mock helper (getMockAblyRealtime, getMockAblyRest, nock)
  • Tests don't pass auth flags — MockConfigManager handles auth
  • Subscribe tests auto-exit via env var (ABLY_CLI_DEFAULT_DURATION: "0.25" in vitest.config.ts) — do NOT pass --duration to runCommand()
  • Tests use standardHelpTests(), standardArgValidationTests(), standardFlagTests() from test/helpers/standard-tests.ts
  • Control API tests use nockControl(), controlApiCleanup() from test/helpers/control-api-test-helpers.ts
  • Control API tests use standardControlApiErrorTests() for 401/500/network error tests in the describe("error handling", ...) block
  • Control API response bodies use mockApp(), mockKey(), mockRule(), mockQueue(), mockNamespace(), mockStats() from test/fixtures/control-api.ts where applicable
  • Index file created if new topic/subtopic
  • pnpm prepare && pnpm exec eslint . && pnpm test:unit passes