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()

• 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

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

KNOWN_SAFE_API_METHODS

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.

3. Fail fast with actionable errors — Use

   CliError

   with a specific error code, a message naming the exact problem, and hints that include correct invocation syntax, valid values, or example commands. Validate all inputs before making API calls.

4. Safe retries and explicit mutation boundaries — Mutating commands support

   --dry-run

   . Destructive + irreversible commands require

   --yes

   . Create commands return the entity ID (use

   isQuiet()

   for bare ID output for scripting, e.g.

   id=$(td task add "Buy milk" -q)

   ).

5. Progressive help discovery — Parent command groups include

   .addHelpText('after', ...)

   with 2–3 concrete examples. Every

   .description()

   is a clear one-line purpose statement. When a required positional arg is missing, show help via

   cmd.help()

   .

6. Composable and predictable structure — Use consistent subcommand verbs (

   list

   /

   view

   /

   create

   /

   update

   /

   delete

   /

   browse

   ). Use consistent flag names across entities (

   --project <ref>

   ,

   --json

   ,

   --dry-run

   ,

   --yes

   ,

   --limit

   ,

   --cursor

   ,

   --all

   ). Support

   --stdin

   for text content where applicable (see

   readStdin()

   in

   src/lib/stdin.ts

   ).

7. Bounded, high-signal responses — List commands use

   paginate()

   from

   src/lib/pagination.ts

   with

   --limit <n>

   ,

   --cursor

   , and

   --all

   flags. When results are truncated,

   formatNextCursorFooter()

   tells the user how to fetch more. JSON output uses

   formatJson()

   or

   formatPaginatedJson()

   to return essential fields by default, passing the

   --full

   flag for complete output.

5. 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)

• index.ts: Imports all subcommand handlers, creates the Commander tree, exports

  registerXxxCommand

• Subcommand files: Export one async action handler + any option interfaces. Use

  ../../lib/

  for lib imports. No Commander imports (only index.ts uses Commander).
• helpers.ts: Only needed when multiple subcommands share a utility/constant.

Single-subcommand commands (e.g.,

add.ts

today.ts

Adding a subcommand to an existing command

1. Create a new file

   src/commands/<entity>/<action>.ts

   with the handler function
2. Import and wire it in

   src/commands/<entity>/index.ts

Flag conventions

--json

--ndjson

--json

formatJson

--dry-run

--dry-run

--yes

--dry-run

--dry-run

--yes

--limit <n>

--cursor

--all

--json

--ndjson

--json

--ndjson

The

--quiet

-q

id=$(td task add "Buy milk" -q)

Error handling

Always use

CliError

src/lib/errors.ts

throw new Error(...)

import { CliError } from '../../lib/errors.js'

throw new CliError('ERROR_CODE', 'User-facing message', ['Optional hint'])

When adding a new error code, add it to the

ErrorCode

src/lib/errors.ts

To make errors actionable for agents:

• The

  message

  must name the specific problem (not generic "invalid input")
• The

  hints

  array should include at least one of: correct invocation syntax, valid values, or a working example command
• Validate all flag constraints and input early — before any API calls. If flags conflict, throw

  CliError('CONFLICTING_OPTIONS', ...)

  immediately

ID resolution

• resolveXxxRef(api, ref)

  — when the user knows the entity by name (projects, tasks, labels). Add new wrappers in

  refs.ts

  —

  resolveRef

  is private.

• lenientIdRef(ref, 'entity')

  — when there is no list endpoint for lookup, or the user can't access the entity yet (e.g., comments, reminders, joining an unjoined project)
• Context-scoped resolvers (

  resolveSectionId

  ,

  resolveParentTaskId

  ,

  resolveWorkspaceRef

  ) — when resolving a name within a parent context (e.g., a section name within a specific project). Each has custom logic in

  refs.ts

  .

Subcommand registration pattern

const myCmd = parent
    .command('my-action [ref]')
    .description('Do something')
    .option('--json', 'Output as JSON')
    .option('--dry-run', 'Preview what would happen without executing')
    .action((ref, options) => {
        if (!ref) {
            myCmd.help()
            return
        }
        return myAction(ref, options)
    })

The variable assignment (

const myCmd = ...

.action()

myCmd.help()

Help text quality:

• Parent command groups (the

  registerXxxCommand

  function) should include

  .addHelpText('after', ...)

  with 2–3 concrete invocation examples
• Every

  .description()

  string should be a clear one-line purpose — agents read this to decide which subcommand to call
• The

  if (!ref) { cmd.help(); return }

  pattern ensures the command never blocks when a required argument is missing

6. Accessibility (

src/lib/output.ts

)

The CLI supports accessible mode via

isAccessible()

TD_ACCESSIBLE=1

--accessible

When to add accessible alternatives

• Color-coded status/severity: If color conveys meaning (e.g., green=good, red=bad), add a text prefix or label in accessible mode so the meaning is available without color. Example:

  formatHealthStatus

  adds

  [+]

  ,

  [!]

  ,

  [!!]

  prefixes.
• ASCII art / visual bars: Omit entirely in accessible mode — screen readers read each character individually (e.g.,

  ====----

  becomes "equals equals equals equals dash dash dash dash"). Show only the numeric value instead.
• Decorative symbols: Stars, checkmarks, or icons used alongside color should have text equivalents. Example: favorites get

  ★

  only in accessible mode since the yellow color already signals it visually.

When you don't need to do anything

• Text that is already descriptive: Status names like

  ON_TRACK

  ,

  COMPLETED

  are self-explanatory — color just reinforces them. Still consider adding indicator prefixes for severity.
• Plain numbers and dates: Already accessible.
• Dim/styled labels:

  chalk.dim()

  for secondary info is fine — screen readers ignore styling.

Pattern

import { isAccessible } from '../lib/output.js'

// For color-coded values: add text prefix in accessible mode
const a11y = isAccessible()
const prefix = a11y ? '[!] ' : ''
console.log(chalk.yellow(`${prefix}AT_RISK`))

// For visual bars: skip entirely in accessible mode
if (isAccessible()) {
    console.log(`${percent}%`)
} else {
    console.log(`[${'='.repeat(filled)}${'-'.repeat(empty)}] ${percent}%`)
}

If adding a new shared formatter to

output.ts

Record<ExactType, ...>

Record<string, ...>

7. Tests (

src/__tests__/<entity>.test.ts

)

Follow the existing pattern: mock

getApi

program.parseAsync()

Always test:

• Happy path (correct output, correct API call)

• INVALID_REF

  rejection for

  lenientIdRef

  commands (plain text like

  "Planning"

  should fail)

• --dry-run

  for mutating commands (API method should NOT be called, preview text shown)

• --json

  output where applicable

8. Skill Content (

src/lib/skills/content.ts

)

Update

SKILL_CONTENT

• Command examples in the entity's

  ### Section

  block
• Quick Reference if adding a top-level command
• Mutating

  --json

  list if the command returns an entity

• --dry-run

  list if applicable

9. Sync Skill File

After all code changes are complete:

npm run sync:skill

This builds the project and regenerates

skills/todoist-cli/SKILL.md

npm run check:skill-sync

10. Verify

npm run type-check
npm test
npm run check