kbagent

name: kbagent description: > Use when working with Keboola Connection projects via kbagent CLI. Covers: exploring and searching configurations (extractors, writers, transformations), browsing job history, analyzing cross-project data lineage, calling MCP tools across multiple projects, managing development branches, debugging SQL in temporary workspaces, bulk-onboarding organizations, syncing project configs as local files (GitOps), git-branching with Keboola dev branch isolation, sharing buckets across projects, linking shared data, encrypting secrets for MCP tool call workflows, uploading/downloading Storage Files with tag management, and syncing storage metadata and job history. Triggers: kbagent, Keboola project, keboola configs, keboola jobs, keboola lineage, keboola transformations, keboola MCP tools, keboola workspace, SQL debugging, keboola branches, keboola organization, keboola sharing, bucket sharing, link bucket, keboola sync, keboola git, keboola gitops, sync pull, sync push, sync diff, branch-link, search configs, find in configurations, audit configurations, input mapping migration, remove input mapping, Snowflake paths, MULTI_STATEMENT_COUNT, statement count error, SQL transformation migration, keboola encrypt, encrypt secrets, encrypt credentials, encrypt password, keboola encryption API, #password, #api_token, KBC::ProjectSecure, safe config write, dry-run preview, fresh fetch before edit, stale local config file, config version overwrite, default bucket, output bucket, default_bucket, storage.output, raw mode bucket override, custom output bucket name, data app, data apps, keboola data app, streamlit app, streamlit deployment, flask app, fastapi app, node app, python-js, deploy data app, data-app create, data-app deploy, data-app password, data-app start, data-app logs, container logs, app logs, tail logs, build logs, app stdout, app stderr, troubleshoot data app, debug data app, app proxy, simpleAuth, app auto-suspend, configVersion, redeploy contract, Data Science API, /apps endpoint, app password, KBC::Project ciphertext, data-app secrets, app secrets, app runtime secrets, secrets-set, secrets-list, secrets-get, secrets-remove, encrypt app secret, app environment variable, validate repo, validate-repo, data-app golden rule, pre-flight repo check, repo structure check, local workspace, project directory, kbagent init, invite user, invite member, project invitation, manage members, list members, remove member, change role, project role, bulk invite, invite from CSV, project access, member management, manage token prompt, --allow-env-manage-token, KBC_MANAGE_API_TOKEN, feature flag, feature flags, list features, project features, user features, enable feature, disable feature, set feature flag, add feature, remove feature, early-adopter-preview, direct-access, pay-as-you-go, /manage/features, super admin token, super-admin feature, stack feature catalogue, data stream, data streams, keboola data streams, stream source, OTLP, OpenTelemetry, otel, OTLP endpoint, OTEL_EXPORTER_OTLP_ENDPOINT, telemetry ingest, logs metrics traces, stream create-source, stream detail, stream list, stream delete, otlp source, http source, stream-in, ingest endpoint, semantic-layer, semantic layer, semantic-layer model, metastore, semantic-metric, semantic-dataset, semantic-relationship, semantic-constraint, semantic-glossary, add metric, edit metric, rename metric, remove metric, validate model, validate semantic layer, promote model, semantic-layer build, semantic-layer export, semantic-layer diff, semantic-layer import, semantic-layer token, metric SQL, dataset FQN, constraint rule, threshold constraint, 4-band health, _critical _warning _healthy _review, CODE_METRIC, DIM_METRIC_THRESHOLD, dangling metric FK, orphaned constraint, phantom field, AGG on STRING, SUM on PCT, deep validate, sl, kbagent sl, semantic layer wizard, sl-build, sl-add, sl-edit, reference data, semantic-layer reference-data, chart of accounts, COA, dimension members, account list, dimension data, member list, developer portal, dev-portal, apps-api, register component, vendor app, portal property, ui-options, encryption portal, defaultBucket portal, app icon, configurationSchema portal, publish component, deprecate component, kbagent dev-portal, portal identity, vendor login, service account portal.

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. Prefer CLI commands over MCP tools where both exist (config update over update_config, config detail over get_configs). Lower latency, native dry-run/diff support, consistent JSON shape, and fewer parameter-shape footguns. Use MCP only for operations the CLI does not cover (e.g. str_replace, list_append, run_component).
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
# --prerelease=allow is required (issue #324): keboola-mcp-server pins a
# pre-release-only transitive dep (toon-format), which uv refuses by default.
uv tool install --prerelease=allow keboola-mcp-server
kbagent doctor --fix

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