add-command

Adding a New CLI Command or Subcommand

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

1. Mock API (src/__tests__/helpers/mock-api.ts)

Add a mock for each new SDK method in createMockApi(). Place it in the correct entity group.

• List/read methods: .mockResolvedValue({ results: [], nextCursor: null }) or appropriate empty default
• Mutation methods: vi.fn() (no default return needed)

2. Spinner Messages (src/lib/api/core.ts)

Add an entry to API_SPINNER_MESSAGES for each new SDK method.

Color convention:

• blue — read/fetch operations
• green — create/join operations
• yellow — update/delete/archive mutations

3. 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 (td auth login --read-only).

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

4. Agent-Friendly Design Checklist

Every new command should satisfy these properties. They ensure the CLI works well for both humans and AI agents. See 7 Principles for Agent-Friendly CLIs for background.

1. Non-interactive by default — All input via flags, positional args, or --stdin. Never use readline, prompt(), or block waiting for TTY input. When a required argument is missing, call cmd.help() and return — don't prompt.

2. Structured, parseable output — Data commands must support --json (and --ndjson for lists). Results go to stdout, diagnostics to stderr. Spinners auto-suppress when !process.stdout.isTTY (see src/lib/spinner.ts). Exit code 0 on success, non-zero on failure.