tessl/npm-sade

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

—

Pending

Overview

Eval results

Files

Options and Configuration

Name: tessl/npm-sade
Author: tessl

Option flag system with aliases, descriptions, default values, and program-level configuration.

Capabilities

Option Method

Add option flags to commands with support for aliases, descriptions, and default values.

/**
 * Add option flag to current command or global scope
 * @param {string} flags - Flag pattern (e.g., '-f, --force' or '--verbose')
 * @param {string} [desc] - Option description
 * @param {*} [value] - Default value (enables type casting)
 * @returns {Sade} Chainable instance
 */
option(flags, desc, value);

Parameters:

flags (string, required): Flag pattern with optional alias
- Short and long flags: -f, --force or --force, -f
- Long flag only: --verbose
- Short flag only: -v
- Separator: comma , or space
desc (string, optional): Human-readable description for help text
value (any, optional): Default value (enables type casting via mri)

Usage Examples:

// Boolean flags (default to false, true when present)
prog.option('-v, --verbose', 'Enable verbose output');
prog.option('--debug', 'Enable debug mode');

// String options with defaults
prog.option('-c, --config', 'Configuration file path', 'config.json');
prog.option('--output', 'Output directory', './dist');

// Number options with defaults  
prog.option('-p, --port', 'Server port', 3000);
prog.option('--timeout', 'Request timeout in ms', 5000);

// Global options (apply to all commands)
const prog = sade('my-cli');
prog.option('-g, --global', 'Global flag available to all commands');

prog.command('build')
  .option('-w, --watch', 'Watch for changes')  // Only for 'build' command
  .action((opts) => {
    // opts.global available here
    // opts.watch available here
  });

Flag Patterns and Aliases

Options support various flag pattern formats with automatic alias detection.

Flag Pattern Examples:

// Standard patterns
prog.option('-f, --force');         // Short: -f, Long: --force
prog.option('--force, -f');         // Same as above (order doesn't matter)
prog.option('-f --force');          // Space separator instead of comma
prog.option('--force -f');          // Long flag first

// Single flags
prog.option('--verbose');           // Long flag only
prog.option('-v');                  // Short flag only (less common)

// Complex names
prog.option('--dry-run');           // Hyphenated long flag
prog.option('-n, --dry-run');       // With short alias

Access in Action Handlers:

prog.command('deploy')
  .option('-f, --force', 'Force deployment')
  .option('--dry-run', 'Show what would be deployed')
  .action((opts) => {
    console.log(opts.force);     // true if -f or --force used
    console.log(opts.f);         // Same as opts.force (alias)
    console.log(opts['dry-run']); // true if --dry-run used
    console.log(opts.dryRun);    // undefined (not auto-converted)
  });

Default Values and Type Casting

Default values enable automatic type casting based on the provided value type.

// Type casting examples
prog.option('-p, --port', 'Server port', 3000);        // Number
prog.option('-c, --config', 'Config file', 'app.json'); // String  
prog.option('--debug', 'Debug mode', false);           // Boolean
prog.option('--max-files', 'Max files', 100);          // Number

Type Casting Behavior:

// Command: my-cli --port 8080 --debug --config custom.json
prog.command('start')
  .option('-p, --port', 'Server port', 3000)
  .option('--debug', 'Debug mode', false)
  .option('-c, --config', 'Config file', 'app.json')
  .action((opts) => {
    console.log(typeof opts.port);    // "number" (8080)
    console.log(typeof opts.debug);   // "boolean" (true)
    console.log(typeof opts.config);  // "string" ("custom.json")
  });

Version Method

Set the program version for automatic --version flag handling.

/**
 * Set program version for --version flag
 * @param {string} str - Version string
 * @returns {Sade} Chainable instance
 */
version(str);

Usage Examples:

// Set version from package.json
const pkg = require('./package.json');
prog.version(pkg.version);

// Or set manually
prog.version('1.0.0');

// Automatically enables --version and -v flags
// $ my-cli --version
// my-cli, 1.0.0

Example Method

Add usage examples to commands for better help documentation.

/**
 * Add usage example to current command
 * @param {string} str - Example usage string (without program name)
 * @returns {Sade} Chainable instance
 */
example(str);

Parameters:

str (string, required): Example usage string (program name is automatically prepended)

Usage Examples:

prog.command('build <src> <dest>')
  .describe('Build source to destination')
  .option('-w, --watch', 'Watch for changes')
  .option('-m, --minify', 'Minify output')
  .example('build src dist')
  .example('build src dist --watch')
  .example('build app public --minify --watch');

Help Output:

Examples
    $ my-cli build src dist
    $ my-cli build src dist --watch  
    $ my-cli build app public --minify --watch

Global vs Command Options

Options can be defined at different scopes depending on when they are added.

Global Options (before any commands):

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

// These apply to ALL commands
prog.option('-v, --verbose', 'Verbose output');
prog.option('-c, --config', 'Config file', 'config.json');

prog.command('build')
  .action((opts) => {
    // opts.verbose and opts.config available here
  });

prog.command('test')  
  .action((opts) => {
    // opts.verbose and opts.config available here too
  });

Command-Specific Options:

prog.command('build <src>')
  .option('-w, --watch', 'Watch mode')  // Only for 'build' command
  .action((src, opts) => {
    // opts.watch only available in 'build' command
  });

prog.command('test')
  .action((opts) => {
    // opts.watch NOT available here
  });

Option Inheritance and Merging:

Options are merged in this order (later values override earlier ones):