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: pass --conversation-id "<unique-id>" (e.g. session UUID) on every kbagent call -- kbagent --json --conversation-id <id> <command>. All API requests include it as the X-Conversation-ID header for platform observability. Do not use a standalone export: agent harnesses (Claude Code included) do not persist shell state between tool calls, so the variable is gone by the next command -- and prefixing each command with export ... stops it matching a Bash(kbagent ...) permission allow-rule. For a whole session, set KBAGENT_CONVERSATION_ID in the harness's own env block (Claude Code: settings.json -> env) instead.
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

…(truncated)