Skip to main content
The ChatbotX CLI is a command-line tool that connects directly to your self-hosted ChatbotX Workspace API. You can run precise operations from a terminal, automate repeatable tasks, and integrate ChatbotX into internal scripts, cronjobs, and CI/CD pipelines. Because the CLI calls the API directly — not an LLM — every command executes with the exact parameters you provide and produces fully predictable, auditable output.

​
When to Use ChatbotX CLI

​
Installation

Install ChatbotX CLI globally on your computer, VPS, or automation server using npm or pnpm.
Verify the installation was successful by running the help command:

​
Authentication

Before you can run Workspace commands, you need to connect the CLI to your ChatbotX instance using a Workspace token and API URL. Save your credentials globally to your local CLI configuration file. This is the recommended approach for most users:
​
string
required
Your Workspace token. Find it under Settings → Developer → API Keys or Settings → Integrations → Workspace token.
​
string
required
The base API URL of your ChatbotX instance (e.g., https://app.chatbotx.io/api).

​
Option 2: Environment Variables

Use environment variables when you do not want secrets stored in your shell history or shared scripts. The CLI automatically detects these variables at runtime:
Do not commit real Workspace tokens to git repositories. Use environment variables or a secret manager for automation scripts and CI/CD workflows.

​
Custom API URL (Self-Hosted)

If you are running a self-hosted ChatbotX instance, point the CLI to your custom domain instead of the cloud URL:
If your self-hosted server uses a self-signed certificate, also enable the certificate bypass:

​
Quick Start

Work through these five commands to verify your connection and safely explore Workspace resources before modifying any data.
1

Confirm the CLI can access your Workspace

A successful response confirms your token and API URL are correctly configured.
2

List Contacts and Tags before changing anything

Review what exists before running any write commands. Note the IDs you will need.
3

Resolve a Contact by email or phone number

Use the email: or phone: prefix to look up the correct Contact record.
4

Add a Tag to a Contact

Replace <tagId> with the actual ID you retrieved from chatbotx tags list.
5

Confirm the result

Verify the tag was applied successfully before running bulk operations.
Always run commands on a test Contact before applying them to real customer data. This is especially important for commands that send messages, trigger Flows, or modify records in bulk.