sade

library1.8.1jsnpmunverified

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.

devops

npm install sade

github ↗package ↗

INSTALL

IMPORT

SIG · SADE

sade

devopsjavascriptv1.8.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

sade

✓ import sade from 'sade'

✗ const sade = require('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

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

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

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).

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

sade --version

Debug

Known issues

breakingSade 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.

affects: <1.7.3

gotchaOption 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.

affects: >=1.7.1

gotchaSade 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';`.

affects: >=1.8.0

gotchaGlobal 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()`.

affects: >=1.0.0

Errors

Common errors & fixes

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

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: Insufficient arguments!

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: Unknown command: [value]

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.

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

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.

Upgrade

Version history

1.8.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/lukeed/sade ↗

packagehttps://www.npmjs.com/package/sade ↗