Custom Components CLI

Custom Components CLI is a tool to help you build and deploy custom components to Desk.

Installation

bun install -g @botpress/desk-custom-components-cli

Usage

Login

Authenticate with your Botpress account before using the CLI:

dcc login

You will be prompted to choose between browser SSO (recommended) or entering a Personal Access Token manually. Your credentials are cached locally at ~/.botpress/global.cache.json.

Options:

• -t, --pat <token> — Personal Access Token (skips the prompt)
• --bp-api-url <url> — Override the Botpress API URL

Create a component

dcc init

You will be asked to provide a name and select a starter template:

| Template | Description | | --------- | -------------------------------------------- | | default | Minimal component with a single message prop | | form | Form with validation and a submit button |

The CLI creates a new folder at components/{name}/ containing:

• Component.tsx — The main component file
• schema.ts — Zod schema defining the component's props
• styles.css — Component styles

Options:

• -n, --name <name> — Component name (skips the name prompt)
• -c, --component <template> — Template to use: default or form (skips the template prompt)

Build a component

dcc build

Select your component from the list. This compiles the TypeScript/JSX to a .js file in the same folder.

Options:

• -p, --path <path> — Path to the component file (skips the selection prompt)

Deploy a component

dcc deploy

Select your component from the list. This builds the component and uploads it to Desk.

Options:

• -p, --path <path> — Path to the component file
• -n, --name <name> — Custom component name (defaults to the folder name)
• -t, --pat <token> — Personal Access Token
• -w, --workspace <id> — Workspace ID
• --bp-api-url <url> — Override the Botpress API URL
• --desk-api-url <url> — Override the Desk API URL

First time deployment

If no credentials are cached, you will be prompted for your PAT and workspace ID.

List deployed components

dcc list

Lists all components currently deployed to your workspace.

Options:

• -t, --pat <token> — Personal Access Token
• -w, --workspace <id> — Workspace ID
• --bp-api-url <url> — Override the Botpress API URL
• --desk-api-url <url> — Override the Desk API URL

Remove a component

dcc remove

Select your component from the list. This deletes the component from Desk.

Options:

• -n, --name <name> — Component name (skips the selection prompt)
• -t, --pat <token> — Personal Access Token
• -w, --workspace <id> — Workspace ID
• --bp-api-url <url> — Override the Botpress API URL
• --desk-api-url <url> — Override the Desk API URL

Logout

dcc logout

Clears your cached credentials (PAT, workspace, and API URL).