tessl/npm-sade

Smooth CLI operator for building command-line applications with subcommands, options, and automated help text generation.

—

Pending

Overview

Eval results

Files

Help System

Name: tessl/npm-sade
Author: tessl

Automated help text generation and display system with support for general help, command-specific help, and custom formatting.

Capabilities

Help Method

Display formatted help text for specific commands or general program help.

/**
 * Display help text for command or general help
 * @param {string} [cmd] - Command name for specific help, omit for general help
 * @returns {void} Prints formatted help to console
 */
help(cmd);

Parameters:

cmd (string, optional): Command name to show help for
- If omitted: Shows general program help with command list
- If provided: Shows detailed help for that specific command

Usage Examples:

// Show general help (same as --help flag)
prog.help();

// Show help for specific command
prog.help('build');
prog.help('remote add');  // For subcommands

// Programmatic help display
if (someCondition) {
  prog.help('deploy');
  process.exit(0);
}

Automatic Help Integration

Help functionality is automatically integrated into the CLI with built-in flags.

Built-in Help Flags:

--help, -h: Available on all commands and global scope
Automatically added to options list in help output
Takes precedence over command execution

Usage Examples:

// These all trigger help display:
// $ my-cli --help          (general help)
// $ my-cli -h              (general help)  
// $ my-cli build --help    (build command help)
// $ my-cli build -h        (build command help)

General Help Format

General help shows program overview and available commands.

General Help Structure:

Description
    [Program description if set via describe()]

  Usage  
    $ program-name <command> [options]

  Available Commands
    command1    First line of command description
    command2    First line of command description
    
  For more info, run any command with the `--help` flag
    $ program-name command1 --help
    $ program-name command2 --help

  Options
    -v, --version    Displays current version
    -g, --global     Global option description
    -h, --help       Displays this message

Example:

const prog = sade('git-cli');

prog.describe('A simple git-like CLI tool');
prog.option('-v, --verbose', 'Enable verbose output');

prog.command('add <files..>', 'Add files to staging area');
prog.command('commit', 'Commit staged changes');

prog.help(); // Shows general help

Output:

Description
    A simple git-like CLI tool

  Usage
    $ git-cli <command> [options]

  Available Commands
    add       Add files to staging area
    commit    Commit staged changes

  For more info, run any command with the `--help` flag
    $ git-cli add --help
    $ git-cli commit --help

  Options
    -v, --version    Displays current version
    -v, --verbose    Enable verbose output  
    -h, --help       Displays this message

Command-Specific Help Format

Command-specific help shows detailed information for individual commands.

Command Help Structure:

Description
    [Full command description with all sentences]

  Usage
    $ program-name command <args> [options]

  Aliases (if any)
    $ program-name alias1
    $ program-name alias2

  Options
    -o, --option     Option description  (default value)
    -g, --global     Global option description
    -h, --help       Displays this message

  Examples (if any)
    $ program-name command example1
    $ program-name command example2 --option

Example:

prog.command('deploy <env> [version]')
  .describe([
    'Deploy application to specified environment.',
    'This will build the application and upload it to the target environment.',
    'Make sure all tests pass before deploying to production.'
  ])
  .alias('d', 'ship')
  .option('-f, --force', 'Force deployment without confirmation')
  .option('--timeout', 'Deployment timeout in seconds', 300)
  .example('deploy staging')  
  .example('deploy prod v1.2.0 --force')
  .example('deploy staging --timeout 600');

prog.help('deploy');

Output:

Description
    Deploy application to specified environment.
    This will build the application and upload it to the target environment.
    Make sure all tests pass before deploying to production.

  Usage
    $ my-cli deploy <env> [version] [options]

  Aliases
    $ my-cli d
    $ my-cli ship

  Options
    -f, --force      Force deployment without confirmation
    --timeout        Deployment timeout in seconds  (default 300)
    -g, --global     Global option description
    -h, --help       Displays this message

  Examples
    $ my-cli deploy staging
    $ my-cli deploy prod v1.2.0 --force
    $ my-cli deploy staging --timeout 600

Single Command Mode Help

Single command mode provides simplified help output without command selection.

Single Command Help Features:

No "Available Commands" section
No "For more info..." text
Direct usage pattern in program name
Simplified structure focused on the single command

Example:

const prog = sade('serve [dir] [port]', true);

prog.describe('Start a static file server')
  .option('-p, --port', 'Server port', 3000)
  .option('-h, --host', 'Server host', 'localhost')
  .example('serve')
  .example('serve ./public')
  .example('serve ./dist 8080');

prog.help();

Output:

Description
    Start a static file server

  Usage
    $ serve [dir] [port] [options]

  Options
    -p, --port       Server port  (default 3000)
    -h, --host       Server host  (default localhost)
    -v, --version    Displays current version
    -h, --help       Displays this message

  Examples
    $ serve
    $ serve ./public  
    $ serve ./dist 8080

Help Text Customization

Help output can be customized through various methods during command definition.

Description Customization:

// Single line (appears in both general and command help)
prog.command('build').describe('Build the application');

// Multiple sentences (first line in general, all lines in command help)
prog.command('test').describe([
  'Run the test suite',           // Appears in general help
  'Executes all test files',      // Only in command help
  'Generates coverage report'     // Only in command help  
]);

// Automatic sentence splitting
prog.command('lint').describe('Check code style. Reports formatting issues and suggests fixes.');

Example Organization:

// Add multiple examples for better documentation
prog.command('docker run <image>')
  .example('run nginx')
  .example('run nginx:latest')  
  .example('run -p 8080:80 nginx')
  .example('run -d --name web nginx');

Error Integration

Help system integrates with error handling to provide contextual assistance.

Error + Help Pattern:

When commands fail, Sade automatically suggests using help:

ERROR
    Insufficient arguments!

  Run `$ my-cli build --help` for more info.

Custom Error Handling:

prog.command('deploy <env>')
  .action((env, opts) => {
    if (!['dev', 'staging', 'prod'].includes(env)) {
      console.error(`Invalid environment: ${env}`);
      prog.help('deploy');  // Show command help
      process.exit(1);
    }
  });

Install with Tessl CLI