visulima
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
@visulima/boxen, @visulima/colorize, @visulima/command-line-args, @visulima/tabular 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/cerebroyarn add @visulima/cerebropnpm add @visulima/cerebroUsage
import { Cerebro } from "@visulima/cerebro";
// Create a CLI runtime
const cli = new Cerebro("my-cli");
// Add commands with options and arguments
cli.addCommand({
name: "build",
description: "Build the project",
options: [
{
name: "output",
alias: "o",
type: String,
description: "Output directory",
defaultValue: "dist",
},
{
name: "production",
alias: "p",
type: Boolean,
description: "Build for production",
},
{
name: "watch",
alias: "w",
type: Boolean,
description: "Watch for changes",
},
],
argument: {
name: "target",
description: "Build target (optional)",
type: String,
},
execute: ({ options, argument, logger, env }) => {
const target = argument[0] || "all";
const outputDir = options.output;
logger.info(`Building target: ${target}`);
logger.info(`Output directory: ${outputDir}`);
if (options.production) {
logger.info("Production build enabled");
}
if (options.watch) {
logger.info("Watch mode enabled");
}
if (env.NODE_ENV) {
logger.info(`Environment: ${env.NODE_ENV}`);
}
},
});
// Add another command with environment variables
cli.addCommand({
name: "deploy",
description: "Deploy the application",
env: [
{
name: "DEPLOY_ENV",
description: "Deployment environment",
type: String,
defaultValue: "staging",
},
{
name: "API_KEY",
description: "API key for deployment",
type: String,
},
],
execute: ({ env, logger }) => {
logger.info(`Deploying to ${env.DEPLOY_ENV}`);
if (env.API_KEY) {
logger.info("Using provided API key");
}
},
});
await cli.run();Now you can run your CLI with node index.js (or deno run index.js, bun index.js). Here are some example usages:
# Show help
node index.js --help
# Build with default options
node index.js build
# Build specific target with custom output
node index.js build --output ./build client
# Production build with watch mode
node index.js build --production --watch
# Deploy (uses environment variables)
node index.js deployYou should see help output and command execution based on the options provided:
Toolbox API
When your command's execute function is called, it receives a toolbox object with various utilities and context. Here's what you can access:
Core Properties
logger: Logger instance for output (debug, info, warn, error)options: Parsed command-line options (camelCase keys)argument: Array of positional argumentsenv: Environment variables (camelCase keys)runtime: Reference to the CLI instanceargv: Original command-line arguments array
Example Usage
cli.addCommand({
name: "example",
description: "Example command showing toolbox usage",
options: [
{ name: "verbose", alias: "v", type: Boolean, description: "Verbose output" },
{ name: "count", alias: "c", type: Number, description: "Count value", defaultValue: 1 },
],
argument: {
name: "input",
description: "Input file",
type: String,
},
env: [{ name: "DEBUG", type: Boolean, description: "Debug mode" }],
execute: ({ logger, options, argument, env, runtime, argv }) => {
// Use logger for output
logger.info("Command started");
// Access parsed options
if (options.verbose) {
logger.debug(`Count: ${options.count}`);
}
// Access positional arguments
if (argument.length > 0) {
logger.info(`Processing file: ${argument[0]}`);
}
// Access environment variables
if (env.debug) {
logger.debug("Debug mode enabled");
}
// Access CLI instance
logger.info(`CLI name: ${runtime.cliName}`);
// Access original argv
logger.debug(`Full command: ${argv.join(" ")}`);
},
});Built-in Commands
Cerebro comes with several built-in commands that are automatically available:
Help Command
The help command is automatically added to your CLI and provides usage information for all commands.
my-cli help
my-cli help <command>Version Command
Display version information for your CLI.
import { Cerebro } from "@visulima/cerebro";
import versionCommand from "@visulima/cerebro/command/version";
const cli = new Cerebro("my-cli", {
packageName: "my-cli",
packageVersion: "1.0.0",
});
cli.addCommand(versionCommand);
await cli.run();my-cli versionReadme Generator Command
Generate README documentation for your CLI commands.
import { Cerebro } from "@visulima/cerebro";
import readmeCommand from "@visulima/cerebro/command/readme-generator";
const cli = new Cerebro("my-cli");
cli.addCommand(readmeCommand);
await cli.run();my-cli readme-generatorShell Completions
Cerebro supports intelligent shell autocompletions for bash, zsh, fish, and powershell through the optional `@bomb.sh/tab` integration. The completion system automatically detects your current shell and runtime, providing context-aware suggestions for commands, options, and arguments.
Installation
To enable completions, first install the optional peer dependency:
pnpm add @bomb.sh/tabOr with other package managers:
npm install @bomb.sh/tab
yarn add @bomb.sh/tabAdding Completion Command
Import and add the completion command to your CLI. The completion command supports two options:
--shell: Shell type (bash, zsh, fish, powershell) - auto-detected by default--runtime: JavaScript runtime (node, bun, deno) - auto-detected by default
import { Cerebro } from "@visulima/cerebro";
import completionCommand from "@visulima/cerebro/command/completion";
const cli = new Cerebro("my-cli");
// Add your commands with options
cli.addCommand({
name: "build",
description: "Build the project",
options: [
{
name: "output",
alias: "o",
type: String,
description: "Output directory",
},
{
name: "production",
alias: "p",
type: Boolean,
description: "Production build",
},
],
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. The completion command will automatically detect your shell and runtime, but you can override them if needed:
# Auto-detect shell and runtime (recommended)
my-cli completion > ~/.my-cli-completion.sh
echo 'source ~/.my-cli-completion.sh' >> ~/.bashrc # or ~/.zshrc
# Explicitly specify shell
my-cli completion --shell=zsh > ~/.my-cli-completion.zsh
my-cli completion --shell=bash > ~/.my-cli-completion.bash
my-cli completion --shell=fish > ~/.config/fish/completions/my-cli.fish
my-cli completion --shell=powershell > ~/.my-cli-completion.ps1
# Override runtime detection
my-cli completion --runtime=node --shell=zsh > ~/.my-cli-completion.zshSetup Instructions
Bash:
my-cli completion --shell=bash > ~/.my-cli-completion.bash
echo 'source ~/.my-cli-completion.bash' >> ~/.bashrc
source ~/.bashrcZsh:
my-cli completion --shell=zsh > ~/.my-cli-completion.zsh
echo 'source ~/.my-cli-completion.zsh' >> ~/.zshrc
source ~/.zshrcFish:
my-cli completion --shell=fish > ~/.config/fish/completions/my-cli.fishPowerShell:
my-cli completion --shell=powershell > $PROFILE.CurrentUserAllHosts
. $PROFILE.CurrentUserAllHostsAfter setting up, users can press TAB to autocomplete:
- Command names
- Option flags (both long
--optionand short-o) - Option values (when applicable)
- Subcommands
Troubleshooting
If completions don't work:
- Ensure `@bomb.sh/tab` is installed
- Verify the completion script was sourced in your shell profile
- Try restarting your shell or running
source ~/.bashrc(or equivalent) - Check that your CLI name matches the completion script filename
Supported Runtimes
Cerebro supports multiple JavaScript runtimes:
- Node.js: >=20.19 <=25.x (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
Related Projects
- 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"
