Get started with kbagent

This walkthrough takes you from nothing to browsing a real project with kbagent in a few minutes. Follow it top to bottom for a single project; the Connect more section covers multi-project and organization setup.

Step 1 — Install

Pick the line for your OS.

macOS / Linux — the prebuilt wheel via the install script:

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

Windows — install with uv in PowerShell (install uv first if you don’t have it):

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

Any OS, from source — uv works on macOS, Linux, and Windows, auto-updates, and can be pinned:

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

Confirm it’s on your PATH (all platforms):

$ kbagent --version
kbagent v0.66.0

Tip

On any platform you can also run kbagent through uvx without installing (uvx --from 'git+https://github.com/keboola/cli' kbagent …) — handy for a one-off or in CI.

Step 2 — Connect your project

For one project you need a Storage API token and your stack URL:

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

prod is an alias you pick — you’ll use it with --project later, or set it as the default with kbagent project use prod.

Caution

kbagent only talks to your Keboola stack, but the config directory stores project credentials — treat it as sensitive, and never paste tokens into shared terminals or commit them.

Step 3 — Verify the connection

kbagent doctor checks your configuration and connectivity. Once a project is connected it confirms the link and flags anything else worth doing (like installing the agent plugin):

You can also test connectivity on its own with kbagent project status.

Step 4 — Browse the project

Explore what’s there. Recent jobs:

kbagent job list --limit 5    # recent jobs (shown above)
kbagent project list          # connected projects
kbagent config list           # configurations in the default project

Step 5 — Search

Find configs, tables, buckets, and flows by name or content:

kbagent search "shopify"

Note

kbagent search uses Keboola’s Global Search by default. If a project doesn’t have that feature enabled, kbagent says so — add --search-type config-based to scan configurations directly instead.

Step 6 — Go further

• Add --json to any command for machine-readable output — this is what an AI agent consumes.

• Set a conversation ID when an agent drives kbagent, so platform observability can correlate the session (adds an X-Conversation-ID header):

  export KBAGENT_CONVERSATION_ID="<unique-id>"

Connect more projects

Several projects — register each with its own Storage token (project add), or bulk-onboard with a Manage API token:

KBC_MANAGE_API_TOKEN=xxx kbagent --allow-env-manage-token \
  org setup --project-ids 901,9621 --url https://connection.keboola.com --yes

A whole organization (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

Read commands then fan out across every connected project — see multi-project.

---

Next: How kbagent works →