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 your operating system:

macOS

Recommended — the prebuilt wheel via the install script:

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

Alternative — uv, if you want to pin to a version or uninstall cleanly:

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

Linux

Recommended — the prebuilt wheel via the install script:

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

Alternative — uv, if you want to pin to a version or uninstall cleanly:

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

Windows

Recommended — uv in PowerShell, the one supported native path on Windows (install uv first if you don't have it):

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

Whichever method you use, kbagent keeps itself current with its own startup update check (kbagent update runs one manually).

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. To create the token, open your project in the browser and go to Project Settings → API Tokens → New Token: give it a description, pick Full Access (you can scope it down later), and click Create — then copy the token right away, it's shown only once.

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.

A Storage API token is enough for browsing. Some commands need an admin (master) token — token create requires the canManageTokens permission, and creating branches or workspaces needs admin privileges. Token types and scoping options are covered in API tokens.

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 across all connected projects

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.

---

Something failing along the way? The Troubleshooting page covers the most common errors and their fixes.

Next: How kbagent works →