{"id":17477,"library":"sywac","title":"sywac CLI Parser","description":"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.","status":"active","version":"1.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/sywac/sywac","tags":["javascript","cli","parser","command","args","argv"],"install":[{"cmd":"npm install sywac","lang":"bash","label":"npm"},{"cmd":"yarn add sywac","lang":"bash","label":"yarn"},{"cmd":"pnpm add sywac","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"sywac is primarily a CommonJS module. Direct ESM `import` statements are not officially supported or documented for the main package.","wrong":"import cli from 'sywac'","symbol":"cli","correct":"const cli = require('sywac')"},{"note":"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.","wrong":"cli.parse()","symbol":".parseAndExit","correct":"await cli.parseAndExit()"},{"note":"Strict mode is enabled via the synchronous `cli.strict()` method since v1.3.0, not via a general configuration object.","wrong":"cli.config({ strict: true })","symbol":".strict()","correct":"cli.strict()"}],"quickstart":{"code":"const sywac = require('sywac');\n\nconst cli = sywac\n  .positional('<command>', { desc: 'The command to execute' })\n  .command('add <item>', { \n    desc: 'Add a new item', \n    run: (argv) => console.log(`Adding item: ${argv.item}`)\n  })\n  .command('remove <item>', { \n    desc: 'Remove an item', \n    run: (argv) => console.log(`Removing item: ${argv.item}`)\n  })\n  .option('-f, --force', { \n    type: 'boolean', \n    desc: 'Force the operation' \n  })\n  .strict()\n  .help()\n  .version();\n\nasync function main() {\n  // Example usage: node cli.js add my-item --force\n  // Example usage: node cli.js remove unknown-item --typo\n  try {\n    const argv = await cli.parseAndExit();\n    console.log('Parsed arguments:', JSON.stringify(argv, null, 2));\n  } catch (error) {\n    console.error('CLI Error:', error.message);\n    // sywac.parseAndExit() typically handles exiting, but in a test environment\n    // or when catching errors manually, you might want to exit.\n    process.exit(1);\n  }\n}\n\nif (require.main === module) {\n  main();\n}","lang":"javascript","description":"This quickstart demonstrates defining commands, options, enabling strict mode, and parsing arguments using the `parseAndExit` method, showing how unknown flags are handled."},"warnings":[{"fix":"Upgrade to sywac v1.2.2 or higher to resolve validation message formatting on Node.js 12+.","message":"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.","severity":"breaking","affected_versions":"<1.2.2"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.3.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Upgrade sywac to v1.2.2 or a newer version to fix the display of validation messages.","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.","error":"Value \"[ 'web', 'docs' ]\" is invalid for argument services. Choices are: web, api, db"},{"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.","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.","error":"Error: Unknown argument: --unknown-flag"},{"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.","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.","error":"TypeError: cli.parseAndExit is not a function"}],"ecosystem":"npm","meta_description":null}