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

The curl … | sh one-liner cannot run on Windows. Windows has shipped curl.exe since Windows 10 1803, but it has no sh, so the command fails with 'sh' is not recognized in both cmd and PowerShell. Installing Git for Windows does not fix that. Its installer only puts C:\Program Files\Git\cmd on PATH, while sh.exe lives in usr\bin.

Recommended: PowerShell, no POSIX shell needed. This fetches the same wheel the install script would have:

winget install --id astral-sh.uv -e
$ver = (Invoke-RestMethod "https://api.github.com/repos/keboola/cli/releases/latest").tag_name.TrimStart('v')
uv tool install --force "keboola-cli[server] @ https://github.com/keboola/cli/releases/download/v$ver/keboola_cli-$ver-py3-none-any.whl"
uv tool update-shell

Skip the first line if you already have uv. That line installs uv itself. The whole block works in the in-box Windows PowerShell 5.1, so you don’t need PowerShell 7.

Then open a new shell. uv tool update-shell edits the persisted PATH, and the session you ran it in will not see the change.

Two alternatives:

• Already have Git for Windows? Run the documented script through its bash:

  & "C:\Program Files\Git\bin\bash.exe" -lc "curl -LsSf https://raw.githubusercontent.com/keboola/cli/main/install.sh | sh"

• No Python on the machine? Every release ships a self-contained build. Download keboola-cli2_<version>_windows_amd64.zip from the releases page, unpack it, and put the folder on PATH. It carries its own interpreter and needs neither Python nor uv.

Not via a package manager

There is no WinGet package for kbagent itself, and the Chocolatey package lags far behind the current release. Use one of the three paths above.

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

Note

On macOS and Linux the install script does not touch the PATH of the shell that ran it. If kbagent: command not found comes back right afterwards, the install worked and your PATH has not caught up. Run source $HOME/.local/bin/env, or open a new terminal.

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

Register the project with the CLI so you (or your agent) can reach it:

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

Swap the URL for your own stack. prod is an alias you pick. You use it with --project later, or set it as the default with kbagent project use prod. Add as many projects as you want.

Run this in a real terminal. Interactively you need no token, because project add signs you in through the browser. When it does ask for a token it prompts with hidden input, so the value never lands in your shell history, and that prompt needs a TTY an agent’s tool-run shell does not have.

You sign in once per machine. Every tool reads the same local config, so a project you connected here is already there in Claude Code, Cursor, VS Code and the rest. kbagent project list shows what is registered.

When you need a token

CI, containers, headless hosts, and anything else that cannot open a browser need a Storage API token. A few features need a static token rather than a browser session too: Kai, data apps, the semantic layer, streams, and the Python SDK.

These docs cannot create a token for you. Open your project in the Keboola UI and go to Settings → Developer settings → Agentic CLI. That page builds the exact kbagent project add command for your project and your stack, and it can include a read-only token in it. Copy it from there.

Pass the token as --token, or set KBC_TOKEN so it stays off the command line.

A Storage API token is enough for browsing. Some commands need an admin (master) token, e.g. 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 one with 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 →