tessl/npm-sade

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

—

Pending

Overview

Eval results

Files

Program Creation

Name: tessl/npm-sade
Author: tessl

Core factory function for creating CLI program instances with support for both multi-command and single-command modes.

Capabilities

Factory Function

Creates a new Sade CLI program instance with optional single-command mode configuration.

/**
 * 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 (auto-detected if name includes arguments)
 * @returns {Sade} Chainable Sade instance
 */
function sade(name, isSingle);

Parameters:

name (string, required): The name of your CLI program or complete usage pattern
isSingle (boolean, optional): Forces single-command mode when true. Auto-detected if name includes arguments like [dir] or <file>

Returns: A chainable Sade instance for method chaining

Usage Examples:

const sade = require('sade');

// Multi-command CLI (like git, npm)
const prog = sade('my-cli');

// Single-command CLI with explicit flag
const prog = sade('my-tool', true);

// Single-command CLI with usage pattern (auto-detected)
const prog = sade('sirv [dir]');
// isSingle is automatically true because name includes arguments

Single Command Mode

When enabled, single-command mode simplifies the CLI for applications that perform only one primary function.

Characteristics:

No subcommands allowed (calling command() throws an error)
Simplified help output without "Available Commands" section
The entire program operates as one command
Usage pattern can be specified directly in the name parameter

Usage Examples:

// Single-command mode for a file server
const prog = sade('sirv [dir]', true)
  .version('1.0.0')
  .describe('Run a static file server')
  .option('-p, --port', 'Port to bind', 5000)
  .option('-H, --host', 'Hostname to bind', 'localhost')
  .action((dir, opts) => {
    console.log(`Starting server on ${opts.host}:${opts.port}`);
    // Server logic here
  });

prog.parse(process.argv);

Help Output Example:

Description
    Run a static file server

  Usage
    $ sirv [dir] [options]

  Options
    -p, --port       Port to bind  (default 5000)
    -H, --host       Hostname to bind  (default localhost)
    -v, --version    Displays current version
    -h, --help       Displays this message

Multi-Command Mode

Default mode for CLIs with multiple subcommands, like git or npm.

Usage Examples:

// Multi-command CLI
const prog = sade('git');

prog
  .command('add <files..>')
  .describe('Add file contents to the index')
  .option('-A, --all', 'Add all files')
  .action((files, opts) => {
    // Add logic here
  });

prog
  .command('commit')
  .describe('Record changes to the repository')
  .option('-m, --message', 'Commit message')
  .action((opts) => {
    // Commit logic here
  });

prog.parse(process.argv);

Error Handling

The factory function and subsequent operations can throw errors in various scenarios:

Single-mode violations: Calling command() when isSingle is true
Invalid usage: Malformed command patterns or conflicting configurations

try {
  const prog = sade('my-tool', true);
  prog.command('invalid'); // Throws: "Disable 'single' mode to add commands"
} catch (error) {
  console.error(error.message);
}

Install with Tessl CLI