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