tessl/npm-sade

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

—

Pending

Overview

Eval results

Files

Command Definition

Name: tessl/npm-sade
Author: tessl

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

Capabilities

Command Method

Define a new command with usage pattern, description, and configuration options.

/**
 * 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);

interface CommandOptions {
  /** Alias names for the command */
  alias?: string | string[];
  /** Make this the default command */
  default?: boolean;
}

Parameters:

usage (string, required): Command usage pattern with arguments
- Required arguments: <arg> (throws error if missing)
- Optional arguments: [arg] (undefined if not provided)
- Multiple arguments: <files..> or [options..]
desc (string, optional): Command description text
opts (object, optional): Configuration options

Usage Examples:

// Basic command
prog.command('build <src> <dest>')
  .describe('Build the source to destination')
  .action((src, dest, opts) => {
    console.log(`Building ${src} to ${dest}`);
  });

// Command with optional arguments
prog.command('serve [dir] [port]')
  .describe('Start development server')
  .action((dir = '.', port = 3000, opts) => {
    console.log(`Serving ${dir} on port ${port}`);
  });

// Command with aliases and default
prog.command('install [package]', 'Install a package', {
  alias: ['i', 'add'],
  default: true
});

Describe Method

Add or update the description for the current command.

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

Parameters:

text (string|string[], required): Description text
- String: Automatically split into sentences
- Array: Each item treated as a separate sentence
- First sentence appears in general help, all sentences in command-specific help

Usage Examples:

// Single line description
prog.command('test')
  .describe('Run the test suite');

// Multi-sentence description
prog.command('deploy')
  .describe([
    'Deploy application to production environment.',
    'This will build the app and upload it to the configured server.',
    'Make sure all tests pass before deploying.'
  ]);

// Automatic sentence splitting
prog.command('lint')
  .describe('Run linting checks. This will check code style and report issues.');

Alias Method

Define one or more aliases (alternative names) for the current command.

/**
 * Define aliases for current command
 * @param {...string} names - Alias names
 * @returns {Sade} Chainable instance
 * @throws {Error} If in single mode or no current command
 */
alias(...names);

Parameters:

...names (string): One or more alias names for the current command

Limitations:

Cannot be used in single-command mode
Must be called after defining a command
Does not check for conflicts with existing commands or aliases

Usage Examples:

// Single alias
prog.command('install [package]')
  .alias('i');

// Multiple aliases
prog.command('install [package]')
  .alias('i', 'add', 'get');

// Chaining aliases
prog.command('install [package]')
  .alias('i')
  .alias('add', 'get');

// Via command options (equivalent to above)
prog.command('install [package]', 'Install a package', {
  alias: ['i', 'add', 'get']
});

Help Output Example:

Description
    Install a package

  Usage
    $ npm install [package] [options]

  Aliases
    $ npm i
    $ npm add  
    $ npm get

  Options
    -h, --help    Displays this message

Subcommands

Define hierarchical commands (subcommands) by including the full command path in the usage pattern.

Usage Examples:

// Git-like subcommands
prog.command('remote add <name> <url>')
  .describe('Add a new remote repository')
  .action((name, url, opts) => {
    console.log(`Adding remote ${name}: ${url}`);
  });

prog.command('remote remove <name>')
  .describe('Remove a remote repository')
  .action((name, opts) => {
    console.log(`Removing remote ${name}`);
  });

// Optional base command (for help organization)
prog.command('remote')
  .describe('Manage remote repositories')
  .action((opts) => {
    console.log('Available remote commands: add, remove, list');
  });

Default Commands

Set a command to run when no specific command is provided.

Usage Examples:

// Set default via command options
prog.command('start [port]', 'Start the application', {
  default: true
});

// Now these are equivalent:
// $ my-cli start 8080
// $ my-cli 8080

// Without default command, this would show an error:
// $ my-cli 8080
// ERROR: No command specified.

Command Context and State

Each call to command() changes the current command context. All subsequent configuration methods (describe, option, action, etc.) apply to the current command until another command() is called.

Usage Examples:

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

// Context switches to 'build' command
prog.command('build <src>')
  .describe('Build the application')  // applies to 'build'
  .option('-w, --watch', 'Watch mode')  // applies to 'build'
  .action((src, opts) => {});          // applies to 'build'

// Context switches to 'test' command  
prog.command('test [pattern]')
  .describe('Run tests')               // applies to 'test'
  .option('-c, --coverage', 'Show coverage')  // applies to 'test'
  .action((pattern, opts) => {});      // applies to 'test'

Install with Tessl CLI