CLI Commands - BuilderBot

The BuilderBot CLI provides several commands for managing your chatbot projects. This page documents all available commands, their options, and usage examples.

Global Commands

`bot`

The main CLI entry point for BuilderBot tools.

bot

Running bot without arguments launches the interactive project creation wizard, equivalent to npm create builderbot.

Project Creation

Interactive Creation

Launch the interactive setup wizard:

npm create builderbot@latest

Or using the global CLI:

bot

The wizard will guide you through:

Confirmation prompt: “Do you want to continue?”
Provider selection: Choose your WhatsApp/messaging provider
Database selection: Choose your data storage backend
Language selection: Choose TypeScript or JavaScript

Non-Interactive Creation

Create a project with predefined configuration:

npm create builderbot@latest -- --provider=<provider> --database=<database> --language=<language>

Required flags:

--provider - WhatsApp/messaging provider
--database - Database backend
--language - Programming language (ts or js)

Example:

npm create builderbot@latest -- --provider=baileys --database=mongo --language=ts

Command Reference

While the main CLI focuses on project creation, here are the internal commands and modules available:

Check Commands

These commands run automatically during project creation to verify system requirements.

Check Node Version

Verifies Node.js version is 20 or higher. Source: src/check/index.ts:9

import { checkNodeVersion } from '@builderbot/cli'

const result = await checkNodeVersion()
// Returns: { pass: boolean, message: string }

Check Git Installation

Verifies Git is installed and accessible. Source: src/check/index.ts:31

import { checkGit } from '@builderbot/cli'

const result = await checkGit()
// Returns: { pass: boolean, message: string }

Check Operating System

Detects the current operating system. Source: src/check/index.ts:21

import { checkOs } from '@builderbot/cli'

const os = await checkOs()
// Returns: string (e.g., "OS: linux")

Clean Commands

Clean Session

Removes WhatsApp Web session files and authentication data. Source: src/clean/index.ts:11

import { cleanSession } from '@builderbot/cli'

await cleanSession()

This removes:

.wwebjs_auth directory
session.json file

Use case: When you need to reset WhatsApp authentication or switch accounts.

Install Commands

Install All Dependencies

Installs or updates BuilderBot packages. Source: src/install/index.ts:27

import { installAll } from '@builderbot/cli'

await installAll()

Get Package Manager

Detects the package manager being used (npm, yarn, or pnpm). Source: src/install/tool.ts:11 Currently defaults to npm.

Configuration Options

The CLI uses predefined configurations for providers, databases, and languages.

Provider List

Source: src/configuration/index.ts:19 All available WhatsApp and messaging providers:

const PROVIDER_LIST = [
  { value: 'baileys', label: 'Baileys', hint: 'opensource' },
  { value: 'sherpa', label: 'Sherpa', hint: 'opensource' },
  { value: 'evolution-api', label: 'Evolution API', hint: 'opensource' },
  { value: 'wppconnect', label: 'WPPConnect', hint: 'opensource' },
  { value: 'twilio', label: 'Twilio' },
  { value: 'meta', label: 'Meta' },
  { value: 'facebook-messenger', label: 'Facebook Messenger' },
  { value: 'instagram', label: 'Instagram' },
  { value: 'gohighlevel', label: 'GoHighLevel' },
  { value: 'email', label: 'Email', hint: 'IMAP/SMTP' },
]

Database List

Source: src/configuration/index.ts:34 All available database backends:

const PROVIDER_DATA = [
  { value: 'memory', label: 'Memory' },
  { value: 'json', label: 'Json' },
  { value: 'mongo', label: 'Mongo' },
  { value: 'mysql', label: 'MySQL' },
  { value: 'postgres', label: 'PostgreSQL' },
]

Language Options

Source: src/configuration/index.ts:42 Supported programming languages:

const AVAILABLE_LANGUAGES = [
  { value: 'ts', label: 'TypeScript' },
  { value: 'js', label: 'JavaScript' },
]

Usage Examples

Example 1: Create a Baileys Bot with MongoDB (TypeScript)

# Interactive mode
npm create builderbot@latest
# Select: Baileys > Mongo > TypeScript

# Non-interactive mode
npm create builderbot@latest -- --provider=baileys --database=mongo --language=ts

# Navigate and start
cd base-ts-baileys-mongo
npm install
npm run dev

Example 2: Create a Twilio Bot with PostgreSQL (JavaScript)

# Interactive mode
npm create builderbot@latest
# Select: Twilio > PostgreSQL > JavaScript

# Non-interactive mode
npm create builderbot@latest -- --provider=twilio --database=postgres --language=js

# Navigate and start
cd base-js-twilio-postgres
npm install
npm start

Example 3: Create an Email Bot with JSON Storage

# Create project
npm create builderbot@latest -- --provider=email --database=json --language=ts

# Setup
cd base-ts-email-json
npm install

# Configure email credentials
cp .env.example .env
# Edit .env with IMAP/SMTP settings

# Start
npm run dev

Example 4: Create a Meta Bot for Production

# Create with PostgreSQL for production reliability
npm create builderbot@latest -- --provider=meta --database=postgres --language=ts

cd base-ts-meta-postgres
npm install

# Configure Meta API credentials
cp .env.example .env
# Add: META_ACCESS_TOKEN, META_PHONE_NUMBER_ID, etc.

# Development
npm run dev

# Production build
npm run build
npm start

Command Options Reference

Provider Options

Value	Label	Type	Description
`baileys`	Baileys	Open Source	Pure TypeScript WhatsApp library
`sherpa`	Sherpa	Open Source	Lightweight WhatsApp integration
`evolution-api`	Evolution API	Open Source	RESTful WhatsApp API
`wppconnect`	WPPConnect	Open Source	Browser-based automation
`twilio`	Twilio	Commercial	Enterprise messaging platform
`meta`	Meta	Commercial	Official WhatsApp Business API
`facebook-messenger`	Facebook Messenger	Commercial	Facebook messaging
`instagram`	Instagram	Commercial	Instagram direct messages
`gohighlevel`	GoHighLevel	Commercial	Marketing automation
`email`	Email	Open Source	IMAP/SMTP email integration

Database Options

Value	Label	Best For	Persistence
`memory`	Memory	Development, testing	No
`json`	JSON	Small projects, prototypes	Yes (file-based)
`mongo`	MongoDB	Scalable applications	Yes (NoSQL)
`mysql`	MySQL	Traditional applications	Yes (SQL)
`postgres`	PostgreSQL	Production systems	Yes (SQL)

Language Options

Value	Label	Features	Best For
`ts`	TypeScript	Type safety, autocomplete, compile-time checks	Large projects, teams
`js`	JavaScript	Quick start, flexibility	Rapid prototyping, simple bots

Programmatic Usage

You can use the CLI programmatically in your Node.js scripts:

import { start } from '@builderbot/cli'

// Launch interactive wizard
await start()

Or create a custom creation flow:

import { copyBaseApp } from '@builderbot/cli'
import { join } from 'path'

const templatePath = join(__dirname, 'templates', 'base-ts-baileys-mongo')
const projectPath = join(process.cwd(), 'my-bot')

await copyBaseApp(templatePath, projectPath)

Environment Variables

`NODE_ENV`

Set to dev to enable development mode:

NODE_ENV=dev bot

Troubleshooting

TTY Initialization Failed

If you see ERR_TTY_INIT_FAILED, the CLI will automatically fall back to legacy mode with basic prompts.

Template Not Found

If you get TEMPLATE_PATH_NOT_FOUND, ensure you’re using valid provider, database, and language combinations.

Permission Errors

On Unix systems, you may need to make the CLI executable:

chmod +x /path/to/node_modules/.bin/bot

Version Information

Check your installed CLI version:

npm list @builderbot/cli

Or for create-builderbot:

npm list create-builderbot

Current stable version: 1.3.15-alpha.10

Package Information

@builderbot/cli

npm package: @builderbot/cli
Binary: bot
Repository: GitHub

create-builderbot

npm package: create-builderbot
Usage: npm create builderbot
Repository: GitHub

CLI Reference

​Global Commands

​bot

​Project Creation

​Interactive Creation

​Non-Interactive Creation

​Command Reference

​Check Commands

​Check Node Version

​Check Git Installation

​Check Operating System

​Clean Commands

​Clean Session

​Install Commands

​Install All Dependencies

​Get Package Manager

​Configuration Options

​Provider List

​Database List

​Language Options

​Usage Examples

​Example 1: Create a Baileys Bot with MongoDB (TypeScript)

​Example 2: Create a Twilio Bot with PostgreSQL (JavaScript)

​Example 3: Create an Email Bot with JSON Storage

​Example 4: Create a Meta Bot for Production

​Command Options Reference

​Provider Options

​Database Options

​Language Options

​Programmatic Usage

​Environment Variables

​NODE_ENV

​Troubleshooting

​TTY Initialization Failed

​Template Not Found

​Permission Errors

​Version Information

​Package Information

​@builderbot/cli

​create-builderbot

​Related Resources

Build docs developers (and LLMs) love

Global Commands

`bot`

Project Creation

Interactive Creation

Non-Interactive Creation

Command Reference

Check Commands

Check Node Version

Check Git Installation

Check Operating System

Clean Commands

Clean Session

Install Commands

Install All Dependencies

Get Package Manager

Configuration Options

Provider List

Database List

Language Options

Usage Examples

Example 1: Create a Baileys Bot with MongoDB (TypeScript)

Example 2: Create a Twilio Bot with PostgreSQL (JavaScript)

Example 3: Create an Email Bot with JSON Storage

Example 4: Create a Meta Bot for Production

Command Options Reference

Provider Options

Database Options

Language Options

Programmatic Usage

Environment Variables

`NODE_ENV`

Troubleshooting

TTY Initialization Failed

Template Not Found

Permission Errors

Version Information

Package Information

@builderbot/cli

create-builderbot

Related Resources