tessl/npm-sade

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Sade

Name: tessl/npm-sade
Author: tessl

Sade is a small but powerful tool for building command-line interface (CLI) applications for Node.js that are fast, responsive, and helpful. It enables default commands, git-like subcommands, option flags with aliases, default option values with type-casting, required-vs-optional argument handling, command validation, and automated help text generation.

Package Information

Package Name: sade
Package Type: npm
Language: TypeScript
Installation: npm install --save sade

Core Imports

const sade = require('sade');

For ES modules:

import sade from 'sade';

Basic Usage

const sade = require('sade');

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

prog
  .version('1.0.5')
  .option('--global, -g', 'An example global flag')
  .option('-c, --config', 'Provide path to custom config', 'foo.config.js');

prog
  .command('build <src> <dest>')
  .describe('Build the source directory. Expects an `index.js` entry file.')
  .option('-o, --output', 'Change the name of the output file', 'bundle.js')
  .example('build src build --global --config my-conf.js')
  .example('build app public -o main.js')
  .action((src, dest, opts) => {
    console.log(`> building from ${src} to ${dest}`);
    console.log('> these are extra opts', opts);
  });

prog.parse(process.argv);

Architecture

Sade is built around several key components:

Factory Function: Creates new Sade instances for CLI programs
Command System: Hierarchical command structure with subcommands and arguments
Option Parsing: Flag and option handling with aliases and default values
Help Generation: Automatic help text generation for commands and global usage
Action Handlers: Callback functions executed when commands are invoked
Single Command Mode: Simplified mode for single-purpose CLI tools

Capabilities

CLI Program Creation

Core factory function for creating CLI program instances with optional single-command mode.

/**
 * Creates a new Sade CLI program instance
 * @param {string} name - The name/usage pattern of the CLI program
 * @param {boolean} [isSingle] - Enable single-command mode
 * @returns {Sade} Chainable Sade instance
 */
function sade(name, isSingle);

Program Creation

Command Definition

System for defining commands with usage patterns, descriptions, and argument handling.

/**
 * Define a new command with usage pattern and options
 * @param {string} usage - Command usage pattern with arguments
 * @param {string} [desc] - Command description
 * @param {object} [opts] - Options including alias and default
 * @returns {Sade} Chainable instance
 */
command(usage, desc, opts);

/**
 * Add description to current command
 * @param {string|string[]} text - Description text
 * @returns {Sade} Chainable instance
 */
describe(text);

/**
 * Define aliases for current command
 * @param {...string} names - Alias names
 * @returns {Sade} Chainable instance
 */
alias(...names);

Command Definition

Options and Configuration

Option flag system with aliases, descriptions, and default values.

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

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

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

Options and Configuration

Action Execution

Action handler system for command execution and argument parsing.

/**
 * Attach callback handler to current command
 * @param {function} handler - Command handler function
 * @returns {Sade} Chainable instance
 */
action(handler);

/**
 * Parse command line arguments and execute appropriate handler
 * @param {string[]} arr - Command line arguments (typically process.argv)
 * @param {object} [opts] - Parsing options
 * @returns {void|object} Void (executes handler) or LazyOutput if opts.lazy = true
 */
parse(arr, opts);

Action Execution

Help System

Automated help text generation and display system.

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

Help System

Types

// TypeScript definitions for better IDE support
interface Sade {
  command(usage: string, description?: string, options?: CommandOptions): Sade;
  option(flag: string, description?: string, value?: Value): Sade;
  action(handler: Handler): Sade;
  describe(text: Arrayable<string>): Sade;
  alias(...names: string[]): Sade;
  example(usage: string): Sade;
  parse(arr: string[], opts: { lazy: true } & ParseOptions): LazyOutput;
  parse(arr: string[], opts?: { lazy?: boolean } & ParseOptions): void;
  version(value: string): Sade;
  help(cmd?: string): void;
}

interface CommandOptions {
  alias?: Arrayable<string>;
  default?: boolean;
}

interface ParseOptions {
  lazy?: boolean;
  alias?: Record<string, string | string[]>;
  default?: Record<string, any>;
  unknown?: (flag: string) => string | void;
  // Additional mri parsing options are also supported
}

interface LazyOutput {
  name: string;
  handler: Handler;
  args: string[];
}

type Handler = (...args: any[]) => any;
type Value = number | string | boolean | null;
type Arrayable<T> = T | T[];