Registry / http-networking / sywac

sywac

JSON →
library1.3.0jsnpmunverified

sywac (So You Want A CLI) is a Node.js library for parsing command-line arguments and building robust CLIs. It provides a fluid, asynchronous API for defining positional arguments, options, and complex nested commands, with features like type-based argument parsing and flexible auto-generated help content. The current stable version is 1.3.0. While its release cadence has been moderate, it remains an active project, most notably adding a `.strict()` mode in v1.3.0 for enhanced security against unknown flags. This differentiator helps prevent unexpected behavior from typos in sensitive operations. sywac is designed for Node.js environments (v4+) and focuses on a coherent API for both simple and complex CLI applications.

http-networking
npm install sywac
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · SYWAC
S
sywac
http-networkingjavascriptv1.3.0
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.

cli
✓ const cli = require('sywac')
✗ import cli from 'sywac'
sywac is primarily a CommonJS module. Direct ESM `import` statements are not officially supported or documented for the main package.
.parseAndExit
✓ await cli.parseAndExit()
✗ cli.parse()
For typical CLI usage, `parseAndExit()` is recommended as it handles `--help` and `--version` flags and exits the process appropriately. `parse()` returns the parsed arguments without exiting.
.strict()
✓ cli.strict()
✗ cli.config({ strict: true })
Strict mode is enabled via the synchronous `cli.strict()` method since v1.3.0, not via a general configuration object.

This quickstart demonstrates defining commands, options, enabling strict mode, and parsing arguments using the `parseAndExit` method, showing how unknown flags are handled.

const sywac = require('sywac'); const cli = sywac .positional('<command>', { desc: 'The command to execute' }) .command('add <item>', { desc: 'Add a new item', run: (argv) => console.log(`Adding item: ${argv.item}`) }) .command('remove <item>', { desc: 'Remove an item', run: (argv) => console.log(`Removing item: ${argv.item}`) }) .option('-f, --force', { type: 'boolean', desc: 'Force the operation' }) .strict() .help() .version(); async function main() { // Example usage: node cli.js add my-item --force // Example usage: node cli.js remove unknown-item --typo try { const argv = await cli.parseAndExit(); console.log('Parsed arguments:', JSON.stringify(argv, null, 2)); } catch (error) { console.error('CLI Error:', error.message); // sywac.parseAndExit() typically handles exiting, but in a test environment // or when catching errors manually, you might want to exit. process.exit(1); } } if (require.main === module) { main(); }
Debug
Known issues
breakingPrior to v1.2.2, validation messages on Node.js 12 and above could be malformed, showing arrays as strings. This was a visual bug rather than a functional breaking change, but could impact user experience and script parsing of error output.
fix
Upgrade to sywac v1.2.2 or higher to resolve validation message formatting on Node.js 12+.
affects: <1.2.2
gotchaBy default, sywac does not error on unknown flags or positional arguments. This can lead to unexpected behavior or security vulnerabilities if users mistype critical flags, as the CLI will silently ignore the unknown input.
fix
Enable strict mode by calling `.strict()` in your CLI definition (available since v1.3.0) to ensure that unknown flags or arguments cause an error.
affects: <1.3.0
gotchasywac is designed for asynchronous parsing and command execution. Mixing synchronous and asynchronous operations without proper `await` can lead to race conditions or unexpected argument parsing outcomes, especially when dealing with complex command structures or custom validators.
fix
Always `await` the result of `cli.parseAndExit()` or `cli.parse()`. Ensure all custom `run` functions and validators are designed to handle asynchronous operations correctly, using `async/await` where necessary.
affects: >=1.0.0
Errors
Common errors & fixes
Value "[ 'web', 'docs' ]" is invalid for argument services. Choices are: web, api, db
This error message format could occur on Node.js 12+ prior to sywac v1.2.2 due to a bug in how array values were stringified in validation messages.
fix
Upgrade sywac to v1.2.2 or a newer version to fix the display of validation messages.
Error: Unknown argument: --unknown-flag
This error occurs when an unknown flag or argument is passed to a sywac CLI that has strict mode enabled, indicating an unrecognized input.
fix
If the flag is legitimate, add its definition to your sywac configuration using `.option()` or `.positional()`. If the flag is indeed an error, the strict mode is working as intended; guide users to correct their input or disable strict mode if this behavior is not desired.
TypeError: cli.parseAndExit is not a function
This typically happens when attempting to use ESM `import cli from 'sywac'` instead of CommonJS `const cli = require('sywac')`, or when calling methods on an undefined or incorrectly imported `cli` object.
fix
Ensure you are using `const cli = require('sywac')` for importing the library, as sywac is distributed as a CommonJS module. Verify that `cli` is correctly instantiated before calling its methods.
Upgrade
Version history
1.3.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
16 hits · last 30 days
node
14
OpenAI (training)
1
Resources
githubhttps://github.com/sywac/sywac ↗
packagehttps://www.npmjs.com/package/sywac ↗
homepagehttps://sywac.io ↗
sywac — npm install sywac · libregistry