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

# Best Practices & Troubleshooting

> Follow safe operating workflows and learn to troubleshoot common ChatbotX CLI errors.

Optimize your command line operations by following safety best practices and resolving common CLI errors.

## Safe Operating Workflows

Some CLI commands require internal IDs (e.g., `contactId`, `tagId`, `flowId`, `customFieldId`, or `inboxId`). Find and verify these IDs before executing commands that modify data:

<Steps>
  <Step title="List resources to retrieve IDs">
    Find target IDs by running lookup commands, for example:

    ```bash theme={null}
    chatbotx tags list
    ```
  </Step>

  <Step title="Verify target Contact">
    Inspect the contact details by email or phone number to confirm you have the correct record:

    ```bash theme={null}
    chatbotx contacts get email:user@example.com
    ```
  </Step>

  <Step title="Perform the action">
    Execute the command using the retrieved IDs:

    ```bash theme={null}
    chatbotx contacts tag add email:user@example.com --tagIds <tagId>
    ```
  </Step>

  <Step title="Confirm results">
    Verify the changes were applied successfully:

    ```bash theme={null}
    chatbotx contacts tags list email:user@example.com
    ```
  </Step>
</Steps>

### Testing Actions Safely

For commands that send messages, trigger Flows, or update bulk records, always run the command on a test Contact first:

```bash theme={null}
# 1. Retrieve the test contact
chatbotx contacts get email:test@example.com

# 2. Send a test message
chatbotx contacts message send email:test@example.com --text "Test message"

# 3. Check message history to confirm
chatbotx contacts messages list email:test@example.com
```

## Common Automation Examples

Combine the CLI's `--json` option and `jq` to automate common workflows in shell scripts:

### 1. Tag a contact by tag name (resolving ID dynamically)

Find the ID of a tag by its name, then apply it to a contact:

```bash theme={null}
# Fetch the ID of the tag named "VIP"
TAG_ID=$(chatbotx tags get "VIP" --json | jq -r '.id')

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

### 2. Send a specific Flow to a contact

Find the ID of a flow by its name, then trigger it for a contact:

```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 the contact by phone number
chatbotx contacts flow add phone:+84708123123 --flowId $FLOW_ID
```

### 3. Set a Custom Field value on a contact

Find the ID of a custom field, then update its value for a contact:

```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 custom field value to "premium"
chatbotx contacts custom-field add email:user@example.com $FIELD_ID --value "premium"
```

### 4. Send a message and verify history

Send a direct message and inspect history to confirm delivery:

```bash theme={null}
# Send a text message to a contact
chatbotx contacts message send email:user@example.com --text "Hello from ChatbotX CLI!"

# List recent messages for this contact to verify
chatbotx contacts messages list email:user@example.com --perPage 5
```

## CLI Help and Cache Management

The CLI caches the OpenAPI spec at `~/.chatbotX/openapi-cache.json` for 1 hour. If your self-hosted system recently added new APIs, force the CLI to refresh the spec:

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

Use `--help` at any group or sub-command level to inspect syntax:

```bash theme={null}
chatbotx --help
chatbotx contacts --help
chatbotx contacts message --help
chatbotx contacts message send --help
```

## Common Issues

| Issue                           | Common Cause                                         | Fix                                                                                                                       |
| :------------------------------ | :--------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------ |
| `401` or `403`                  | Token is incorrect, expired, or missing permissions. | Create a new Workspace token and update configuration. See [Authentication](../cli/authentication.mdx)                    |
| CLI does not show a new command | OpenAPI spec cache is stale.                         | Run the command with `--refresh-spec` option.                                                                             |
| TLS certificate error           | Self-hosted server uses a self-signed certificate.   | Enable `--allowSelfSignedCert` or `CHATBOTX_ALLOW_SELF_SIGNED_CERT=true`. See [Authentication](../cli/authentication.mdx) |
| Contact not found               | Identifier format is incorrect.                      | Use explicit prefix: `id:<value>`, `email:<value>`, or `phone:<value>`.                                                   |

## References

* [ChatbotX CLI on npm](https://www.npmjs.com/package/chatbotx): Official npm package details.