{"id":16950,"library":"auditboard-cli","title":"Auditboard CLI","description":"The `auditboard-cli` is a Node.js-based command-line interface (CLI) tool designed to boost developer productivity by enabling the creation and automation of custom tasks within JavaScript projects. Currently in version `0.3.0-dev.2`, it follows an iterative release cadence typical for early-stage development. Inspired by task runners like Ruby's Rake and Laravel's Artisan, this CLI allows developers to define project-specific commands within an `ab-cli-commands` directory, or create global utilities stored in `~/.ab-cli-commands`. Its core differentiation lies in supporting both local and global command definitions with a simple, CommonJS-based API for command creation, including clear mechanisms for defining required and optional arguments. It abstracts argument parsing, allowing developers to focus on command logic.","status":"active","version":"0.3.0-dev.2","language":"javascript","source_language":"en","source_url":"https://github.com/soxhub/auditboard-cli","tags":["javascript","cli","auditboard"],"install":[{"cmd":"npm install auditboard-cli","lang":"bash","label":"npm"},{"cmd":"yarn add auditboard-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add auditboard-cli","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used internally by auditboard-cli for parsing optional command-line arguments.","package":"args","optional":false}],"imports":[{"note":"The primary interaction with this package is via its command-line executable, typically invoked using `npx` or if installed globally, directly as `auditboard`.","wrong":"node auditboard <command>","symbol":"CLI Executable","correct":"npx auditboard <command>"},{"note":"Custom command files (`ab-cli-commands/*.js`) must use CommonJS `module.exports` syntax to define their structure, not ES module `export` statements.","wrong":"export default { async command(args) { /* ... */ }, commandOptions: { /* ... */ } };","symbol":"Command Definition File","correct":"module.exports = { async command(args) { /* ... */ }, commandOptions: { /* ... */ } };"},{"note":"All required and optional arguments are injected into the `command` function as properties of a single `args` object, keyed by their defined names.","wrong":"async command(firstParam, option) { /* ... */ }","symbol":"Accessing Arguments","correct":"async command(args) { const requiredParam = args.firstParam; const optionalArg = args.option; }"}],"quickstart":{"code":"// 1. Install auditboard-cli in your project\nnpm install auditboard-cli\n\n// 2. Create a new command named 'greet'\n// Run this in your project's root directory:\nnpx auditboard make:command greet\n\n// 3. Locate the generated command file: ab-cli-commands/greet.js\n// Replace its content with the following:\n/*\nmodule.exports = {\n  async command(args) {\n    const name = args.name || 'World'; // Access required arg 'name'\n    const greeting = args.message || 'Hello'; // Access optional arg 'message'\n    console.log(`${greeting} ${name}!`);\n    return `Successfully greeted '${name}' with '${greeting}'.`;\n  },\n  commandOptions: {\n    help: 'Greets a person by name, with an optional custom message.',\n    description: 'A simple greeting command example',\n    required: [\n      {\n        name: 'name',\n        message: 'A name is required for the greeting.',\n      },\n    ],\n    args: {\n      '--message': String,\n      '-m': '--message',\n    },\n  },\n};\n*/\n\n// 4. Run your custom 'greet' command\n// Example with required 'name' and optional 'message':\nnpx auditboard greet Alice --message \"Hi there\"\n// Expected output:\n// Hi there Alice!\n// Successfully greeted 'Alice' with 'Hi there'.\n\n// Example with only the required 'name':\nnpx auditboard greet Bob\n// Expected output:\n// Hello Bob!\n// Successfully greeted 'Bob' with 'Hello'.","lang":"javascript","description":"Demonstrates how to install the CLI, create a custom command, define its arguments, and execute it locally within a project."},"warnings":[{"fix":"Refer to the project's GitHub repository for the latest documentation, changelog, or release notes for upcoming versions.","message":"The package version `0.3.0-dev.2` indicates it is in an early development or pre-release stage. The API might not be fully stable and could introduce breaking changes in future minor or patch releases.","severity":"gotcha","affected_versions":">=0.3.0-dev.2"},{"fix":"Ensure all command definitions use `module.exports` instead of `export default` or named exports.","message":"Custom command files (e.g., in `ab-cli-commands/*.js`) must adhere to CommonJS module syntax (`module.exports = { ... }`). Using ES module `export` syntax will lead to errors.","severity":"gotcha","affected_versions":">=0.3.0-dev.2"},{"fix":"Prefer `npx auditboard <command>` for local execution, or globally install the package (`npm install -g auditboard-cli`) for direct `auditboard <command>` access.","message":"When running commands locally (not globally installed), `npx` should be used (e.g., `npx auditboard <command>`). If you rely on directly calling `auditboard` without `npx`, you must manually add `./node_modules/.bin` to your system's PATH environment variable.","severity":"gotcha","affected_versions":">=0.3.0-dev.2"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Verify the command name matches the file name (e.g., `my:command` for `my-command.js`) and ensure the file is correctly placed in `ab-cli-commands` or `~/.ab-cli-commands`.","cause":"The CLI is unable to locate the specified command file. This might happen if the command name doesn't match the file name, or the file is not in the expected `ab-cli-commands` directory (or `~/.ab-cli-commands` for global).","error":"Error: Cannot find module 'ab-cli-commands/my-command.js'"},{"fix":"Change the command file's export statement from `export default { ... }` to `module.exports = { ... };` to comply with CommonJS.","cause":"Attempting to define a command file using ES module syntax (e.g., `export default ...`) while the Node.js environment expects CommonJS (`module.exports`).","error":"ReferenceError: module is not defined"},{"fix":"Consult the command's help (e.g., `npx auditboard help my:command`) to identify and provide all necessary required arguments.","cause":"A required argument for the command was not provided during execution. This message is specified in the `message` property of the `required` argument definition.","error":"Something went wrong..."}],"ecosystem":"npm","meta_description":null}