JSPM – @visulima/cerebro@2.0.3

Package Exports

@visulima/cerebro
@visulima/cerebro/command/completion
@visulima/cerebro/command/help
@visulima/cerebro/command/readme-generator
@visulima/cerebro/command/version
@visulima/cerebro/logger/pail
@visulima/cerebro/package.json
@visulima/cerebro/plugins/error-handler
@visulima/cerebro/plugins/runtime-version-check
@visulima/cerebro/plugins/update-notifier

Readme

Visulima Cerebro

Cerebro is a delightful toolkit for building cross-runtime command-line interfaces (CLIs) for Node.js, Deno, and Bun, built on top of

boxen, colorize, cli-table3, command-line-args and fastest-levenshtein

I would recommend reading this guide on how to make user-friendly command-line tools.

[][typescript-url] [![npm-image]][npm-url] [![license-image]][license-url]

^{Daniel Bannert's open source work is supported by the community on GitHub Sponsors}

Install

npm install @visulima/cerebro

yarn add @visulima/cerebro

pnpm add @visulima/cerebro

Usage

import Cli from "@visulima/cerebro";

// Create a CLI runtime
const cli = new Cli("cerebro");

// Your command
cli.addCommand({
    name: "main:colors",
    description: "Output colors", // This is used in the help output
    execute: ({ logger }) => {
        logger.info("Colors command");
    },
});

await cli.run();

Now you can run your CLI with node index.js (or deno run index.js, bun index.js) and you should see the following output:

Cli Output

Shell Completions

Cerebro supports shell autocompletions for bash, zsh, fish, and powershell through the optional @bomb.sh/tab integration.

Installation

To enable completions, first install the optional peer dependency:

pnpm add @bomb.sh/tab

Adding Completion Command

Import and add the completion command to your CLI:

import Cli from "@visulima/cerebro";
import completionCommand from "@visulima/cerebro/command/completion";

const cli = new Cli("my-cli");

// Add your commands
cli.addCommand({
    name: "build",
    description: "Build the project",
    options: [
        {
            name: "output",
            alias: "o",
            type: String,
            description: "Output directory",
        },
    ],
    execute: ({ options }) => {
        console.log(`Building to ${options.output || "dist"}`);
    },
});

// Add completion command
cli.addCommand(completionCommand);

await cli.run();

Generating Completion Scripts

Users can generate completion scripts for their shell:

# For zsh
my-cli completion --shell=zsh > ~/.my-cli-completion.zsh
echo 'source ~/.my-cli-completion.zsh' >> ~/.zshrc

# For bash
my-cli completion --shell=bash > ~/.my-cli-completion.bash
echo 'source ~/.my-cli-completion.bash' >> ~/.bashrc

# For fish
my-cli completion --shell=fish > ~/.config/fish/completions/my-cli.fish

After setting up, users can use TAB to autocomplete commands and options.

Supported Runtimes

Cerebro supports multiple JavaScript runtimes:

Node.js: 18+ (follows Node.js' release schedule)
Deno: 1.0+
Bun: 1.0+

The library uses runtime-agnostic APIs to ensure compatibility across all supported runtimes. Here's a post on why we think tracking Node.js releases is important.

Contributing

If you would like to help take a look at the list of issues and check our Contributing guild.

Note: please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Credits

About

oclif - The Open CLI Framework
gluegun - A delightful toolkit for building TypeScript-powered command-line apps.
meow - CLI app helper
commander.js - node.js command-line interfaces made easy
yargs - yargs the modern, pirate-themed successor to optimist.

License

The visulima package is open-sourced software licensed under the [MIT][license-url]

[typescript-url]: https://www.typescriptlang.org/ "TypeScript" "typescript" [license-image]: https://img.shields.io/npm/l/@visulima/cerebro?color=blueviolet&style=for-the-badge [license-url]: LICENSE.md "license" [npm-image]: https://img.shields.io/npm/v/@visulima/cerebro/latest.svg?style=for-the-badge&logo=npm [npm-url]: https://www.npmjs.com/package/@visulima/cerebro/v/latest "npm"

@visulima/cerebro