Agent Skills: CLI User Experience 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

| Tool | Purpose | Location | |------|---------|----------| | chalk | Colored terminal output | Via src/cli/console.ts | | ora | Spinner/progress indicators | src/cli/progress.ts | | @inquirer/prompts | Interactive user prompts | Commands layer | | tslog | Structured logging | Internal logging |

Console Module

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

| Method | Color | Prefix | Use For | |--------|-------|--------|---------| | error() | Red | x | Error messages | | success() | Green | check | Success confirmations | | warning() | Yellow | warn | Warnings, degraded results | | hint() | Cyan | bulb | Actionable suggestions | | important() | Bold | - | Key information | | info() | Blue | i | Informational messages | | code() | Gray bg | - | Code/command snippets |

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:

| Prompt | Import | Use For | |--------|--------|---------| | confirm | @inquirer/prompts | Yes/no decisions, destructive action guards | | select | @inquirer/prompts | Single choice from options | | checkbox | @inquirer/prompts | Multi-select (e.g., entity selection) | | input | @inquirer/prompts | Text input with validation | | password | @inquirer/prompts | Masked input for tokens/secrets |

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

Reporter Patterns

Three main reporters in src/cli/reporters/:

| Reporter | Purpose | Key Output | |----------|---------|------------| | deployment-reporter | Deploy results | Table with created/updated/deleted/failed counts | | diff reporter | Diff results | + create (green), ~ update (blue), - delete (red) | | duplicate reporter | Validation issues | Duplicate identifiers with locations |

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

| Mistake | Fix | |---------|-----| | Using raw console.log | Import and use console from @/cli/console | | Missing progress feedback | Add ora spinner for any async operation | | Raw exit codes (process.exit(1)) | Use ExitCodes.GENERAL_ERROR constants | | Blocking prompts in CI | Check for --yes flag or CI env var to skip prompts | | No suggestions on errors | Always add console.hint() with next steps | | Debug output in production | Use tslog with appropriate log levels |

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