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, returnsPromise<string>(non-nullable). Callsthis.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. ReturnsPromise<T>(non-nullable). Useful for single API calls; for multi-step flows, usethis.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 manuallyformatSuccess("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 useformatResource()or any ANSI-producing helper insidethis.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 streamsformatClientId(id)— blue, for client identity in eventsformatEventType(type)— yellow, for event/action labelsformatLabel(text)— dim with colon, for field labelsformatHeading(text)— bold, for record headings in listsformatIndex(n)— dim bracketed number, for history ordering- Use
this.fail()for all errors (see Error handling below), neverthis.log(chalk.red(...)) - Never use
console.logorconsole.error— alwaysthis.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 — noshouldOutputJsonguard needed. In non-JSON mode all emit to stderr. In JSON mode:logProgressandlogSuccessMessageare silent;logListening(status: "listening"),logHolding(status: "holding"), andlogWarning(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 usesthis.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 owntypefield)command— always stripped (envelope's owncommandfield)success— stripped from"error"records (alwaysfalse); for"result"records, data'ssuccessoverrides the envelope's defaulttrue
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 contextWEB_CLI_ANONYMOUS_RESTRICTED_COMMANDS— for commands that expose account/app dataINTERACTIVE_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:
- Block the command — add it to
WEB_CLI_RESTRICTED_COMMANDSwhen the entire command is meaningless without local files (e.g.push config set-fcm/set-apnsexist only to upload a credentials file). - Disable just the file read — when the command is still useful with inline input (e.g.
push publish/batch-publish/devices saveaccept JSON inline), load the input through thethis.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@filereferences — so the command keeps working without a server-side file-read sink. Never callfs.readFileSyncdirectly on flag/arg values; always go throughresolveJsonInputso 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:
- This file (
SKILL.md) and itsreferences/templates ably-review/SKILL.mdandably-codebase-review/SKILL.md— review checks must match current patterns.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, orStatsBaseCommand) - Correct flag set (
productApiFlagsvsControlBaseCommand.globalFlags) -
clientIdFlagonly if command needs client identity - Human data output wrapped in
if (!this.shouldOutputJson(flags))— butlogProgress,logSuccessMessage,logListening,logWarninghelpers do NOT need guards - Status messages use base command helpers (
this.logProgress,this.logSuccessMessage,this.logListening,this.logWarning) — NOTthis.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 insrc/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-allfor current state) - Resource names use
formatResource(name), never quoted - JSON output uses
logJsonResult()(one-shot) orlogJsonEvent()(streaming), not directformatJsonRecord() - 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)(notwaitUntilInterruptedOrTimeout) - Error handling uses
this.fail()exclusively, notthis.error()orthis.log(chalk.red(...)) - Component strings are camelCase: single-word lowercase (
"room","auth"), multi-word camelCase ("channelPublish","roomPresenceSubscribe") - At least one
--jsonexample instatic examples - Test file at matching path under
test/unit/commands/ - Tests use correct mock helper (
getMockAblyRealtime,getMockAblyRest,nock) - Tests don't pass auth flags —
MockConfigManagerhandles 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()fromtest/helpers/standard-tests.ts - Control API tests use
nockControl(),controlApiCleanup()fromtest/helpers/control-api-test-helpers.ts - Control API tests use
standardControlApiErrorTests()for 401/500/network error tests in thedescribe("error handling", ...)block - Control API response bodies use
mockApp(),mockKey(),mockRule(),mockQueue(),mockNamespace(),mockStats()fromtest/fixtures/control-api.tswhere applicable - Index file created if new topic/subtopic
-
pnpm prepare && pnpm exec eslint . && pnpm test:unitpasses