Guide · Open source

How to use Botpress: CLI setup, integrations and bots as code

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Botpress is a platform for building chatbots and assistants powered by OpenAI. This repository holds the open-source parts of Botpress Cloud: integrations, developer tools (a CLI, an SDK and an API client), and some example bots written as code. This guide is for developers who want to create and deploy integrations with the Botpress CLI, and it shows you how to install the tools, create an integration and deploy it to your workspace.

Botpressbotpress/botpress · ★ 15k · MIT Install options & downloads

Quick start

1Install prerequisites. Install Node.js, pnpm and git. On Windows, also install the Microsoft Visual C++ Redistributable for Visual Studio 2015-2022.
2Install the CLI. Run npm install -g @botpress/cli to install the Botpress CLI globally.
3Create an integration. In the directory you choose, run bp init and pick one of the templates.
4Edit the definition and code. Modify integration.definition.ts and src/index.ts to define and implement your integration.
5Deploy to your workspace. Run bp deploy to publish the current version to your workspace for testing.
6Share publicly if ready. Run bp deploy --visibility public only when you are ready, since a public version cannot be updated afterwards.

Check the prerequisites

The development environment needs Node.js, pnpm and git installed. The README links to each tool's official site for installation.

On Windows, the README also lists the Microsoft Visual C++ Redistributable for Visual Studio 2015-2022 as a prerequisite.

git: version control system
Node.js: JavaScript runtime
pnpm: package manager
Windows only: Microsoft Visual C++ Redistributable for Visual Studio 2015-2022

Install the Botpress CLI

Start by installing the Botpress CLI from npm. The README also shows the equivalent commands for yarn and pnpm.

The CLI package is @botpress/cli. Its README entry describes it as a tool to build, deploy and manage bots, integrations and plugins.

npm install -g @botpress/cli

Create a new integration with bp init

Run bp init in the directory of your choice. The command generates an integration from one of the proposed templates. You do not need to fork this repository to do this, and the step can run in any directory and git repository.

After the template is generated, you can change the integration in two files: integration.definition.ts holds the definition and src/index.ts holds the implementation.

integration.definition.ts: the integration definition
src/index.ts: the integration implementation

bp init

Deploy your integration to a workspace

To test your integration, run bp deploy. This deploys the current version to your workspace so that all your bots can use it. If the version is already deployed, it is updated. Otherwise a new version is created.

By default, integrations are private to the workspace they are deployed in. To share a version with the community, deploy it as public. The README warns that once a version is public, it cannot be updated again.

Default: the integration is private to your workspace
Public: the integration is listed on the Botpress Hub for all Botpress users
A public version cannot be updated after publishing

bp deploy
bp deploy --visibility public

Build the repository from source

If you want to work on the code in this repository, clone it and build it. The README lists the steps: install dependencies, build all packages, then run the checks.

The repository has an /integrations folder with public integrations, a /bots folder with example bots, and devtools packages (CLI, SDK, API client).

/integrations: public, open-source integrations
/bots: example bots written as code using only the client, SDK and CLI
Devtools: @botpress/cli, @botpress/client and @botpress/sdk

git clone https://github.com/botpress/botpress.git
cd botpress
pnpm install
pnpm run build
pnpm run check

Know when to use the Studio instead

The README says that building bots as code is not the recommended way to build bots and is not a replacement for Botpress Studio. The code-based approach suits experienced developers who want a programmatic workflow.

The README also notes that plugins are coming soon and are not yet available.

Use Botpress Studio for the recommended visual bot building
Use the code approach if you are an experienced developer
For on-premise Botpress v12, use the separate v12 repository

What people use it for

Writing a custom integration for a Botpress Cloud workspace using the TypeScript SDK
Publishing a finished integration to the Botpress Hub for other users
Reading example bots built only with the SDK and CLI to learn the programmatic approach
Contributing fixes or new integrations to the public integrations folder

Frequently asked questions

Is Botpress free and open source?

The repository is licensed under the MIT License, and the README says all packages in it are open-source software. The README does not describe pricing for Botpress Cloud, so check the Botpress site for that.

What do I need to install before using Botpress?

The README lists Node.js, pnpm and git as prerequisites for development. Windows users also need the Microsoft Visual C++ Redistributable for Visual Studio 2015-2022.

What is the difference between bp init and bp deploy?

bp init creates a new integration from a template in the directory you choose. bp deploy publishes the integration's current version to your workspace so your bots can use it.

Can I build a chatbot without writing code?

The README recommends Botpress Studio for building bots and says the code-based approach is mainly for experienced developers. Non-programmers are better served by the Studio.

Can I run Botpress fully self-hosted on my own machine?

The README focuses on Botpress Cloud workflows and does not describe a standalone self-hosted setup. For on-premise use, the README points to the separate Botpress v12 repository.

How does Botpress compare to Rasa, LangChain or Flowise?

This repository does not compare Botpress with those projects. Botpress is described here as a platform for OpenAI-powered chatbots and assistants, built around Botpress Cloud, so compare the features you need in each project's own documentation.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Botpress suits developers who want to write integrations and bots as TypeScript code with the CLI and SDK, especially if they already use Botpress Cloud. If you want a no-code chatbot builder or a self-contained local chatbot, the README points you to Botpress Studio or the separate v12 product instead.

Install options & downloads