implementing-cli-patterns

CLI User Experience Patterns

Overview

Implement consistent, user-friendly CLI interactions using the project's console module, progress tracking, and reporter patterns. All CLI output should go through src/cli/console.ts rather than raw console.log.

When to Use

• Implementing command output formatting
• Adding progress indicators for operations
• Creating interactive user prompts
• Formatting error messages for the terminal
• Designing reporter output for deploy/diff results
• Not for: Business logic, GraphQL operations, or service layer code

CLI Stack

Console Module

Located in src/cli/console.ts. Always use this instead of raw console.log:

Import: import { console } from '@/cli/console';

Progress Indicators

• Single operations: Use ora spinner with .start(), .succeed(), .fail()
• Bulk operations: Use BulkOperationProgress from src/cli/progress.ts for progress bars with success/failure tracking

Interactive Prompts

Available prompt types from @inquirer/prompts:

See references/prompt-patterns.md for full examples.

Reporter Patterns

Three main reporters in src/cli/reporters/:

See references/reporter-patterns.md for full implementations.

Error Message Formatting

Two error formatters in the project:

• formatError(error: BaseError): General errors with code, context, and suggestions
• formatGraphQLError(error: GraphQLError): GraphQL-specific with operation name and path

Pattern: Show error message, then optional code/context in gray, then actionable suggestions via console.hint().

Exit Codes

export const ExitCodes = {
  SUCCESS: 0,
  GENERAL_ERROR: 1,
  VALIDATION_ERROR: 2,
  NETWORK_ERROR: 3,
  AUTH_ERROR: 4,
  CONFLICT_ERROR: 5,
} as const;

Always use named exit codes, never raw numbers.

Best Practices

• Use src/cli/console.ts for all output (never raw console.log)
• Provide progress feedback for any operation over ~1 second
• Include actionable suggestions with every error message
• Confirm destructive operations with confirm prompt
• Support non-interactive mode (skip prompts in CI/headless)
• Use consistent color semantics (green=success, red=error, yellow=warning)

Common Mistakes

References

• {baseDir}/src/cli/console.ts - Console module
• {baseDir}/src/cli/progress.ts - Progress tracking
• {baseDir}/src/cli/reporters/ - Reporter implementations
• references/reporter-patterns.md - Full reporter code
• references/prompt-patterns.md - Full prompt examples

Related Skills

• Complete entity workflow: See adding-entity-types for CLI integration patterns
• Error handling: See reviewing-typescript-code for error message standards

Quick Reference Rule

For a condensed quick reference, see .claude/rules/cli-development.md (automatically loaded when editing src/cli/**/*.ts and src/commands/**/*.ts files).