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

# Introduction

> Automate ChatbotX workspace operations from the command line with the ChatbotX CLI.

**ChatbotX CLI** is a command-line tool for working directly with your self-hosted ChatbotX Workspace API. Use it to run exact operations from a terminal, automate repeatable tasks, and connect ChatbotX with internal scripts, cronjobs, CI/CD, or support workflows.

The CLI is useful when you need predictable output, auditable commands, and zero LLM token usage. It calls the ChatbotX API directly, so every command runs with the parameters you provide.

```mermaid theme={null}
sequenceDiagram
  autonumber
  participant User as User / Operator
  participant CLI as ChatbotX CLI
  participant WS as ChatbotX Workspace

  User->>CLI: Run command (e.g., chatbotx contacts list)
  CLI->>WS: Execute API request (Workspace Token auth)
  WS-->>CLI: Return action result (status/data)
  CLI-->>User: Display output in terminal (JSON / formatted text)
```

## When to use ChatbotX CLI

<Card title="When to use ChatbotX CLI?" icon="terminal">
  * **Scripting & Cronjobs**: Automating bulk tasks like syncing CRM custom fields or importing contacts.
  * **Zero Token Costs**: Communicates directly with the ChatbotX API, saving 100% of LLM API fees.
  * **Speed & Precision**: Delivers instantaneous results with 100% predictability and zero AI hallucinations.
</Card>

<Warning>
  For your AI agent to work best with ChatbotX, install the skill by running:

  ```bash theme={null}
  npx skills add sunghajung43/chatbotx
  ```

  Or load the SKILL.md file from [ClawHub](https://clawhub.ai/sunghajung43/chatbotx).
</Warning>

## Installation

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

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install -g chatbotx
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    pnpm install -g chatbotx
    ```
  </Tab>
</Tabs>

Verify the installation by running the help command:

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

## Authentication

Before running Workspace commands, connect the CLI to your self-hosted ChatbotX instance.

### Option 1: CLI Configuration (Recommended)

Save your credentials globally to your local CLI configuration:

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

* `--apiKey`: Your Workspace token (found under **Settings → Developer → API Keys** or **Settings → Integrations → Workspace token**).
* `--apiUrl`: The API URL of your ChatbotX instance.

### Option 2: Environment Variables

Use environment variables to avoid saving secrets in your shell history:

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

### Custom API URL (Self-Hosted)

If you are self-hosting ChatbotX, point the CLI configuration to your custom domain:

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

Or via environment variables:

```bash theme={null}
export CHATBOTX_API_URL="https://app.yourdomain.com/api"
```

## Quick Start

Get started with the ChatbotX CLI by checking your connection and inspecting workspace resources:

```bash theme={null}
# 1. Confirm the CLI can access your Workspace
chatbotx workspaces get

# 2. List Contacts and Tags before changing anything
chatbotx contacts list --perPage 10
chatbotx tags list

# 3. Resolve a Contact by email or phone number
chatbotx contacts get email:user@example.com
chatbotx contacts get phone:+84708123123

# 4. Add a Tag to a Contact after you know the tagId
chatbotx contacts tag add email:user@example.com --tagIds <tagId>

# 5. Confirm the result
chatbotx contacts tags list email:user@example.com
```

<Note>
  Use a test Contact before running commands on real customer data.
</Note>