or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

arguments.mdcommands.mderrors.mdhelp.mdindex.mdoptions.md
tile.json

help.mddocs/

Help System

Comprehensive help generation and customization system with support for custom formatting, output configuration, help text positioning, extensive styling options, and complete control over help display behavior.

Capabilities

Help Class

Handles help text generation and formatting with extensive customization options.

/**
 * Help text generation and formatting system
 */
class Help {
  /**
   * Initialize a new Help instance
   */
  constructor();
  
  // Configuration properties
  helpWidth?: number;           // Help text width for wrapping
  minWidthToWrap: number;       // Minimum width before wrapping (default: 40)
  sortSubcommands: boolean;     // Whether to sort subcommands in help
  sortOptions: boolean;         // Whether to sort options in help
  showGlobalOptions: boolean;   // Whether to show global options in subcommand help
  
  // Content generation methods
  visibleCommands(cmd: Command): Command[];
  visibleOptions(cmd: Command): Option[];
  visibleGlobalOptions(cmd: Command): Option[];
  visibleArguments(cmd: Command): Argument[];
  
  // Formatting methods
  formatHelp(cmd: Command, helper: Help): string;
  formatItem(term: string, termWidth: number, description: string, helper: Help): string;
  formatItemList(heading: string, items: string[], helper: Help): string[];
  
  // Grouping and sorting
  groupItems<T extends Command | Option>(
    unsortedItems: T[], 
    visibleItems: T[], 
    getGroup: (item: T) => string
  ): Map<string, T[]>;
  compareOptions(a: Option, b: Option): number;
  
  // Display width and styling
  displayWidth(str: string): number;
  styleTitle(title: string): string;
  styleUsage(str: string): string;
  styleCommandText(str: string): string;
  styleCommandDescription(str: string): string;
  styleOptionDescription(str: string): string;
}

Command Help Integration

Help system integration with Command class for comprehensive help management.

interface Command {
  /**
   * Create Help instance (can be overridden for customization)
   * @returns New Help instance
   */
  createHelp(): Help;
  
  /**
   * Configure help system properties
   * @param configuration - Help configuration object
   * @returns this command for chaining
   */
  configureHelp(configuration: HelpConfiguration): this;
  
  /**
   * Get current help configuration
   * @returns Current help configuration
   */
  configureHelp(): HelpConfiguration;
  
  /**
   * Configure output streams and behavior
   * @param configuration - Output configuration object
   * @returns this command for chaining
   */
  configureOutput(configuration: OutputConfiguration): this;
  
  /**
   * Get current output configuration
   * @returns Current output configuration
   */
  configureOutput(): OutputConfiguration;
}

Help Option Configuration

Configure the built-in help option and its behavior.

interface Command {
  /**
   * Configure or disable the built-in help option
   * @param flags - Help option flags (default: '-h, --help')
   * @param description - Help option description
   * @returns this command for chaining
   */
  helpOption(flags?: string | boolean, description?: string): this;
  
  /**
   * Add a custom help option
   * @param option - Custom Option instance for help
   * @returns this command for chaining
   */
  addHelpOption(option: Option): this;
}

Usage Examples:

// Customize help option
program.helpOption('-H, --help', 'display help for command');

// Disable help option
program.helpOption(false);

// Custom help option
const customHelp = createOption('--usage', 'show usage information');
program.addHelpOption(customHelp);

Help Command Configuration

Configure automatic help commands for applications with subcommands.

interface Command {
  /**
   * Configure help command
   * @param nameAndArgs - Help command specification
   * @param description - Help command description
   * @returns this command for chaining
   */
  helpCommand(nameAndArgs: string, description?: string): this;
  
  /**
   * Enable or disable help command
   * @param enable - Whether to enable help command
   * @returns this command for chaining
   */
  helpCommand(enable: boolean): this;
  
  /**
   * Add a custom help command
   * @param cmd - Custom Command instance for help
   * @returns this command for chaining
   */
  addHelpCommand(cmd: Command): this;
}

Usage Examples:

// Customize help command
program.helpCommand('help [command]', 'display help for command');

// Disable help command
program.helpCommand(false);

// Force enable help command even without subcommands
program.helpCommand(true);

// Custom help command
const customHelpCommand = createCommand('usage')
  .description('show detailed usage information')
  .action((cmdName) => {
    if (cmdName) {
      const cmd = program.commands.find(c => c.name() === cmdName);
      if (cmd) cmd.help();
    } else {
      program.help();
    }
  });
  
program.addHelpCommand(customHelpCommand);

Help Display and Output

Display help text and control output behavior.

interface Command {
  /**
   * Display help and exit
   * @param context - Help display context
   */
  help(context?: HelpContext): never;
  
  /**
   * Output help without exiting
   * @param context - Help display context
   */
  outputHelp(context?: HelpContext): void;
  
  /**
   * Get help text as string
   * @param context - Help display context
   * @returns Formatted help text
   */
  helpInformation(context?: HelpContext): string;
  
  /**
   * Display help after errors
   * @param displayHelp - Whether to show help, or custom help text
   * @returns this command for chaining
   */
  showHelpAfterError(displayHelp?: boolean | string): this;
  
  /**
   * Display command suggestions after errors
   * @param displaySuggestion - Whether to show suggestions
   * @returns this command for chaining
   */
  showSuggestionAfterError(displaySuggestion?: boolean): this;
}

interface HelpContext {
  /** Whether help is being displayed due to an error */
  error: boolean;
}

Usage Examples:

// Display help programmatically
if (program.args.length === 0) {
  program.outputHelp();
  process.exit(1);
}

// Get help text for processing
const helpText = program.helpInformation();
console.log('Help length:', helpText.length);

// Show help after parsing errors
program.showHelpAfterError('Use --help for usage information');

// Disable command suggestions
program.showSuggestionAfterError(false);

Custom Help Text

Add custom text to help output at various positions.

interface Command {
  /**
   * Add custom help text
   * @param position - Where to add the text
   * @param text - Text to add or function returning text
   * @returns this command for chaining
   */
  addHelpText(position: AddHelpTextPosition, text: string): this;
  addHelpText(position: AddHelpTextPosition, text: (context: AddHelpTextContext) => string): this;
}

type AddHelpTextPosition = 'beforeAll' | 'before' | 'after' | 'afterAll';

interface AddHelpTextContext {
  error: boolean;
  command: Command;
}

Usage Examples:

program
  .addHelpText('beforeAll', 'My CLI Application v1.0.0\n')
  .addHelpText('before', 'This tool processes files and generates reports.')
  .addHelpText('after', '\nExamples:\n  $ mycli process file.txt\n  $ mycli --verbose process *.txt')
  .addHelpText('afterAll', '\nFor more information, visit: https://example.com/docs');

// Dynamic help text
program.addHelpText('after', (context) => {
  if (context.error) {
    return '\nSee --help for correct usage.';
  }
  return '\nFor more examples, run: mycli examples';
});

Help Content Methods

Methods for retrieving and formatting help content components.

interface Help {
  /**
   * Prepare help context (called before formatting)
   * @param contextOptions - Context configuration
   */
  prepareContext(contextOptions: { error?: boolean; helpWidth?: number; outputHasColors?: boolean }): void;
  
  /**
   * Get visible subcommands for help display
   * @param cmd - Command to get subcommands for
   * @returns Array of visible subcommands
   */
  visibleCommands(cmd: Command): Command[];
  
  /**
   * Get visible options for help display
   * @param cmd - Command to get options for
   * @returns Array of visible options
   */
  visibleOptions(cmd: Command): Option[];
  
  /**
   * Get visible global options for help display
   * @param cmd - Command to get global options for
   * @returns Array of visible global options
   */
  visibleGlobalOptions(cmd: Command): Option[];
  
  /**
   * Get visible arguments for help display
   * @param cmd - Command to get arguments for
   * @returns Array of visible arguments
   */
  visibleArguments(cmd: Command): Argument[];
}

Help Formatting Methods

Methods for generating formatted help text components.

interface Help {
  /**
   * Get command usage string
   * @param cmd - Command to format usage for
   * @returns Usage string
   */
  commandUsage(cmd: Command): string;
  
  /**
   * Get command description
   * @param cmd - Command to get description for
   * @returns Command description
   */
  commandDescription(cmd: Command): string;
  
  /**
   * Get subcommand term for help display
   * @param cmd - Subcommand to format
   * @returns Formatted subcommand term
   */
  subcommandTerm(cmd: Command): string;
  
  /**
   * Get subcommand description
   * @param cmd - Subcommand to get description for
   * @returns Subcommand description
   */
  subcommandDescription(cmd: Command): string;
  
  /**
   * Get option term for help display
   * @param option - Option to format
   * @returns Formatted option term
   */
  optionTerm(option: Option): string;
  
  /**
   * Get option description
   * @param option - Option to get description for
   * @returns Option description
   */
  optionDescription(option: Option): string;
  
  /**
   * Get argument term for help display
   * @param argument - Argument to format
   * @returns Formatted argument term
   */
  argumentTerm(argument: Argument): string;
  
  /**
   * Get argument description
   * @param argument - Argument to get description for
   * @returns Argument description
   */
  argumentDescription(argument: Argument): string;
}

Help Layout and Sizing

Methods for calculating layout dimensions and formatting.

interface Help {
  /**
   * Get longest subcommand term length
   * @param cmd - Command with subcommands
   * @param helper - Help instance
   * @returns Maximum term length
   */
  longestSubcommandTermLength(cmd: Command, helper: Help): number;
  
  /**
   * Get longest option term length
   * @param cmd - Command with options
   * @param helper - Help instance
   * @returns Maximum term length
   */
  longestOptionTermLength(cmd: Command, helper: Help): number;
  
  /**
   * Get longest global option term length
   * @param cmd - Command with global options
   * @param helper - Help instance
   * @returns Maximum term length
   */
  longestGlobalOptionTermLength(cmd: Command, helper: Help): number;
  
  /**
   * Get longest argument term length
   * @param cmd - Command with arguments
   * @param helper - Help instance
   * @returns Maximum term length
   */
  longestArgumentTermLength(cmd: Command, helper: Help): number;
  
  /**
   * Calculate padding width for aligned formatting
   * @param cmd - Command to calculate padding for
   * @param helper - Help instance
   * @returns Padding width
   */
  padWidth(cmd: Command, helper: Help): number;
  
  /**
   * Get display width of string (ignoring ANSI codes)
   * @param str - String to measure
   * @returns Display width
   */
  displayWidth(str: string): number;
}

Help Styling Methods

Methods for applying styles to help text components.

interface Help {
  /**
   * Style section titles (e.g., 'Usage:', 'Options:')
   * @param title - Title to style
   * @returns Styled title
   */
  styleTitle(title: string): string;
  
  /**
   * Style usage text
   * @param str - Usage text to style
   * @returns Styled usage text
   */
  styleUsage(str: string): string;
  
  /**
   * Style command text in usage
   * @param str - Command text to style
   * @returns Styled command text
   */
  styleCommandText(str: string): string;
  
  /**
   * Style command descriptions
   * @param str - Description to style
   * @returns Styled description
   */
  styleCommandDescription(str: string): string;
  
  /**
   * Style option descriptions
   * @param str - Description to style
   * @returns Styled description
   */
  styleOptionDescription(str: string): string;
  
  /**
   * Style subcommand descriptions
   * @param str - Description to style
   * @returns Styled description
   */
  styleSubcommandDescription(str: string): string;
  
  /**
   * Style argument descriptions
   * @param str - Description to style
   * @returns Styled description
   */
  styleArgumentDescription(str: string): string;
  
  /**
   * Base description styling
   * @param str - Description to style
   * @returns Styled description
   */
  styleDescriptionText(str: string): string;
  
  /**
   * Style option terms
   * @param str - Option term to style
   * @returns Styled option term
   */
  styleOptionTerm(str: string): string;
  
  /**
   * Style subcommand terms
   * @param str - Subcommand term to style
   * @returns Styled subcommand term
   */
  styleSubcommandTerm(str: string): string;
  
  /**
   * Style argument terms
   * @param str - Argument term to style
   * @returns Styled argument term
   */
  styleArgumentTerm(str: string): string;
  
  /**
   * Base option text styling
   * @param str - Option text to style
   * @returns Styled option text
   */
  styleOptionText(str: string): string;
  
  /**
   * Base subcommand text styling
   * @param str - Subcommand text to style
   * @returns Styled subcommand text
   */
  styleSubcommandText(str: string): string;
  
  /**
   * Base argument text styling
   * @param str - Argument text to style
   * @returns Styled argument text
   */
  styleArgumentText(str: string): string;
}

Help Text Processing

Methods for text wrapping and formatting help content.

interface Help {
  /**
   * Wrap text to specified width, preserving line breaks
   * @param str - Text to wrap
   * @param width - Maximum line width
   * @returns Wrapped text
   */
  boxWrap(str: string, width: number): string;
  
  /**
   * Check if text is preformatted (has manual line breaks and indentation)
   * @param str - Text to check
   * @returns Whether text is preformatted
   */
  preformatted(str: string): boolean;
  
  /**
   * Format a help item (term and description)
   * @param term - Item term
   * @param termWidth - Width for term column
   * @param description - Item description
   * @param helper - Help instance
   * @returns Formatted item
   */
  formatItem(term: string, termWidth: number, description: string, helper: Help): string;
  
  /**
   * Format a list of help items with heading
   * @param heading - Section heading
   * @param items - Formatted items
   * @param helper - Help instance
   * @returns Formatted item list
   */
  formatItemList(heading: string, items: string[], helper: Help): string[];
  
  /**
   * Group items by help group heading
   * @param unsortedItems - All items
   * @param visibleItems - Visible items
   * @param getGroup - Function to get group for item
   * @returns Map of groups to items
   */
  groupItems<T>(unsortedItems: T[], visibleItems: T[], getGroup: (item: T) => string): Map<string, T[]>;
  
  /**
   * Generate complete formatted help text
   * @param cmd - Command to generate help for
   * @param helper - Help instance
   * @returns Complete help text
   */
  formatHelp(cmd: Command, helper: Help): string;
}

Help Grouping

Organize help items into logical groups with headings.

interface Command {
  /**
   * Set help group for this subcommand in parent's help
   * @param heading - Group heading
   * @returns this command for chaining
   */
  helpGroup(heading: string): this;
  
  /**
   * Get help group for this subcommand
   * @returns Group heading
   */
  helpGroup(): string;
  
  /**
   * Set default group heading for subcommands
   * @param heading - Default group heading
   * @returns this command for chaining
   */
  commandsGroup(heading: string): this;
  
  /**
   * Get default group heading for subcommands
   * @returns Default group heading
   */
  commandsGroup(): string;
  
  /**
   * Set default group heading for options
   * @param heading - Default group heading
   * @returns this command for chaining
   */
  optionsGroup(heading: string): this;
  
  /**
   * Get default group heading for options
   * @returns Default group heading
   */
  optionsGroup(): string;
}

interface Option {
  /**
   * Set help group for this option
   * @param heading - Group heading
   * @returns this option for chaining
   */
  helpGroup(heading: string): this;
}

Usage Examples:

program
  .commandsGroup('Main Commands:')
  .optionsGroup('Global Options:');

program.command('build')
  .helpGroup('Build Commands:')
  .description('Build the project');

program.command('test')
  .helpGroup('Build Commands:')
  .description('Run tests');

program.command('deploy')
  .helpGroup('Deployment Commands:')
  .description('Deploy the project');

program
  .option('--verbose', 'verbose output')
  .helpGroup('Output Options:')
  .option('--quiet', 'quiet output')
  .helpGroup('Output Options:')
  .option('--config <file>', 'configuration file')
  .helpGroup('Configuration Options:');

Types

interface HelpConfiguration {
  helpWidth?: number;
  minWidthToWrap?: number;
  sortSubcommands?: boolean;
  sortOptions?: boolean;
  showGlobalOptions?: boolean;
}

interface OutputConfiguration {
  writeOut?(str: string): void;
  writeErr?(str: string): void;
  outputError?(str: string, write: (str: string) => void): void;
  getOutHelpWidth?(): number;
  getErrHelpWidth?(): number;
  getOutHasColors?(): boolean;
  getErrHasColors?(): boolean;
  stripColor?(str: string): string;
}

interface HelpContext {
  error: boolean;
}

interface AddHelpTextContext {
  error: boolean;
  command: Command;
}

type AddHelpTextPosition = 'beforeAll' | 'before' | 'after' | 'afterAll';