sywac CLI Parser

1.3.0 · active · verified Wed Apr 22

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.

Common errors

```
Value "[ 'web', 'docs' ]" is invalid for argument services. Choices are: web, api, db
```
cause 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
```
cause 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
```
cause 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.

Warnings

breaking Prior 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+.
gotcha By 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.
gotcha sywac 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.

Install

npm install sywac npm
yarn add sywac yarn
pnpm add sywac pnpm

Imports

cli
wrong:
```
import cli from 'sywac'
```
correct:
```
const cli = require('sywac')
```
sywac is primarily a CommonJS module. Direct ESM `import` statements are not officially supported or documented for the main package.
.parseAndExit
wrong:
```
cli.parse()
```
correct:
```
await cli.parseAndExit()
```
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()
wrong:
```
cli.config({ strict: true })
```
correct:
```
cli.strict()
```
Strict mode is enabled via the synchronous `cli.strict()` method since v1.3.0, not via a general configuration object.

Quickstart

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

view raw JSON →