Auditboard CLI

0.3.0-dev.2 · active · verified Wed Apr 22

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.

Common errors

```
Error: Cannot find module 'ab-cli-commands/my-command.js'
```
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).

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`.
```
ReferenceError: module is not defined
```
cause Attempting to define a command file using ES module syntax (e.g., `export default ...`) while the Node.js environment expects CommonJS (`module.exports`).

fix Change the command file's export statement from `export default { ... }` to `module.exports = { ... };` to comply with CommonJS.
```
Something went wrong...
```
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.

fix Consult the command's help (e.g., `npx auditboard help my:command`) to identify and provide all necessary required arguments.

Warnings

gotcha 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.
Fix: Refer to the project's GitHub repository for the latest documentation, changelog, or release notes for upcoming versions.
gotcha 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.
Fix: Ensure all command definitions use `module.exports` instead of `export default` or named exports.
gotcha 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.
Fix: Prefer `npx auditboard <command>` for local execution, or globally install the package (`npm install -g auditboard-cli`) for direct `auditboard <command>` access.

Install

npm install auditboard-cli npm
yarn add auditboard-cli yarn
pnpm add auditboard-cli pnpm

Imports

CLI Executable
wrong:
```
node auditboard <command>
```
correct:
```
npx auditboard <command>
```
The primary interaction with this package is via its command-line executable, typically invoked using `npx` or if installed globally, directly as `auditboard`.
Command Definition File
wrong:
```
export default { async command(args) { /* ... */ }, commandOptions: { /* ... */ } };
```
correct:
```
module.exports = { async command(args) { /* ... */ }, commandOptions: { /* ... */ } };
```
Custom command files (`ab-cli-commands/*.js`) must use CommonJS `module.exports` syntax to define their structure, not ES module `export` statements.
Accessing Arguments
wrong:
```
async command(firstParam, option) { /* ... */ }
```
correct:
```
async command(args) { const requiredParam = args.firstParam; const optionalArg = args.option; }
```
All required and optional arguments are injected into the `command` function as properties of a single `args` object, keyed by their defined names.

Quickstart

Demonstrates how to install the CLI, create a custom command, define its arguments, and execute it locally within a project.

// 1. Install auditboard-cli in your project
npm install auditboard-cli

// 2. Create a new command named 'greet'
// Run this in your project's root directory:
npx auditboard make:command greet

// 3. Locate the generated command file: ab-cli-commands/greet.js
// Replace its content with the following:
/*
module.exports = {
  async command(args) {
    const name = args.name || 'World'; // Access required arg 'name'
    const greeting = args.message || 'Hello'; // Access optional arg 'message'
    console.log(`${greeting} ${name}!`);
    return `Successfully greeted '${name}' with '${greeting}'.`;
  },
  commandOptions: {
    help: 'Greets a person by name, with an optional custom message.',
    description: 'A simple greeting command example',
    required: [
      {
        name: 'name',
        message: 'A name is required for the greeting.',
      },
    ],
    args: {
      '--message': String,
      '-m': '--message',
    },
  },
};
*/

// 4. Run your custom 'greet' command
// Example with required 'name' and optional 'message':
npx auditboard greet Alice --message "Hi there"
// Expected output:
// Hi there Alice!
// Successfully greeted 'Alice' with 'Hi there'.

// Example with only the required 'name':
npx auditboard greet Bob
// Expected output:
// Hello Bob!
// Successfully greeted 'Bob' with 'Hello'.

view raw JSON →