←back to manuals

CLI

The ChatBotKit CLI is a powerful command-line tool that combines autonomous AI agent capabilities with comprehensive API management. It enables you to run AI-powered automation directly in your local environment while seamlessly integrating with the full ChatBotKit platform.

Installation

Install the CLI globally using npm:

Requirements:

  • Node.js 14.x or higher
  • A ChatBotKit API token
  • Terminal or command prompt access

Authentication

The CLI requires a ChatBotKit API token for authentication. You can configure this using environment variables with flexible configuration options.

Environment Variable Setup

Set your API token using one of these methods:

Option 1: Global Configuration (Recommended)

Create a global configuration file at ~/.cbk/env:

Option 2: Project-Level Configuration

Create a .env or .env.local file in your project directory:

Option 3: Shell Environment Variable

Configuration Precedence

The CLI loads environment variables in this order (first match wins):

  1. .env.local - Project-specific local configuration (current directory)
  2. .env - Project configuration (current directory)
  3. ~/.cbk/env - Global user configuration (home directory)
  4. Shell environment variables

This allows you to have a global configuration while being able to override it per-project when needed.

Partner API Configuration

For multi-tenant applications, you can run operations as a specific user:

Agent Mode

Agent mode is the most powerful feature of the ChatBotKit CLI, enabling autonomous AI agents to interact with your local file system, execute commands, and perform complex automation tasks. This makes it perfect for coding assistance, business automation workflows, and development tasks.

What is Agent Mode?

Agent mode runs an AI agent that can:

  • Read and write files in your local file system
  • Execute shell commands with configurable timeouts
  • Edit files intelligently with precise string replacements
  • Search for files using glob patterns
  • Access all ChatBotKit platform features including integrations, datasets, skillsets, and custom abilities

The agent operates autonomously, breaking down tasks, executing them step-by-step, and iterating until completion.

Basic Agent Usage

Execute a task with a simple command:

The agent will:

  1. Analyze the task
  2. Determine the necessary steps
  3. Execute file operations
  4. Verify the result
  5. Report completion status

Agent Options

Available Tools

The agent has access to these local file system tools:

read

  • Read file contents
  • Returns full file content as text

write

  • Create new files or overwrite existing ones
  • Write string content to specified path

edit

  • Replace exact string occurrences in files
  • Ensures only one match exists (prevents accidental multi-replace)
  • Perfect for precise code modifications

find

  • Search for files using glob patterns
  • Returns list of matching file paths
  • Useful for discovery before operations

exec

  • Execute shell commands with timeout protection
  • Non-interactive only (commands must exit automatically)
  • Default 30-second timeout, configurable

Restricting Tools

For security or specific use cases, limit which tools the agent can use:

Agent Mode Examples

Coding Assistant:

Business Automation:

Development Workflows:

Complex Multi-Step Tasks:

Agent Output

The agent provides structured output showing its progress:

Platform Integration

Agent mode runs with full ChatBotKit platform capabilities:

  • Integrations: Access third-party services you've configured
  • Datasets: Reference knowledge bases during execution
  • Skillsets: Use custom abilities and functions
  • Bots: Leverage specific bot configurations with -b option
  • Secrets: Access stored credentials securely

This means your local agent can interact with external APIs, databases, and services while working on local files.

Agent Best Practices

  1. Be specific in prompts: Clear instructions lead to better results
  2. Use prompt files: Store complex instructions in text files
  3. Restrict tools when appropriate: Limit capabilities for specific tasks
  4. Monitor iterations: Adjust max iterations based on task complexity
  5. Test incrementally: Start with simple tasks, build to complex workflows
  6. Review changes: Always review file modifications before committing
  7. Use version control: Run agent in git repositories to track changes

Interactive Chat Mode

For conversational interactions with file system access:

Example:

In chat mode, you can have an ongoing conversation where the AI can use tools to interact with your file system based on your requests.

API Management Commands

The CLI provides comprehensive access to ChatBotKit API resources through the cbk api command.

General API Command Structure

Conversation Management

Bot Management

Dataset Management

Skillset Management

Partner API

Manage multi-tenant accounts:

Solution Management

Solutions provide a way to manage complex ChatBotKit configurations as code.

Solutions allow you to version control your ChatBotKit infrastructure and deploy configurations programmatically.

Common Workflows

Local Development Assistant

Use agent mode as a coding assistant:

Automation Workflows

Content Generation

API Integration Testing

Error Handling

The CLI provides clear error messages with actionable guidance:

Advanced Features

Custom Models

Specify alternative AI models:

Timeout Configuration

Configure execution timeouts for long-running commands:

Prompt Files

Store complex instructions in files:

Output Formatting

The CLI automatically detects terminal capabilities:

  • Interactive mode (TTY): Colorized output, spinners, formatted display
  • Non-interactive mode: JSON output suitable for piping and parsing

Best Practices

Security

  • Store tokens securely: Use ~/.cbk/env with restricted permissions (chmod 600)
  • Never commit tokens: Add .env.local to .gitignore
  • Use project-level configs: Override global config per project when needed
  • Restrict tools: Limit agent capabilities with -t for sensitive operations
  • Review agent actions: Always verify file changes before committing

Performance

  • Use specific tools: Restrict tools to only what's needed
  • Set iteration limits: Adjust -i based on task complexity
  • Batch operations: Combine related tasks in one agent prompt
  • Use API commands directly: For simple operations, API commands are faster than agent mode

Development

  • Version control: Run agent in git repositories to track changes
  • Incremental testing: Test agent with simple tasks before complex workflows
  • Prompt engineering: Be specific and clear in task descriptions
  • Monitor output: Watch for agent reasoning to understand its approach
  • Use bot configurations: Create specialized bots for specific automation tasks

Automation

  • Script repetitive tasks: Wrap CLI commands in shell scripts
  • Use cron for scheduling: Schedule periodic agent tasks
  • Log outputs: Redirect CLI output to logs for auditing
  • Error handling: Check exit codes in scripts
  • Notification integration: Pipe results to notification systems

Troubleshooting

Authentication Issues

Agent Not Completing Tasks

  • Increase max iterations: -i 100
  • Simplify the prompt: Break into smaller tasks
  • Check tool restrictions: Ensure needed tools are enabled
  • Review output: Look for error messages in tool calls

Permission Errors

Additional Resources

CLIAgentAutomationDevelopment