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:

$ kbagent doctor
  PASS  Config file: config.json exists with correct permissions.
  PASS  Config parseable: valid JSON with 1 project(s).
  PASS  Project 'docs-demo': Connected to https://connection.europe-west3.gcp.keboola.com
        (project: L0 - Shopify, id: 264) in 163ms
  PASS  CLI version: kbagent v0.66.0
  PASS  Conversation ID: X-Conversation-ID: docs-capture
  WARN  Claude Code plugin: not installed. Run /plugin marketplace add keboola/cli

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
                                        Jobs
┏━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ Project   ┃   Job ID ┃ Status  ┃ Component           ┃ Created            ┃ Duration ┃
┡━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━┩
│ docs-demo │ 90878516 │ success │ keboola.flow        │ 2026-07-13T07:16:… │   1m 14s │
│           │ 90878596 │ success │ keboola.snowflake-… │ 2026-07-13T07:16:… │      36s │
│           │ 90878900 │ success │ keboola.data-apps   │ 2026-07-13T07:17:… │      20s │
└───────────┴──────────┴─────────┴─────────────────────┴────────────────────┴──────────┘

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.