> ## Documentation Index
> Fetch the complete documentation index at: https://docs.theomnibot.io/llms.txt
> Use this file to discover all available pages before exploring further.

# ChatbotX CLI Command Reference: All Commands and Flags

> Complete reference for every ChatbotX CLI command group: config, workspaces, contacts, tags, custom fields, flows, sequences, channels, and more.

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        |

```bash theme={null}
# 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.

```bash theme={null}
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`

```bash theme={null}
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`

```bash theme={null}
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`

```bash theme={null}
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`

```bash theme={null}
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`

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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:

```bash theme={null}
chatbotx --refresh-spec <command>
# or delete the cache manually
rm ~/.chatbotX/openapi-cache.json
```

Use `--help` at any level to inspect syntax:

```bash theme={null}
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>`       |