Keboola Agent CLI (kbagent)
A CLI for managing multiple Keboola projects from one place. Built for AI coding agents (Claude Code, Codex, Gemini) and human operators who need to work across many projects at once.
Why does this exist?
Keboola's web UI and standard API clients work great for a single project. But when you manage 30+ projects across an organization, you need a way to:
- Query all projects at once -- list configurations, jobs, or data lineage across the entire organization in one command
- Give AI agents access to Keboola -- every command supports
--json output that agents can parse reliably
- Onboard an entire organization -- register all projects from a Keboola org with a single
org setup command
- Trace data flow -- see how data moves between projects via bucket sharing (lineage)
- Use MCP tools -- call keboola-mcp-server tools across all projects in parallel
- Manage dev branches -- create, switch, delete branches with persistent active branch state
- Debug SQL interactively -- create workspaces, load tables, run SQL queries without full job runs
See real-world use cases for end-to-end examples with AI agents.
What it can do
Setup & Info
| Command | What it does |
|---|
init | Initialize a local .kbagent/ workspace for per-directory project isolation |
doctor | Health check -- verifies config, permissions, connectivity, MCP server availability |
version | Show kbagent version and check for dependency updates |
context | Print comprehensive usage instructions for AI agents |
Project Management
| Command | What it does |
|---|
project | Add, remove, edit, list, and check status of connected Keboola projects |
org setup | Bulk-onboard all projects from a Keboola organization (uses Manage API) |
Browse & Inspect
| Command | What it does |
|---|
config | List, detail, search, update, delete configurations; generate new config scaffolds |
component | Discover and search Keboola components (AI-powered search, schema inspection) |
job | Browse job history -- list and inspect jobs from the Queue API |
storage | Browse buckets and tables with Snowflake path resolution for shared buckets |
lineage | Analyze cross-project data flow via bucket sharing |
Development
| Command | What it does |
|---|
branch | Full branch lifecycle -- create, switch, reset, delete dev branches; get merge URL |
workspace | Create workspaces, load tables, run SQL queries -- iterative SQL debugging |
tool | List and call MCP tools from keboola-mcp-server (read tools run in parallel) |
sync | Sync project configurations to local filesystem; push with auto-encryption of secrets |
Every command supports --json for structured output and Rich formatting for human-readable output.
Run kbagent --help or kbagent <command> --help for details on any command.
Installation
# Install from GitHub (recommended)
uv tool install git+https://github.com/padak/keboola_agent_cli
# Update to latest version
uv tool install --reinstall git+https://github.com/padak/keboola_agent_cli
# Run without installing (one-off use)
uvx --from git+https://github.com/padak/keboola_agent_cli kbagent --help
For development:
# Clone and install in editable mode
git clone https://github.com/padak/keboola_agent_cli.git
cd keboola_agent_cli
uv pip install -e ".[dev]"
After uv tool install, kbagent is available globally in your shell.
Configuration and credentials
Where is everything stored?
All configuration lives in a single file (permissions: 0600):
- macOS:
~/Library/Application Support/keboola-agent-cli/config.json
- Linux:
~/.config/keboola-agent-cli/config.json
This file contains Storage API tokens for each connected project. Tokens are always masked in CLI output (e.g. 901-...pt0k).
Workspace isolation (per-client directories)
By default kbagent uses a single global config. For teams working with multiple clients, you can create per-directory workspaces so each client folder has its own isolated set of Keboola projects.
# Create a workspace for ACME client
mkdir -p ~/clients/acme && cd ~/clients/acme
kbagent init # creates .kbagent/config.json
kbagent project add --project acme-prod --url https://connection.keboola.com --token ...
# Create a workspace for BigCorp client
mkdir -p ~/clients/bigcorp && cd ~/clients/bigcorp
kbagent init # separate .kbagent/config.json
kbagent project add --project bigcorp-main --url https://connection.eu-central-1.keboola.com --token ...
Now when you cd ~/clients/acme and run kbagent project list, you only see ACME's projects. Each client directory can have its own CLAUDE.md with project-specific instructions.
keboola