# auditboard-cli

> Changing the world one cli at a time

Latest version **0.3.0-dev.2** (published 2025-05-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install auditboard-cli
pnpm add auditboard-cli
yarn add auditboard-cli
bun add auditboard-cli
```

Provides the command `auditboard`.

## Health

**Score 25/100 (F)** — status: maintenance-mode.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.3.0-dev.2 |
| Published | 2025-05-23 |
| First published | 2019-07-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=10.0.0 |
| Dependencies | 7 |
| Unpacked size | 281.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Walt Z, Gal N, Motta |
| Maintainers | kjhangiani, gneugroschl, portnumber53, auditboard-eng |
| Keywords | cli, auditboard |

## Links

- npm: https://www.npmjs.com/package/auditboard-cli
- Repository: https://github.com/soxhub/auditboard-cli
- Homepage: https://github.com/soxhub/auditboard-cli#readme
- Issues: https://github.com/soxhub/auditboard-cli/issues
- npm.io page: https://npm.io/package/auditboard-cli

## Dependencies (7)

- [arg](https://npm.io/package/arg.md) ^5.0.2
- [chalk](https://npm.io/package/chalk.md) ^5.4.1
- [figlet](https://npm.io/package/figlet.md) ^1.2.3
- [marked](https://npm.io/package/marked.md) ^15.0.11
- [mkpath](https://npm.io/package/mkpath.md) ^1.0.0
- [marked-terminal](https://npm.io/package/marked-terminal.md) ^7.3.0
- [is-installed-globally](https://npm.io/package/is-installed-globally.md) ^1.0.0

## Alternatives

- [@salesforce/cli](https://npm.io/package/@salesforce/cli.md) — 389.7K weekly downloads
- [@mintlify/cli](https://npm.io/package/@mintlify/cli.md) — 208.9K weekly downloads
- [@grafana/e2e-selectors](https://npm.io/package/@grafana/e2e-selectors.md) — 128.7K weekly downloads
- [mintlify](https://npm.io/package/mintlify.md) — 112.0K weekly downloads
- [@intlayer/cli](https://npm.io/package/@intlayer/cli.md) — 22.8K weekly downloads

## Recent versions

- 0.3.0-dev.2 (latest) — 2025-05-23
- 0.0.4-beta (beta) — 2019-07-26
- 0.3.0-dev — 2025-05-23
- 0.2.0 — 2025-05-22
- 0.1.2 — 2021-11-11
- 0.1.1 — 2019-09-28
- 0.1.0 — 2019-07-27
- 0.0.11 — 2019-07-27
- 0.0.10 — 2019-07-26
- 0.0.9 — 2019-07-26
- 0.0.8 — 2019-07-26
- 0.0.7 — 2019-07-26
- 0.0.6 — 2019-07-26
- 0.0.5 — 2019-07-26
- 0.0.3-beta — 2019-07-26
- … 2 more at https://npm.io/package/auditboard-cli/versions

## README

# Auditboard Cli

![ab basic](assets/ab-cli-basic.png)

## Installation
```
$ yarn add auditboard-cli

$ npm install auditboard-cli
```

Make sure your projects `node_modules/.bin` is in your path.
```
$ export PATH=$PATH:$PWD/node_modules/.bin
```

## Why this CLI?
`auditboard-cli` is a cli that you can drop into any node project (>=v10) and automate anything you can write code for. Inspired by [Rake](https://guides.rubyonrails.org/v3.2/command_line.html) and [Artisan](https://laravel.com/docs/5.0/artisan) to help support developers maximise productivity. The commands you create live in the repo you install `auditboard-cli` in `<YOUR PROJECT ROOT>/ab-cli-commands`. We also support global creation of commands which live in `~/.ab-cli-commands`. If you want to delete a command just delete that file.

## Basic Usage

First thing to do when you get up and running is use the `make:command` (you can pass a `-g` or `--global` to the make command to install globally).

![ab make command](assets/make-command.png)

Now open the command file that was created.
```js
module.exports = {
	/**
	 * args get defined by the commandOptions interface below
	 * {
	 *   "firstParam": "users", <-- required params
	 *   "options": 11 <-- optional params
	 * }
	 */
	async command(args) {
		console.log("HELLO WORLD From my new command", args);
		return "Return a message and the cli will log it!";
	},
	commandOptions: {
		help: "This help string supports markdown!",
		description: "This is your command short description",
		required: [
			/**
			 * This is where you put required params
			 * arguments are parsed sequentially
			 * example: ./auditboard make:command users -o 11
			 *
			 * This segment is how it got to this 
			 */
			{
				name: "firstParam", // <-- this value will be users
				message: 'Something went wrong...', // <-- (optional) failure message if param does not exist
			},
			// ... more required params
		],
		args: {
			// these are optional parameters
			// https://www.npmjs.com/package/args
			'--option': Number,
			'-o': '--option',
		}
	}
};
```

## Command API
`make:command` creates the above example let's walk through the interface.

### command
  ```js
    async command(args) {
      console.log("HELLO WORLD From my new command", args);
      return "Return a message and the cli will log it!";
    },
  ```
This is the function that gets executed. If you want a custom message to display on command completion return a string

### commandOptions

- `help`
  - The message that gets displayed when a user runs `help`(supports markdown):
  ```
  $ auditboard help <your awesome command>
  ```
- `description`
  - The description that displays when you run `list`
- `required`
  - An array of parameter objects that are required to run your command. The engine does the validation.
  ```js
    required: [
      /**
        * This is where you put required params
        * arguments are parsed sequentially
        * example: ./auditboard make:command users -o 11
        *
        * This segment is how it got to this 
        */
      {
        name: "firstParam", // <-- this value will be users
        message: 'Something went wrong...', // <-- (optional) failure message if param does not exist
      },
      // ... more required params
    ],
  ```
- `args`
  - We leveraged the open source communuty for parsing optional arguments (you will be responsible for checking if they exist in your command function). See [Args docs](https://www.npmjs.com/package/args)

### Argument injection
Arguments (both optional and required) are injected into the command function. Keyed by name (for optional parms we remove `--`)

Our make command, for example, has required and optional arguments
Required:
```js
{
  name: "commandName",
  message: 'You need a command name to create a command... duh',
},
```
Optional:
```js
args: {
  "--global": Boolean,
  "-g": "--global"
}
```
We run the command...

```
$ auditboard make:command mynew:command -g
```
Inside the command function the arguments are

```js
async command(args) {
  // args.commandName => mynew:command
  // args.global => true
  ...
}
```

# Contributing
Feel free to create issues and open pull requests!

# License
[MIT](LICENSE) (AuditBoard <3 Open Source)

---
_Source: https://npm.io/package/auditboard-cli · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
