Installation

Install the Botpress CLI, SDK, and set up your development environment

This guide covers everything you need to install and configure Botpress for local development.

Prerequisites

Before installing Botpress, ensure your system meets these requirements:

Required software

1. Node.js 18.0.0 or higher

   Botpress requires Node.js version 18.0.0 or higher.

   Check your current version:

   node --version
   

   If you need to install or upgrade Node.js:

   Official installer

   Download from nodejs.org

   Version manager (recommended)

   Use nvm or fnm to manage multiple Node versions

   Using a version manager like nvm makes it easy to switch between Node.js versions for different projects.

2. Package manager

   You’ll need one of these package managers:

   • npm (comes with Node.js)
   • yarn (install via npm install -g yarn)
   • pnpm (install via npm install -g pnpm)

   All examples in this documentation work with any package manager. Choose the one you prefer.

3. Botpress Cloud account

   Create a free account at app.botpress.cloud to:

   • Deploy your bots and integrations
   • Access the Hub and available integrations
   • Use the visual Studio editor
   • Manage workspaces and collaborators

Optional tools

These tools enhance your development experience:

• Git - Version control for your bot projects
• TypeScript - Already included as a dependency, but useful for editor support
• VS Code - Recommended editor with excellent TypeScript support

Install the Botpress CLI

The Botpress CLI is the primary tool for building, testing, and deploying bots and integrations.

Global installation

Install the CLI globally to use it anywhere on your system:

npm

npm install -g @botpress/cli

Verify installation

Confirm the CLI is installed and check the version:

bp --version

You should see output like:

5.5.7

The exact version number may differ based on the latest release.

Get help

View all available commands:

bp --help

Get help for a specific command:

bp init --help
bp deploy --help
bp dev --help

Authenticate with Botpress Cloud

1. Generate a Personal Access Token

   1. Log in to Botpress Cloud
   2. Click your profile avatar in the top-right corner
   3. Select Personal Access Tokens
   4. Click Generate Token
   5. Give your token a descriptive name (e.g., “Development Machine”)
   6. Copy the token and save it securely

   Your Personal Access Token is shown only once. Store it in a password manager or secure location.

2. Log in via the CLI

   Run the login command:

   bp login
   

   You’ll be prompted for:

   ? Enter your Personal Access Token: [paste token here]
   

   After entering your token, select your workspace:

   ? Which workspace do you want to use?
   ❯ My Workspace
     Company Workspace
     Test Workspace
   

   The CLI caches your credentials in ~/.botpress/, so you only need to log in once per machine.

3. Verify authentication

   Test that you’re logged in correctly:

   bp init --help
   

   If authentication succeeded, you won’t see any login-related errors.

Using profiles

If you work with multiple Botpress workspaces, use profiles to switch between them:

# Log in with a named profile
bp login --profile work
bp login --profile personal

# Use a specific profile
bp deploy --profile work
bp dev --profile personal

Install the Botpress SDK

When you create a new bot or integration with bp init, the SDK is automatically added as a dependency. However, you can also install it manually in existing projects.

Add to your project

npm

npm install @botpress/sdk

SDK usage

The SDK provides TypeScript types and utilities for building bots and integrations:

import * as sdk from '@botpress/sdk'
import { z } from '@botpress/sdk'

// Define a bot
export default new sdk.BotDefinition({
  actions: {
    myAction: {
      title: 'My Action',
      input: {
        schema: z.object({
          message: z.string(),
        }),
      },
      output: {
        schema: z.object({
          result: z.string(),
        }),
      },
    },
  },
})

The SDK uses Zod for schema validation. Import z from @botpress/sdk to define schemas.

Local development setup

For contributors or advanced users who want to build Botpress from source.

Clone the repository

git clone https://github.com/botpress/botpress.git
cd botpress

Install dependencies

Botpress uses pnpm as its package manager:

pnpm install

You must use pnpm for local development. The repository uses pnpm workspaces and won’t work with npm or yarn.

Build all packages

Build the CLI, SDK, and all packages:

pnpm run build

Run checks

Verify everything is working:

pnpm run check

This runs:

• Type checking
• Linting
• Format checking
• Dependency validation

Use local CLI

Run the CLI directly from source:

cd packages/cli
pnpm dev -- init

Or link it globally:

cd packages/cli
npm link
bp --version

Windows-specific setup

Windows users need additional prerequisites:

1. Install Visual C++ Redistributable

   Download and install the Microsoft Visual C++ Redistributable for Visual Studio 2015-2022.

   This is required for native dependencies used by the CLI.

2. Use PowerShell or Windows Terminal

   For the best experience, use:

   • PowerShell (comes with Windows)
   • Windows Terminal (recommended, available in Microsoft Store)

   Avoid using the legacy Command Prompt (cmd.exe).

3. Configure execution policy (if needed)

   If you encounter script execution errors, run PowerShell as Administrator and execute:

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
   

Environment variables

Some CLI commands support environment variables for configuration:

Variable	Description	Example
BP_API_URL	Custom Botpress API URL	https://api.botpress.cloud
BP_TOKEN	Personal Access Token	bp_pat_...
BP_WORKDIR	Working directory for commands	./my-bot

Set these in a .env file in your project root, and the CLI will automatically load them.

Verify your setup

Confirm everything is installed correctly:

1. Check versions

   node --version   # Should be 18.0.0 or higher
   bp --version     # Should show CLI version
   
2. Test authentication

   bp login
   

   You should be able to select a workspace without errors.

3. Create a test project

   bp init
   # Select "bot", name it "test-bot"
   cd test-bot
   

   If this succeeds, your installation is complete!

Troubleshooting

Command 'bp' not found

The CLI wasn’t installed globally or isn’t in your PATH.

Solution:

1. Reinstall globally:

   npm install -g @botpress/cli
   

2. Check your global npm bin directory:

   npm config get prefix
   

3. Ensure this directory is in your system PATH.

Node version error

You’re running an unsupported Node.js version.

Solution:

Install Node.js 18.0.0 or higher:

# Using nvm
nvm install 18
nvm use 18

# Or download from nodejs.org

Permission denied on macOS/Linux

You may need elevated permissions for global installs.

Solution:

Use a version manager like nvm (recommended) or:

sudo npm install -g @botpress/cli

Using sudo can cause permission issues. Use nvm instead when possible.

pnpm install fails in local development

This usually means you’re missing prerequisites.

Solution:

1. Ensure you have git installed
2. On Windows, install Visual C++ Redistributable
3. Delete node_modules and pnpm-lock.yaml, then run pnpm install again

Authentication keeps failing

Your token might be invalid or expired.

Solution:

1. Generate a new Personal Access Token in Botpress Cloud
2. Run bp login again
3. If you’re using a custom API URL, verify it’s correct:
   bp login --apiUrl https://api.botpress.cloud
   

Next steps

Quickstart guide

Build your first bot in under 5 minutes

CLI reference

Explore all available CLI commands and options

SDK reference

Learn about the Botpress SDK API

Build an integration

Create custom integrations for external services