kai-cli-usage-guide

name	Kai CLI Usage Guide
description	This skill should be used when the user asks to "use kai", "run kai command", "chat with Keboola AI", "query Keboola", "list tables", "check kai history", "interact with Keboola assistant", "send message to kai", or mentions Kai CLI, Keboola AI Assistant, or wants to execute Kai commands. Provides comprehensive guidance for using the Kai CLI tool to interact with the Keboola AI Assistant.
version	1.0.0

Kai CLI Usage Guide

The Kai CLI is a command-line interface for interacting with the Keboola AI Assistant (Kai). It enables querying Keboola infrastructure, managing data, and executing operations through natural language conversations.

Prerequisites

Required Environment Variables

Before using any Kai command, ensure these environment variables are set:

export STORAGE_API_TOKEN="your-keboola-storage-api-token"
export STORAGE_API_URL="https://connection.keboola.com"

Alternatively, load from a .env.local file:

set -a && source .env.local && set +a

Or pass credentials via CLI flags:

kai --token YOUR_TOKEN --url https://connection.keboola.com COMMAND

Installation

Install from PyPI or run from source:

# From PyPI
pip install kai-client

# From source (in development)
uv run kai COMMAND

Core Commands

Health Check

Verify server connectivity:

kai ping

Returns server timestamp if successful.

Server Information

Get server details including connected MCP servers:

kai info

Interactive Chat

Start an interactive conversation:

kai chat

• Type messages and press Enter to send
• Type exit or quit to end the session
• Press Ctrl+C to interrupt

Single Message

Send a one-off message without interactive mode:

kai chat -m "What tables do I have?"
kai chat -m "Show me the schema for my users table"
kai chat -m "List all configurations"

Continue Existing Chat

Resume a previous conversation using its chat ID:

kai chat --chat-id CHAT_ID -m "Tell me more about that"

Tool Approval

When Kai needs to execute write operations (creating buckets, running jobs, etc.), it requests approval:

Interactive approval (default):

kai chat -m "Create a bucket called test-bucket"
# Prompts: "Approve this tool call? [y/N]: "

Auto-approve for automation:

kai chat --auto-approve -m "Run job for configuration 12345"

Warning: Use --auto-approve cautiously - it allows write operations without confirmation.

JSON Output for Scripting

Get raw JSON events for programmatic use:

kai chat --json-output -m "List my buckets" | jq '.text'

History Management

View Chat History

List recent conversations:

kai history              # Last 10 chats
kai history --limit 50   # Last 50 chats
kai history --json-output

Get Full Chat Details

Retrieve complete chat with all messages:

kai get-chat CHAT_ID
kai get-chat CHAT_ID --json-output > chat.json

Delete a Chat

Remove a chat from history:

kai delete-chat CHAT_ID
kai delete-chat CHAT_ID -y  # Skip confirmation

Voting System

Provide feedback on AI responses:

kai vote CHAT_ID MESSAGE_ID up    # Upvote helpful response
kai vote CHAT_ID MESSAGE_ID down  # Downvote poor response
kai get-votes CHAT_ID             # View all votes for a chat

Command Reference

Command	Purpose	Key Options
kai ping	Check server health	-
kai info	Get server information	-
kai chat	Start chat session	-m, --chat-id, --auto-approve, --json-output
kai history	View chat history	-n/--limit, --json-output
kai get-chat	Get chat details	--json-output
kai delete-chat	Delete a chat	-y/--yes
kai vote	Vote on message	up or down
kai get-votes	Get votes for chat	--json-output

Common Usage Patterns

Query Keboola Data

# List available resources
kai chat -m "What tables do I have?"
kai chat -m "Show me all my configurations"
kai chat -m "List buckets in my project"

# Get specific information
kai chat -m "Show schema for table in.c-bucket.users"
kai chat -m "What data types are in my sales table?"

Execute Operations

# Create resources (requires approval)
kai chat -m "Create a bucket called analytics"

# Run jobs
kai chat --auto-approve -m "Run the transformation job for config 12345"

Workflow Example

# 1. Start a conversation
kai chat -m "Help me analyze my user data"

# 2. Note the chat ID from output, continue conversation
kai chat --chat-id CHAT_ID -m "Filter by active users only"

# 3. Review the full conversation
kai get-chat CHAT_ID

# 4. Provide feedback
kai vote CHAT_ID MSG_ID up

Error Handling

Common error scenarios:

• Missing credentials: Set STORAGE_API_TOKEN and STORAGE_API_URL
• Connection refused: Check network and server availability with kai ping
• Authentication failed: Verify token is valid and has required permissions
• Rate limited: Wait and retry, or reduce request frequency

Additional Resources

Reference Files

For detailed API information and advanced usage:

• references/api-details.md - Complete API method documentation
• references/sse-events.md - SSE event types and handling

Example Files

Working examples in examples/:

• basic-chat.sh - Simple chat interaction
• workflow-automation.sh - Automated workflow with tool approval