add-command

name	add-command
description	Guide for adding new CLI commands or subcommands to comms-cli. Use when implementing new SDK endpoints, adding subcommands to existing command groups, or extending CLI functionality.

Adding a New CLI Command or Subcommand

Follow this checklist when adding new commands. Each step references the exact file to modify.

1. Spinner Messages (src/lib/api.ts)

Add an entry to API_SPINNER_MESSAGES for each new SDK method.

Color convention:

• blue — read/fetch operations (e.g., loading threads, listing channels)
• green — create/join operations (e.g., creating a thread, starting a conversation)
• yellow — update/delete/archive mutations (e.g., muting, deleting, archiving)

2. Read-Only Permissions (src/lib/permissions.ts)

If the new command uses a read-only SDK method (e.g., getXxx, listXxx), add it to the KNOWN_SAFE_API_METHODS set. This set uses a default-deny approach: any method not listed is treated as mutating and will be blocked when the CLI is authenticated with a read-only OAuth token (tdc auth login --read-only).

• Read-only methods (fetch/list/view): add to KNOWN_SAFE_API_METHODS
• Mutating methods (create/update/delete/archive/mute): do NOT add — they are blocked by default, which is the correct behavior

3. Command Implementation (src/commands/<entity>/)

Commands with multiple subcommands use a folder-based structure:

src/commands/<entity>/
  index.ts          # registerXxxCommand — creates parent cmd, wires subcommands
  list.ts           # async function listXxx(...) — one file per subcommand
  view.ts           # async function viewXxx(...)
  create.ts         # async function createXxx(...)
  helpers.ts        # shared constants/utilities used by multiple subcommands (optional)