Sade CLI Framework

1.8.1 verified Thu Apr 23 auth: no javascript

Sade is a lightweight and powerful JavaScript library designed for building robust command-line interface (CLI) applications for Node.js. It distinguishes itself by providing a small API surface while offering essential features such as default commands, git-like subcommands, flexible option flags with aliases, type-casting for default option values, and sophisticated handling of required versus optional arguments. Sade also includes built-in command validation and automates the generation of helpful documentation, including version and usage text. The current stable version is 1.8.1, and the package sees regular, feature-driven releases, often including patches and minor enhancements like Deno support and integrated TypeScript definitions. It aims to offer a smooth developer and user experience with minimal overhead, making it a strong alternative to more heavyweight CLI frameworks.

Common errors

error TypeError: Cannot read properties of undefined (reading 'length') ↓

cause Attempting to access properties of `process.argv` directly after `prog.parse(process.argv)` when `sade` previously mutated the array, but no longer does.

fix

Ensure you are using sade@1.7.3 or newer. Do not rely on side effects of process.argv mutation. Access arguments and options via the action() callback parameters.

error Error: Insufficient arguments! ↓

cause A required command argument (e.g., `<src>` or `<dest>`) was not provided by the user when invoking the CLI command.

fix

Check your command definition to ensure all required arguments are clearly marked (<arg>). Inform users to provide all necessary arguments, which will also be highlighted in the automatically generated help text.

error Error: Unknown command: [value] ↓

cause An option flag was placed before the command name without a corresponding value, causing Sade to misinterpret the flag's potential value or the next argument as a command.

fix

When using options before the command name, ensure they are always explicitly paired with a value (e.g., --config my.js). For boolean flags, place them after the command name or ensure they are followed by a non-command argument.

error TypeError: (0 , sade_1.default) is not a function ↓

cause This error typically occurs when using CommonJS `require()` syntax to import an ESM-only package, or when a bundler is configured incorrectly for mixed modules.

fix

Ensure you are using import sade from 'sade'; for ESM contexts (like modern Node.js modules or bundlers) or const sade = require('sade'); for CommonJS environments. Sade supports both since v1.8.0, but context matters.

Warnings

breaking Sade no longer mutates the input `process.argv` array. While this is generally good practice, older implementations that relied on side effects of `process.argv` being modified within action handlers might need adjustment. ↓

fix Upgrade to `sade@1.7.3` or newer. Avoid directly accessing `process.argv` within action handlers; instead, rely on the arguments and options passed to the `action()` function.

gotcha Option flags placed before the command name must now be paired with a value. Previously, Sade might have ignored these flags, but since `v1.7.1`, an unpaired flag before the command can be misinterpreted as the command itself or its value, leading to `Unknown command` errors. ↓

fix Always ensure options preceding the command name are correctly paired (e.g., `--config my-config.js`) or place options after the command name for clarity. For boolean flags, they must not appear immediately before the command name if the command name could be interpreted as a value.

gotcha Sade now includes its own TypeScript definitions, and the `sade.Handler` type definition was fixed in `v1.8.1`. Users migrating from `@types/sade` should remove the `@types/sade` package to prevent type conflicts. ↓

fix Uninstall `@types/sade` from your project dependencies. Ensure your `tsconfig.json` includes `sade` in `types` if you're using global types, or import types directly: `import type { Handler } from 'sade';`.

gotcha Global options and commands are parsed and displayed in the order they are defined. Once a command is defined, you cannot add more global options or return to the global scope to define them. Ensure all program-wide configurations are set up first. ↓

fix Define all global options, version, and description using `prog.option()`, `prog.version()`, etc., before defining any specific commands with `prog.command()`.

Install

npm install sade

yarn add sade

pnpm add sade

Imports

sade
wrong
```
const sade = require('sade')
```
correct
```
import sade from 'sade'
```
ESM import is supported since v1.8.0 via the `module` field. CommonJS `require()` is also fully supported for older Node.js environments and build setups.

sade.Handler

wrong

import { Handler } from 'sade';
// or
const handler: sade.Handler = (args, opts) => {};

correct

import sade, { type Handler } from 'sade';
// or
import type { Handler } from 'sade';

TypeScript type `Handler` was fixed in v1.8.1. Prior to this, it was generic but did not work as expected. Ensure you import it as a type to avoid runtime errors.

sade
```
const sade = require('sade');
```
This CommonJS import style is fully supported and demonstrated in older examples and is compatible with Sade's target Node.js versions (>=6).

Quickstart

This quickstart demonstrates how to define a basic CLI application with Sade, including program-wide options, two distinct commands (`build` and `greet`), command-specific options, and argument parsing with actions.

#!/usr/bin/env node

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(`> output file: ${opts.output}`);
    console.log(`> global flag: ${opts.global}`);
    console.log(`> config path: ${opts.config}`);
  });

prog
  .command('greet <name>')
  .describe('Greets the specified name.')
  .option('--loud', 'Say it loudly!')
  .action((name, opts) => {
    const greeting = opts.loud ? `HELLO ${name.toUpperCase()}!` : `Hello ${name}!`;
    console.log(greeting);
  });

prog.parse(process.argv);