kbagent

kbagent -- Keboola Agent CLI

How to use this skill

This skill contains everything you need. The decision table below maps goals to commands. For detailed workflows, see the references/ docs linked at the bottom.

For command flags and parameters, use kbagent <command> --help (e.g. kbagent config new --help).

If kbagent is not installed or you need the full standalone reference, run kbagent context.

Rules

1. Always use --json: kbagent --json <command> for parseable output
2. Set conversation ID: before first kbagent call, run export KBAGENT_CONVERSATION_ID="<unique-id>" (e.g. session UUID). All API requests include this as X-Conversation-ID header for platform observability.
3. Multi-project by default: read commands query ALL connected projects in parallel -- no need to loop
4. Write commands need --project: specify the target project alias
5. Tokens are always masked in output -- this is expected, not an error
6. Always fetch fresh before write: configs change between commands and across users. Re-fetch from the API immediately before any update; never reuse a config dump from earlier in the session. Stale local files are how vN+1 silently overwrites someone else's vN changes.
7. Always --dry-run first for destructive operations (config update, config delete, storage delete-*, branch delete, sync push). Show the user the diff and get explicit confirmation before applying.
8. There is no MCP passthrough. kbagent tool list / tool call and agent --type mcp_tool were removed in v0.85.0 -- every catalog tool has a native command. If a user names an old tool (update_config, get_configs, query_data, ...), map it via docs/mcp-migration.md in the repo and run the native command instead.
9. Never auto-run jobs after config changes. config update (or sync push) and job run are always two separate steps. Wait for the user to confirm before triggering a run -- do not chain them.

Safe write workflow

For any operation that modifies a Keboola config or storage object, follow this order. See safe-write-workflow for the detailed runbook with examples and anti-patterns.

1. Fetch fresh from the API (e.g. kbagent --json config detail ...) -- never reuse a local file from earlier in the session.
2. Compute the change in memory or via jq/Python. Keep the diff small and targeted; prefer --set path=value or --merge over full-config replacement.
3. Preview with --dry-run (e.g. kbagent --json config update ... --dry-run). Show the user what will change.
4. Get user confirmation before re-running the same command without --dry-run.
5. Verify by re-fetching the config and inspecting the new version.
6. Stop. Do NOT auto-trigger job run, transformation execution, or any side-effecting follow-up. The user decides when to run.

When working inside a git repository or project directory, run kbagent init (or kbagent init --from-global) once to create a local .kbagent/ workspace. After that, kbagent works from any subdirectory of the project -- no need to cd ~ first.

Choosing the right approach

Sync pull notable flags

Response format

All JSON responses follow one of two shapes:

Success:

{"status": "ok", "data": ...}

Error:

{"status": "error", "error": {"code": "ERROR_CODE", "message": "...", "retryable": true}}

Check the retryable field -- if true, retry the operation.

For detailed response parsing rules and common pitfalls, see gotchas.

Workflow references

First-time setup

If kbagent is not yet installed:

uv tool install git+https://github.com/keboola/cli
kbagent doctor

Then add projects:

# Single project
kbagent --json project add --project prod --url https://connection.keboola.com --token YOUR_TOKEN

# Or bulk-onboard from organization (org admin)
# Manage token: interactive prompt by default; for CI add --allow-env-manage-token
# alongside KBC_MANAGE_API_TOKEN (required since v0.29.0).
KBC_MANAGE_API_TOKEN=xxx kbagent --allow-env-manage-token --json org setup --org-id 123 --url https://connection.keboola.com --yes

# Or onboard specific projects (any project member, uses Personal Access Token)
KBC_MANAGE_API_TOKEN=xxx kbagent --allow-env-manage-token --json org setup --project-ids 901,9621,10539 --url https://connection.keboola.com --yes

Installing this plugin

This plugin ships through Keboola's keboola-claude-kit marketplace, published from keboola/ai-kit. To (re)install it in Claude Code:

/plugin marketplace add keboola/ai-kit
/plugin install kbagent@keboola-claude-kit

Copies installed from the older keboola-agent-cli marketplace (this CLI's own repo) still work and still update, but that entry is deprecated -- the two lines above are how a user moves to the maintained one.