> ## 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: Terminal Access for Your ChatbotX Workspace

> Install and authenticate the ChatbotX CLI to run exact API operations, automate tasks, and integrate ChatbotX into scripts and cronjobs.

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

| Use Case                 | Why CLI Works Best                                                                     |
| ------------------------ | -------------------------------------------------------------------------------------- |
| **Scripting & Cronjobs** | Automate bulk tasks like syncing CRM custom fields or importing contacts on a schedule |
| **Zero Token Costs**     | Communicates directly with the ChatbotX API — saves 100% of LLM API fees               |
| **Speed & Precision**    | Delivers instantaneous results with 100% predictability and zero AI hallucinations     |
| **Auditable Workflows**  | Every command maps to an explicit API call you can log and trace                       |

## Installation

Install ChatbotX CLI globally on your computer, VPS, or automation server using npm or pnpm.

<CodeGroup>
  ```bash npm theme={null}
  npm install -g chatbotx
  ```

  ```bash pnpm theme={null}
  pnpm install -g chatbotx
  ```
</CodeGroup>

Verify the installation was successful by running the help command:

```bash theme={null}
chatbotx --help
```

## Authentication

Before you can run Workspace commands, you need to connect the CLI to your ChatbotX instance using a Workspace token and API URL.

### Option 1: CLI Configuration (Recommended)

Save your credentials globally to your local CLI configuration file. This is the recommended approach for most users:

```bash theme={null}
chatbotx config set --apiKey "YOUR_WORKSPACE_TOKEN" --apiUrl "https://app.chatbotx.io/api"
```

<ParamField body="--apiKey" type="string" required>
  Your Workspace token. Find it under **Settings → Developer → API Keys** or **Settings → Integrations → Workspace token**.
</ParamField>

<ParamField body="--apiUrl" type="string" required>
  The base API URL of your ChatbotX instance (e.g., `https://app.chatbotx.io/api`).
</ParamField>

### 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:

```bash theme={null}
export CHATBOTX_API_KEY="YOUR_WORKSPACE_TOKEN"
export CHATBOTX_API_URL="https://app.chatbotx.io/api"
```

<Info>
  Do not commit real Workspace tokens to git repositories. Use environment variables or a secret manager for automation scripts and CI/CD workflows.
</Info>

### 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:

<CodeGroup>
  ```bash CLI config theme={null}
  chatbotx config set --apiKey "YOUR_WORKSPACE_TOKEN" --apiUrl "https://app.yourdomain.com/api"
  ```

  ```bash Environment variable theme={null}
  export CHATBOTX_API_URL="https://app.yourdomain.com/api"
  ```
</CodeGroup>

If your self-hosted server uses a self-signed certificate, also enable the certificate bypass:

```bash theme={null}
chatbotx config set --allowSelfSignedCert true
# or via environment variable
export CHATBOTX_ALLOW_SELF_SIGNED_CERT=true
```

## Quick Start

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

<Steps>
  <Step title="Confirm the CLI can access your Workspace">
    ```bash theme={null}
    chatbotx workspaces get
    ```

    A successful response confirms your token and API URL are correctly configured.
  </Step>

  <Step title="List Contacts and Tags before changing anything">
    ```bash theme={null}
    chatbotx contacts list --perPage 10
    chatbotx tags list
    ```

    Review what exists before running any write commands. Note the IDs you will need.
  </Step>

  <Step title="Resolve a Contact by email or phone number">
    ```bash theme={null}
    chatbotx contacts get email:user@example.com
    chatbotx contacts get phone:+84708123123
    ```

    Use the `email:` or `phone:` prefix to look up the correct Contact record.
  </Step>

  <Step title="Add a Tag to a Contact">
    ```bash theme={null}
    chatbotx contacts tag add email:user@example.com --tagIds <tagId>
    ```

    Replace `<tagId>` with the actual ID you retrieved from `chatbotx tags list`.
  </Step>

  <Step title="Confirm the result">
    ```bash theme={null}
    chatbotx contacts tags list email:user@example.com
    ```

    Verify the tag was applied successfully before running bulk operations.
  </Step>
</Steps>

<Warning>
  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.
</Warning>