{"id":17937,"library":"sade","title":"Sade CLI Framework","description":"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.","status":"active","version":"1.8.1","language":"javascript","source_language":"en","source_url":"https://github.com/lukeed/sade","tags":["javascript","cli","cli-app","commander","arguments","parser","yargs","argv","typescript"],"install":[{"cmd":"npm install sade","lang":"bash","label":"npm"},{"cmd":"yarn add sade","lang":"bash","label":"yarn"},{"cmd":"pnpm add sade","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const sade = require('sade')","symbol":"sade","correct":"import sade from 'sade'"},{"note":"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.","wrong":"import { Handler } from 'sade';\n// or\nconst handler: sade.Handler = (args, opts) => {};","symbol":"sade.Handler","correct":"import sade, { type Handler } from 'sade';\n// or\nimport type { Handler } from 'sade';"},{"note":"This CommonJS import style is fully supported and demonstrated in older examples and is compatible with Sade's target Node.js versions (>=6).","symbol":"sade","correct":"const sade = require('sade');"}],"quickstart":{"code":"#!/usr/bin/env node\n\nconst sade = require('sade');\n\nconst prog = sade('my-cli');\n\nprog\n  .version('1.0.5')\n  .option('--global, -g', 'An example global flag')\n  .option('-c, --config', 'Provide path to custom config', 'foo.config.js');\n\nprog\n  .command('build <src> <dest>')\n  .describe('Build the source directory. Expects an `index.js` entry file.')\n  .option('-o, --output', 'Change the name of the output file', 'bundle.js')\n  .example('build src build --global --config my-conf.js')\n  .example('build app public -o main.js')\n  .action((src, dest, opts) => {\n    console.log(`> building from ${src} to ${dest}`);\n    console.log(`> output file: ${opts.output}`);\n    console.log(`> global flag: ${opts.global}`);\n    console.log(`> config path: ${opts.config}`);\n  });\n\nprog\n  .command('greet <name>')\n  .describe('Greets the specified name.')\n  .option('--loud', 'Say it loudly!')\n  .action((name, opts) => {\n    const greeting = opts.loud ? `HELLO ${name.toUpperCase()}!` : `Hello ${name}!`;\n    console.log(greeting);\n  });\n\nprog.parse(process.argv);","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<1.7.3"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.7.1"},{"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';`.","message":"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.","severity":"gotcha","affected_versions":">=1.8.0"},{"fix":"Define all global options, version, and description using `prog.option()`, `prog.version()`, etc., before defining any specific commands with `prog.command()`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"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.","cause":"Attempting to access properties of `process.argv` directly after `prog.parse(process.argv)` when `sade` previously mutated the array, but no longer does.","error":"TypeError: Cannot read properties of undefined (reading 'length')"},{"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.","cause":"A required command argument (e.g., `<src>` or `<dest>`) was not provided by the user when invoking the CLI command.","error":"Error: Insufficient arguments!"},{"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.","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.","error":"Error: Unknown command: [value]"},{"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.","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.","error":"TypeError: (0 , sade_1.default) is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}