Getting started with kbagent

Install kbagent, connect it to a project, and run your first commands. This takes a couple of minutes.

Install

The recommended install is the prebuilt wheel via the install script:

curl -LsSf https://raw.githubusercontent.com/keboola/cli/main/install.sh | sh

Or install from source with uv (auto-updates, version-pinnable):

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

Check the version:

$ kbagent --version
kbagent v0.66.0

Connect a project

How you authenticate depends on how much you want to manage.

A single project — use a Storage API token:

kbagent project add --project prod \
  --url https://connection.keboola.com --token YOUR_TOKEN

A whole organization — use a Manage API token (org admin). kbagent registers every project and mints per-project tokens:

KBC_MANAGE_API_TOKEN=xxx kbagent --allow-env-manage-token \
  org setup --org-id 123 --url https://connection.keboola.com --yes

Caution

kbagent never sends your token anywhere except your Keboola stack, but treat the config directory as sensitive — it stores project credentials. Don’t paste tokens into shared terminals or commit them.

Verify with doctor

kbagent doctor runs health checks on your configuration and connectivity. Once a project is connected it confirms the link and flags anything still worth doing:

Run your first commands

Once a project is connected, explore it. Add --json / -j for machine-readable output (what an agent uses):

kbagent job list --limit 5    # recent jobs (shown above)

Other everyday reads:

kbagent project list          # connected projects
kbagent config list           # configurations in the default project
kbagent search "shopify" --search-type config-based   # find configs by name/content

Note

kbagent search uses Keboola’s Global Search by default. If a project doesn’t have that feature enabled, kbagent tells you and you can fall back to --search-type config-based to scan configurations directly.

Set a conversation ID (for agents)

When an AI agent drives kbagent, set a conversation ID so platform observability can correlate the session — every request then carries an X-Conversation-ID header:

export KBAGENT_CONVERSATION_ID="<unique-id>"

Next steps

• Commands — the full command groups.
• Workflows — dev branches, GitOps sync, and real use cases.
• For AI agents — the Claude Code plugin and sandboxing.