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: the installer only puts C:\Program Files\Git\cmd on PATH, and 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. It installs uv, not kbagent. 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, so a kbagent: command not found immediately afterwards is a PATH problem, not a failed install. 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

There are two ways in. Sign in through your browser if you can, and reach for a Storage API token only where a browser cannot open.

Sign in with your browser (recommended)

If you have a browser on this machine, you need no token at all. One command signs you in and registers every project the session can reach:

kbagent auth login --stack https://connection.keboola.com --register-projects

Swap the URL for your own stack. kbagent opens a browser for the login (PKCE); if it cannot, it prints a code you type in on another device. Afterwards kbagent project list shows what got registered.

Note

Browser login needs a human at a browser, so it is not usable from CI or an unattended agent task. A few features also still require a static token rather than a session (Kai, data apps, semantic layer, streams, the Python SDK). Use the token route below for those.

Or connect with a Storage API token

This is the route for CI, headless hosts, containers, and anywhere no browser can open.

These docs cannot create a token for you. Open your project in the browser at keboola.com 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. Copy the value right away, it is shown only once.

Tip

If you are already in the UI, the in-product Connect your agent guide is the easier route: one switch and it mints a scoped read-only token for you.

Then register the project. Leave --token off and kbagent prompts for it with hidden input, so the value never lands in your shell history or on a shared command line:

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

prod is an alias you pick. You use it with --project later, or set it as the default with kbagent project use prod. In a script or CI, pass the token through the KBC_TOKEN environment variable instead of a flag.

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 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 →