Quick Start

Last updated:

Quick Start

Build your first CLI application with Cerebro in under 5 minutes.

Basic CLI

Create a simple CLI with a single command:

import { createCerebro } from "@visulima/cerebro";

// Create CLI instance
const cli = createCerebro("greet-cli", {
  packageName: "greet-cli",
  packageVersion: "1.0.0",
});

// Add a command
cli.addCommand({
  name: "hello",
  description: "Greet someone",
  execute: ({ logger }) => {
    logger.log("Hello, World!");
  },
});

// Run the CLI
await cli.run();

Run it:

$ node cli.js hello
Hello, World!

Commands with Arguments

Add arguments to your commands:

cli.addCommand({
  name: "greet",
  description: "Greet someone by name",
  argument: {
    name: "name",
    description: "Person to greet",
    type: String,
  },
  execute: ({ argument, logger }) => {
    const name = argument[0];
    logger.log(`Hello, ${name}!`);
  },
});
$ node cli.js greet Alice
Hello, Alice!

Commands with Options

Add options for more flexibility:

cli.addCommand({
  name: "greet",
  description: "Greet someone",
  argument: {
    name: "name",
    description: "Person to greet",
    type: String,
  },
  options: [
    {
      name: "loud",
      alias: "l",
      description: "Make it loud",
      type: Boolean,
    },
    {
      name: "times",
      alias: "t",
      description: "Number of times to greet",
      type: Number,
      defaultValue: 1,
    },
  ],
  execute: ({ argument, options, logger }) => {
    const name = argument[0];
    const message = `Hello, ${name}!`;
    const output = options.loud ? message.toUpperCase() : message;

    for (let i = 0; i < options.times; i++) {
      logger.log(output);
    }
  },
});
$ node cli.js greet Alice --loud --times 3
HELLO, ALICE!
HELLO, ALICE!
HELLO, ALICE!

Automatic Help

Cerebro automatically generates help text:

$ node cli.js --help
greet-cli v1.0.0

Usage: greet-cli <command> [options]

Commands:
  greet <name>  Greet someone

Options:
  --help     Show help
  --version  Show version

Environment Variables

Access environment variables in your commands:

cli.addCommand({
  name: "env",
  description: "Show environment info",
  env: {
    API_KEY: {
      description: "API key for authentication",
      required: true,
    },
  },
  execute: ({ env, logger }) => {
    logger.log(`API Key: ${env.API_KEY}`);
  },
});
$ API_KEY=secret123 node cli.js env
API Key: secret123

Nested Commands

Create command hierarchies:

cli.addCommand({
  name: "db",
  description: "Database commands",
  commands: [
    {
      name: "migrate",
      description: "Run migrations",
      execute: ({ logger }) => {
        logger.log("Running migrations...");
      },
    },
    {
      name: "seed",
      description: "Seed database",
      execute: ({ logger }) => {
        logger.log("Seeding database...");
      },
    },
  ],
});
$ node cli.js db migrate
Running migrations...

$ node cli.js db seed
Seeding database...

Next Steps

Support

Contribute to our work and keep us going

Community is the heart of open source. The success of our packages wouldn't be possible without the incredible contributions of users, testers, and developers who collaborate with us every day.Want to get involved? Here are some tips on how you can make a meaningful impact on our open source projects.

Ready to help us out?

Be sure to check out the package's contribution guidelines first. They'll walk you through the process on how to properly submit an issue or pull request to our repositories.

Submit a pull request

Found something to improve? Fork the repo, make your changes, and open a PR. We review every contribution and provide feedback to help you get merged.

Good first issues

Simple issues suited for people new to open source development, and often a good place to start working on a package.
View good first issues