ChatbotX CLI Command Reference: All Commands and Flags

ChatbotX CLI commands follow the same resource model as the Workspace: Contacts, Tags, Custom Fields, Bot Fields, Conversations, Broadcasts, Flows, Sequences, and system tools. This page documents every command group with syntax, flags, and descriptions.

Global Options

These flags are available on every command and override your saved configuration for a single run.

Option	Description
`--apiKey`	Use a different API key for one command
`--apiUrl`	Use a different API URL for one command
`--allowSelfSignedCert`	Connect to a server with a self-signed TLS certificate
`--refresh-spec`	Re-fetch the OpenAPI spec after new APIs are added
`--json`	Return raw JSON output instead of formatted text (useful for scripting with `jq`)

Contact Identifiers

For any command in the contacts group, the <identifier> parameter supports three look-up formats. Always include the explicit prefix so the CLI resolves the correct Contact.

Format	Example	Lookup By
`id:<value>`	`id:123456789`	Internal Contact ID
`email:<value>`	`email:user@example.com`	Email address
`phone:<value>`	`phone:+84708123123`	Phone number

# Examples
chatbotx contacts get email:user@example.com
chatbotx contacts get phone:+84708123123
chatbotx contacts get id:123456789

Command Groups

Group	Common Commands	Purpose
Workspace	`workspaces get`	Check Workspace connection and metadata
Members, Channels, Teams	`members list`, `channels list`, `teams list`	Inspect users, channels, and inbox teams
Tags	`tags list`, `tags create`, `tags update`	Manage Contact labels
Custom Fields	`custom-fields list`, `custom-fields create`	Manage Contact data fields
Bot Fields	`bot-fields list`, `bot-fields bulk-update`	Manage bot-level variables
Contacts	`contacts list`, `contacts get`, `contacts upsert`	Find, create, update, import, and block Contacts
Contact Actions	`contacts tag add`, `contacts message send`, `contacts flow add`	Run actions on a specific Contact
Conversations	`conversations list`	Inspect Inbox activity
Broadcasts	`broadcasts list`, `broadcasts get`	Check campaigns and audiences
Automation	`flows list`, `sequences list`, `keywords list`, `triggers list`	Inspect automation assets
System Tools	`saved-replies list`, `template-messages list`, `error-logs list`	Review reusable content and logs

`chatbotx config`

Configure your CLI credentials. Settings are saved globally and used by all subsequent commands.

chatbotx config set --apiKey <key> --apiUrl <url>
chatbotx config set --allowSelfSignedCert true

Flag	Description
`--apiKey`	Your Workspace token
`--apiUrl`	The full API base URL (e.g., `https://app.chatbotx.io/api`)
`--allowSelfSignedCert`	Allow connections to self-signed TLS certificate servers

`chatbotx workspaces`

chatbotx workspaces get

Retrieves metadata and connection details for your Workspace. Use this to verify that your token and API URL are working correctly.

`chatbotx members`, `channels`, `teams`

chatbotx members list                      # [--page --perPage --sort --keyword]
chatbotx members get <memberId>
chatbotx channels list                     # [--includes --page --perPage]
chatbotx teams list

Command	Description
`members list`	List all workspace members with optional filters
`members get <memberId>`	Get details for a specific member by ID
`channels list`	List all connected channel inboxes
`teams list`	List all inbox teams

`chatbotx tags`

chatbotx tags list
chatbotx tags create --name <name>
chatbotx tags get <idOrName>
chatbotx tags update <id> --name <name>
chatbotx tags delete <id>

Command	Description
`tags list`	List all tags in the Workspace
`tags create`	Create a new tag by name
`tags get <idOrName>`	Look up a tag by its ID or name
`tags update <id>`	Rename an existing tag
`tags delete <id>`	Permanently delete a tag

`chatbotx custom-fields`

chatbotx custom-fields list
chatbotx custom-fields create --name <name> --type <type>
chatbotx custom-fields get <idOrName>
chatbotx custom-fields update <id> --name <name>     # [--description --folderId]
chatbotx custom-fields delete <id>

Command	Description
`custom-fields list`	List all Contact custom fields
`custom-fields create`	Create a new custom field with a name and type
`custom-fields get <idOrName>`	Retrieve a field by ID or name
`custom-fields update <id>`	Update a field’s name, description, or folder
`custom-fields delete <id>`	Delete a custom field definition

`chatbotx bot-fields`

chatbotx bot-fields list
chatbotx bot-fields create --name <name> --type <type> --value <value> --description <description>
chatbotx bot-fields update --fields <fields>
chatbotx bot-fields bulk-update --fields <fields>
chatbotx bot-fields get <idOrName>
chatbotx bot-fields update <idOrName> --value <value>
chatbotx bot-fields delete <idOrName>

Bot Fields store workspace-level variables shared across your bot flows.

`chatbotx contacts`

Core Contact Commands

chatbotx contacts list                     # [--page --perPage --sort --keyword ...]
chatbotx contacts create --phoneNumber <phoneNumber> --email <email> --gender <gender>
chatbotx contacts get <identifier>
chatbotx contacts upsert <identifier>      # [--firstName --lastName --email --phoneNumber --avatar --gender]
chatbotx contacts update <identifier>
chatbotx contacts delete <identifier>
chatbotx contacts find-by-custom-field     # [--customFieldId --value]
chatbotx contacts import --fileId <fileId> --channel <channel> --inboxId <inboxId>

Command	Description
`contacts list`	Paginated list of Contacts with optional keyword and filter support
`contacts create`	Create a new Contact record
`contacts get <identifier>`	Retrieve a Contact by ID, email, or phone
`contacts upsert <identifier>`	Create a Contact if not found, or update existing fields
`contacts update <identifier>`	Update fields on an existing Contact
`contacts delete <identifier>`	Permanently delete a Contact
`contacts find-by-custom-field`	Search Contacts by a specific custom field value
`contacts import`	Bulk-import Contacts from an uploaded file

Contact Tags

chatbotx contacts tags list <identifier>
chatbotx contacts tag add <identifier> --tagIds <tagIds>
chatbotx contacts tag delete <identifier> --tagIds <tagIds>

Command	Description
`contacts tags list <identifier>`	List all tags applied to a Contact
`contacts tag add <identifier>`	Add one or more tags to a Contact by tag IDs
`contacts tag delete <identifier>`	Remove one or more tags from a Contact

Contact Custom Fields

chatbotx contacts custom-fields list <identifier>
chatbotx contacts custom-fields update <identifier> --fields <fields>
chatbotx contacts custom-field get <identifier> <customFieldId>
chatbotx contacts custom-field add <identifier> <customFieldId> --value <value>
chatbotx contacts custom-field delete <identifier> <idOrName>

Command	Description
`contacts custom-fields list <identifier>`	List all custom field values for a Contact
`contacts custom-fields update <identifier>`	Bulk-update multiple custom field values
`contacts custom-field get <identifier> <customFieldId>`	Get the value of a specific field
`contacts custom-field add <identifier> <customFieldId>`	Set the value of a specific field
`contacts custom-field delete <identifier> <idOrName>`	Clear a specific custom field value

Contact Actions

chatbotx contacts block <identifier>
chatbotx contacts unblock <identifier>
chatbotx contacts messages list <identifier>         # [--perPage --cursor]
chatbotx contacts message get <identifier> <messageId>
chatbotx contacts message send <identifier>          # [--text --files --flowId --nodeId --inboxId]
chatbotx contacts flow add <identifier> --flowId <flowId>  # [--inboxId]
chatbotx contacts auto-replies add <identifier> --keyword <keyword>  # [--inboxId]

Command	Description
`contacts block <identifier>`	Block a Contact from sending messages
`contacts unblock <identifier>`	Unblock a previously blocked Contact
`contacts messages list <identifier>`	List recent messages for a Contact
`contacts message get <identifier> <messageId>`	Retrieve a specific message
`contacts message send <identifier>`	Send a text message, file, or flow node to a Contact
`contacts flow add <identifier>`	Trigger an automation Flow for a Contact
`contacts auto-replies add <identifier>`	Add a keyword-based auto-reply for a Contact

Conversations, Broadcasts, Flows, Sequences, and System Tools

chatbotx conversations list                # [--botCategory --assignedId --channel --status --keyword ...]
chatbotx broadcasts list
chatbotx broadcasts get <idOrName>
chatbotx broadcasts audience get <idOrName>           # [--page --perPage]
chatbotx flows list
chatbotx sequences list                    # [--page --perPage --sort]
chatbotx sequences get <id>
chatbotx saved-replies list
chatbotx template-messages list            # [--inboxId --integrationWhatsappId --status]
chatbotx ai-agents list
chatbotx integrations list
chatbotx keywords list
chatbotx triggers list
chatbotx webhooks list
chatbotx error-logs list                   # [--page --perPage --sort --keyword]

Command	Description
`conversations list`	List Inbox conversations with optional filters
`broadcasts list`	List all broadcast campaigns
`broadcasts get <idOrName>`	Get details of a specific broadcast
`broadcasts audience get <idOrName>`	Retrieve the audience list for a broadcast
`flows list`	List all automation Flows
`sequences list`	List all Sequences with optional sorting
`sequences get <id>`	Get details for a specific Sequence
`saved-replies list`	List all saved reply templates
`template-messages list`	List WhatsApp template messages
`ai-agents list`	List configured AI agents
`integrations list`	List all active integrations
`keywords list`	List keyword triggers
`triggers list`	List automation triggers
`webhooks list`	List configured webhooks
`error-logs list`	List recent system error logs

Automation Examples

Combine --json and jq to build powerful shell automation workflows.

Tag a Contact by Tag Name

# Fetch the ID of a tag named "VIP"
TAG_ID=$(chatbotx tags get "VIP" --json | jq -r '.id')

# Add the tag to a contact by email
chatbotx contacts tag add email:user@example.com --tagIds $TAG_ID

Trigger a Flow by Name

# Find the ID of the flow named "Welcome Flow"
FLOW_ID=$(chatbotx flows list --json | jq -r '.[] | select(.name=="Welcome Flow") | .id')

# Trigger the flow for a contact
chatbotx contacts flow add phone:+84708123123 --flowId $FLOW_ID

Set a Custom Field Value

# Find the ID of the custom field named "plan"
FIELD_ID=$(chatbotx custom-fields get "plan" --json | jq -r '.id')

# Set the value to "premium" for a contact
chatbotx contacts custom-field add email:user@example.com $FIELD_ID --value "premium"

CLI Help and Cache Management

The CLI caches the OpenAPI spec at ~/.chatbotX/openapi-cache.json for one hour. If your self-hosted instance has recently added new APIs and the commands are not appearing, force a refresh:

chatbotx --refresh-spec <command>
# or delete the cache manually
rm ~/.chatbotX/openapi-cache.json

Use --help at any level to inspect syntax:

chatbotx --help
chatbotx contacts --help
chatbotx contacts message --help
chatbotx contacts message send --help

Troubleshooting

Issue	Common Cause	Fix
`401` or `403` error	Token is incorrect, expired, or missing permissions	Create a new Workspace token and update your configuration
Command not found	OpenAPI spec cache is stale	Run with `--refresh-spec` or delete the cache file
TLS certificate error	Self-hosted server uses a self-signed certificate	Enable `--allowSelfSignedCert` or set `CHATBOTX_ALLOW_SELF_SIGNED_CERT=true`
Contact not found	Identifier format is incorrect	Use explicit prefix: `id:<value>`, `email:<value>`, or `phone:<value>`

Get Started

Channels

Automation

AI Agents

Inbox & Contacts

Remarketing

Tools & Growth

Integrations

Analytics

White Label

CLI & MCP

ChatbotX CLI Command Reference: All Commands and Flags

Global Options

Contact Identifiers

Command Groups

`chatbotx config`

`chatbotx workspaces`

`chatbotx members`, `channels`, `teams`

`chatbotx tags`

`chatbotx custom-fields`

`chatbotx bot-fields`

`chatbotx contacts`

Core Contact Commands

Contact Tags

Contact Custom Fields

Contact Actions

Conversations, Broadcasts, Flows, Sequences, and System Tools

Automation Examples

Tag a Contact by Tag Name

Trigger a Flow by Name

Set a Custom Field Value

CLI Help and Cache Management

Troubleshooting

​Global Options

​Contact Identifiers

​Command Groups

​chatbotx config

​chatbotx workspaces

​chatbotx members, channels, teams

​chatbotx tags

​chatbotx custom-fields

​chatbotx bot-fields

​chatbotx contacts

​Core Contact Commands

​Contact Tags

​Contact Custom Fields

​Contact Actions

​Conversations, Broadcasts, Flows, Sequences, and System Tools

​Automation Examples

​Tag a Contact by Tag Name

​Trigger a Flow by Name

​Set a Custom Field Value

​CLI Help and Cache Management

​Troubleshooting

Global Options

Contact Identifiers

Command Groups

`chatbotx config`

`chatbotx workspaces`

`chatbotx members`, `channels`, `teams`

`chatbotx tags`

`chatbotx custom-fields`

`chatbotx bot-fields`

`chatbotx contacts`

Core Contact Commands

Contact Tags

Contact Custom Fields

Contact Actions

Conversations, Broadcasts, Flows, Sequences, and System Tools

Automation Examples

Tag a Contact by Tag Name

Trigger a Flow by Name

Set a Custom Field Value

CLI Help and Cache Management

Troubleshooting