kbagent · 1.0 compared with 0.100

kbagent 1.0 at a glance

kbagent 1.0 makes all commands follow the same rules. One command is removed and one is renamed. The old forms that 0.x kept for compatibility are removed too. Each removed form is an error that names the new form. Some defaults, exit codes and messages change. The main changes come first, then the gaps that 0.x already closed, then the full list.

The main changes in 1.0

These are the changes that most often need a change in a script or an agent.

One rule for a missing --project, not three

0.x
What a command did without --project depended on the command. 172 commands stopped with an error, 25 used your active project, and 19 worked on every registered project, for example config list and job list. One of the 19 was workspace gc: without --project it deleted unused workspaces in every registered project.
1.0
Every command uses your active project when you leave out --project. Only --all-projects works on every project:
19 → 0commands that work on every project without being asked
25 → 223commands that use your active project
172 → 0commands that stop and ask for --project

Counts from kbagent 0.99 and 1.0. Commands that delete still ask first. Three commands use --project for something else: init, lineage show and agent prompt-improve.

What to do: choose your project once with kbagent project use. In scripts and agents, give --project on every command, because all your terminals and sessions share the active project. On the 18 read commands, --project and --all-projects already work on 0.100.

Deletes ask, scripts confirm with --yes

0.x
In a script, a confirmation took its answer from the input: echo y | kbagent ... confirmed a delete. branch delete and workspace delete deleted at once, with no question and no --dry-run.
1.0
Without a terminal, the command stops unless you give --yes. branch delete and workspace delete ask, and take --yes and --dry-run. --json still counts as a confirmation.

What to do: add --yes to scripts that confirm.

Mistakes stop before they change data

0.x
A single-value option given twice used the last value with no message: --project x ... --project test acted on test. --text @notes.md saved the file name, not the file.
1.0
Both are errors, and the message says what to fix. On read commands, an option given twice only adds a warning.

What to do: give a single-value option once. Use --description-file or another --X-file option for text from a file.

One short flag for each option, on every command

0.x
A short flag worked on some commands and not on others, and seven short flags meant different options in different commands. For example, -d was --directory, --body, --deny or --description.
1.0
Each short flag means one option, and every command with that option accepts it:
24 → 225-p for --project
2 → 40-n for --name, as in the Azure CLI
1 → 20-t for --type
0 → 14-L for --limit, as in the GitHub CLI

Commands that accept the short flag, before and after. Removed, because they meant a different option in some commands: -c, -r and -l everywhere, and -d, -f, -m, -n and -v where they did not mean --directory, --feature, --message, --name and --verbose.

What to do: replace a removed short flag with the long option name. Long names work on 0.x and on 1.0.

A failure is never reported as success

0.x
A read across projects ended with exit code 0 when one project failed. The same error could end with different exit codes in different commands.
1.0
Exit code 1 after the full output. Each error code has one exit code, in one published list.

What to do: check scripts that test for a specific exit code.

--json always answers in JSON

0.x
A typo, a wrong value or a crash printed no JSON. --json worked only before the command.
1.0
Every run prints one JSON document, errors included. Only --help still prints help, and a --stream command still prints one JSON line per event. kbagent config list --json works too.

What to do: read error.code for every exit code.

One word for one thing

0.x
The project you chose with project use was the "pin" or the "default project". The branch you chose with branch use was the "active branch", and the REST API called it "pin" too:
pindefault projectactive branch
In Keboola, "default branch" already means the production branch.
1.0
One name everywhere:
active projectactive branch
project use prints Active project: prod. The JSON fields and the configuration file do not change.

What to do: nothing, unless a script reads the text of project use.

kbagent serve follows the same rules

0.x
Over HTTP, 26 routes used production and list routes read all projects, while the command line used the active branch and project. Most errors answered HTTP 502.
1.0
The same project and branch as the command line, HTTP status codes that match the error, and PATCH for partial updates.

What to do: send branch_id: 0 for production and all_projects=true for all projects.

Dangerous gaps that 0.x already closed

These could delete data, act on the wrong project, or let a command through a safety setting. They did not wait for 1.0: kbagent 0.96 to 0.100 fixed them. If you run an older 0.x version, update.

Fixed in 0.100.0

Safety options that did nothing

Before
storage delete-bucket and storage file-delete had a --yes option, but never read it. They deleted without asking. delete-bucket --force also deleted a shared bucket, although the help says to unshare it first.
Now
Both ask in a terminal, and --yes skips the question. --force no longer deletes a shared bucket.
Fixed in 0.96.1 to 0.100.0

A permission setting with gaps

Before
--deny-writes, --deny-destructive and saved permission policies did not apply to kbagent http and kbagent search, so kbagent http delete ran under --deny-destructive. --deny-destructive also did not stop sync push --force, a token refresh or a password reset. Over kbagent serve, only two groups of routes were checked.
Now
Every command and every kbagent serve route is checked, except the health and documentation routes. Commands that reset a password, invalidate a token or replace all variables count as destructive.

Other dangerous behavior that 0.x fixed

  • workspace gc without --project deleted unused workspaces in every registered project. When it could not list the configurations of a project, it took every sandbox workspace in that project as unused. 0.100.0
  • sync push --project B in a folder of project A created the configurations of project A in project B. 0.100.0
  • sync push deleted a configuration in Keboola when its local folder was missing, also without --force. 0.96.1
  • A second flow delete of the same flow removed it from the trash for good. 0.100.0
  • job run --idempotency-key, repeated after a lost answer, started a second job. 0.100.0
  • Over kbagent serve, DELETE /flows/...?dry_run=true ran the real delete. 0.100.0
  • Removing the active project made the next project active without a notice. 0.100.0
  • Commands used the branch from branch use and did not say so. Now each command names the project and branch it uses. 0.96.1
  • data-app password printed the password, so it went into an AI agent's chat history. Now it prints the password only with --reveal. 0.96.1
Other changes in 0.x
  • Commands that change several items end with exit code 1 after a failed item (0.98.0).
  • --project also accepts a project ID (0.96.1).
  • --all-projects on the 18 read commands, so one script works on 0.x and on 1.0 (0.100.0).
  • kbagent update stays on 0.x until the move date. kbagent update --major moves earlier (0.100.0).

When 1.0 reaches you

Release day

New installs get 1.0

Install script, PyPI, Homebrew, apt and rpm (Chocolatey and winget after their package review). Also CI pipelines that install kbagent without a version, and package-manager upgrades.

The next 28 days

Installs that update themselves stay on 0.x

kbagent 0.100 and later shows a notice with the move date. kbagent update --major moves to 1.0 at once. kbagent 0.100.5 accepts the 1.0 names, so you can change scripts before the move.

Day 28

They move to 1.0

An install that updates itself moves to 1.0, also a version older than 0.100. The first command that changes data after the move stops once and links to the migration guide.

To stay on 0.x, set KBAGENT_AUTO_UPDATE=false. In CI, also install keboola-cli<1. A Homebrew, apt, rpm, Chocolatey or winget package stays on 0.x with a hold in the package manager, for example brew pin or apt-mark hold. 0.x gets security and data-loss fixes until day 28.

All changes in 1.0

Grouped by impact, from the changes that can change which data a command touches to the additions that need nothing. Open a row to see the old and the new behavior and what to do.

Show changes for
Changes which project, branch or data a command usesCheck these first. Without a change, a script can work on other data than before, or stop.
Every command uses your active project by defaultProject and branchScripts and CI, AI agents, terminal users
0.x18 read commands, for example config list, job list, storage buckets and search, read all registered projects when you did not name one. 172 commands stopped with an error, and 25 used your active project.
1.0Every command uses one project: --project, else KBAGENT_PROJECT, else the one from kbagent project use, else your only project. --all-projects works on all. Commands that delete still ask first.

What to do: on the 18 read commands, add --project or --all-projects. Both work on 0.100. In scripts and agents, give --project on every command.

List routes, token refresh and workspace clean-up use your active projectkbagent servekbagent serve clients
0.xA list request without project read all projects. POST /org/refresh with an empty body replaced the tokens of all projects. POST /workspaces/gc without project was refused.
1.0The active project, as on the command line. all_projects=true reads all.

What to do: send project or all_projects=true.

Routes use your active branchkbagent servekbagent serve clients
0.x26 routes used production when the request had no branch_id. The same commands on the command line used the active branch.
1.0The active branch, as on the command line. branch_id: 0 is production.

What to do: send branch_id: 0 for production.

A single-value option given twice is an error on commands that change dataOptions and inputScripts and CI, AI agents
0.xThe last value won, with no message. storage delete-bucket --project x ... --project test acted on test.
1.0An error on commands that create, change or delete. A warning on read commands.

What to do: give a single-value option once.

List options take one value each time you give themOptions and inputScripts and CI, AI agents
0.xNine list options took one comma list. sharing share --target-project-ids 11 --target-project-ids 22 shared with 22 only.
1.0Repeat the option once per value: --target-project 11 --target-project 22. A comma in an ID or a fixed value is an error. The options have singular names (see below).

What to do: repeat the option instead of a comma list. Check scripts that repeat one of these options. They now send all values.

@file in a text option is refusedOptions and inputScripts and CI, AI agents, terminal users
0.x--text @notes.md saved the text "@notes.md" in place of the file content.
1.0An error that names --description-file, --value-file or --sql-file.

What to do: use --description-file, --value-file or --sql-file for text from a file.

A confirmation needs a person or --yesConfirmationsScripts and CI, AI agents
0.xIn a script, the answer came from the input: echo y | kbagent ... confirmed a delete.
1.0Without a terminal, the command stops with CONFIRMATION_REQUIRED unless you give --yes. --json still counts as a confirmation.

What to do: add --yes to scripts that confirm.

branch delete and workspace delete ask firstConfirmationsScripts and CI, terminal users
0.xBoth deleted at once, with no question, no --yes and no --dry-run.
1.0Both ask in a terminal, and take --yes and --dry-run.

What to do: in scripts, add --yes or use --json.

project remove asks firstConfirmationsScripts and CI, terminal users
0.xIt removed the project and its stored token at once, with no question and no --dry-run.
1.0It asks in a terminal, and takes --yes and --dry-run. Without a terminal it stops with CONFIRMATION_REQUIRED unless you give --yes or --json.

What to do: in scripts, add --yes or use --json.

flow schema --full and flow validate use your active projectProject and branchScripts and CI, AI agents
0.xWithout --project, they used the flow schema bundled with kbagent.
1.0They download the current schema of your active project. With no project registered, they use the bundled schema as before. When the download fails, flow schema --full ends with an error and flow validate runs only its basic checks.

What to do: nothing, unless a CI job has a registered project but no access to its stack.

Short flags with a second meaning are removedOptions and inputScripts and CI, AI agents, terminal users
0.xSeven short flags meant different options in different commands. For example, -n was --limit in changelog and --name in stream detail.
1.0Removed: -c, -r, -d on --body, --deny and --description, -f on --format, -l and -n on --limit, -m on --mode, and -v on changelog --full. A removed short flag is a usage error (exit code 2).

What to do: use the long option name. For --limit, -L works on 1.0.

After the automatic move, the first change stops onceUpdatesScripts and CI, AI agents
1.0After kbagent updates itself from 0.x, the first command that changes data stops once with UPDATED_ACROSS_MAJOR and a link to the migration guide. Run it again and it works. A move with kbagent update --major does not stop anything.

What to do: check the command against this page, then run it again.

data-app stop suspends the appData appsScripts and CI, AI agents, kbagent serve clients
0.xstop stopped the app, and stop --wait waited until it was stopped.
1.0The app is suspended, and the next request to its URL wakes it. stop --wait and --timeout do nothing. start and stop fail on an app that no deployment serves, and the message names data-app deploy.

What to do: do not expect a stopped app to stay stopped. Run data-app deploy once for an app that start or stop refuses.

data-app output follows the /v2 APIData appsScripts and CI, AI agents, kbagent serve clients
0.xThe output had desired_state and last_start_timestamp, and create had managed_git_repo_id. --type accepted 7 types.
1.0These keys are removed. state is notDeployed, starting, running, suspended or disabled. detail, create and deploy add deployment_id. --type accepts only python-js and streamlit, also for a data app that sync push creates.

What to do: read state and deployment_id.

sync push --force keeps a config that changed in KeboolaSyncScripts and CI, AI agents
0.xA config or row deleted locally was deleted in Keboola, also when someone had changed it there since the last pull.
1.0Such a delete is a conflict that --force never overrides. Push lists it in refused_deletions.

What to do: run sync pull, then delete again.

A moved config directory keeps its configSyncScripts and CI, AI agents
0.xA directory moved with mv or git mv was a new config: push created a copy, and push --force deleted the original.
1.0The directory keeps its config id. Two directories with one id, or swapped directories, are a conflict: nothing is created, changed or deleted for them, also with --force or --theirs.

What to do: give each config id one directory, or use config rename --directory.

A broken _config.yml is an error, not a deleteSyncScripts and CI, AI agents
0.xA _config.yml that was not valid YAML read as missing, so sync push --force deleted the config in Keboola. An unknown top-level key was dropped without a message.
1.0sync diff and sync push report SYNC_LOCAL_FILE_INVALID in errors[] and end with exit code 1. They do not change that config or its rows, also with --force.

What to do: fix the file that the error names. Put extra configuration keys under _configuration_extra.

Changes exit codes and errorsThe work is the same. A script that checks exit codes or error codes can react in another way.
A read that failed for one project ends with exit code 1ErrorsScripts and CI, AI agents
0.xExit code 0. The failure was only in the output.
1.0Exit code 1 after the full output. Exit code 5 when no project is registered.

What to do: treat exit code 1 as "some projects failed". The other results are still in the output.

Each error code has one exit codeErrorsScripts and CI, AI agents
0.xThe same error ended with different exit codes in different commands.
1.0One exit code per error code, in one published list. Some commands now end with another code, for example transformation create with invalid input: 1 → 2.

What to do: check scripts that test for a specific exit code.

More specific error codesErrorsScripts and CI, AI agents
0.xkai and semantic-layer reported CONFIG_ERROR also when the cause had its own code.
1.0AUTH_NOT_SUPPORTED_ON_STACK or FEATURE_NOT_ENABLED. Some error types change, for example ALREADY_EXISTS is now a conflict.

What to do: check agents and scripts that look for CONFIG_ERROR.

Every run with --json prints one JSON documentJSON outputScripts and CI, AI agents
0.xA typo, a wrong value, a crash or Ctrl+C printed no JSON.
1.0Always one JSON document with an error code. --help and --stream keep their output. The exit codes do not change.

What to do: read error.code for every exit code.

A wrong value gives a clear error, not a crashOptions and inputScripts and CI, AI agents
0.xSome wrong values ended in a Python traceback with exit code 1.
1.0INVALID_ARGUMENT with exit code 2, and the message names the option.

What to do: nothing, unless a script expects exit code 1 for these mistakes.

A command group without a command is an errorJSON outputScripts and CI, AI agents
0.xkbagent storage ended with exit code 0 and printed nothing.
1.0Exit code 2 and the help.

What to do: nothing for complete commands.

--branch with several projects has one error codeErrorsScripts and CI, AI agents
0.xsync pull, sync diff and sync push with --all-projects and --branch gave USAGE_ERROR, the other commands INVALID_ARGUMENT.
1.0INVALID_ARGUMENT everywhere. The exit code stays 2.

What to do: check scripts that look for USAGE_ERROR here.

HTTP status codes follow the errorkbagent servekbagent serve clients
0.xMost errors answered HTTP 502, also an invalid request or an invalid token.
1.0400, 401, 403, 404, 409 or 502 by the kind of error, and 500 for an internal error. The error has the same fields as on the command line.

What to do: use error.code, not only the status.

sync push refuses packages it cannot readSyncScripts and CI, AI agents
0.xA pyproject.toml without a usable dependency list could clear the packages of a config in Keboola.
1.0Push keeps the inline or the remote packages. A new config with neither is refused with COMPANION_UNREADABLE and exit code 1.

What to do: fix pyproject.toml, or add packages inline.

branch create on __env__ ends with exit code 0Project and branchScripts and CI, kbagent serve clients
0.xIt created the branch, then ended with exit code 5, so a retry created a second branch.
1.0Exit code 0, activated: false and the warning ACTIVE_BRANCH_NOT_STORED. branch reset does nothing, and branch use is refused before any API call.

What to do: give --branch on the later commands.

Changes the text outputOnly for scripts that read the text output. With --json, nothing changes.
Each failed item is one Error: lineTerminal outputScripts and CI, terminal users
0.xFive different forms, depending on the command, and some of them on stderr.
1.0One line Error: <item>: <message> on stdout.

What to do: read failed items from stdout, or use --json.

A summary line at the endTerminal outputScripts and CI, terminal users
0.xOnly 5 commands that handle several items printed a Failed: summary line.
1.0One Success: ... or Failed: N of M ... line at the end.

What to do: if a script parses the text output, ignore the last line or use --json.

auth login messages go to stderrTerminal outputScripts and CI
0.xMessages on stdout, mixed with the result.
1.0Messages on stderr. The result stays on stdout.

What to do: if a script reads these messages, read stderr.

One word for the saved choice: activeTerminal outputTerminal users
0.x"Pin" and "default project" for the chosen project, "active branch" for the chosen branch, and "pin" again for the branch in the REST API.
1.0"Active" everywhere. project use prints Active project: prod.

What to do: nothing, unless a script reads that text.

Old forms that are removed1.0 removes them. Each one is an error that names the new form.
stream delete --force becomes --yesConfirmationsScripts and CI, terminal users
0.x--force skipped the confirmation. semantic-layer import --yes did nothing.
1.0Use stream delete --yes, and run semantic-layer import without --yes. The old flags are a usage error (exit code 2).

What to do: change the flags.

Partial updates use PATCHkbagent servekbagent serve clients
0.x4 routes changed part of an item with PUT.
1.0PATCH. PUT answers HTTP 405, and the message names PATCH. PUT of the configuration variables with replace: true still replaces all variables.

What to do: switch these requests to PATCH.

project add --project becomes --aliasOptions and inputScripts and CI, AI agents, terminal users
0.xproject add and project create took the name of the new project as --project, which names an existing project everywhere else.
1.0--alias. --project and -p are a usage error that names --alias.

What to do: use --alias. It works on 0.100.3 and later too.

project refresh --all becomes --all-projectsOptions and inputScripts and CI, kbagent serve clients
0.xproject refresh --all, and refresh_all in POST /org/refresh.
1.0--all-projects and all_projects, as everywhere else. --all is a usage error, and refresh_all answers HTTP 422. Both messages name the new name.

What to do: use --all-projects. It works on 0.100.3 and later too.

branch merge is removedProject and branchScripts and CI, AI agents, kbagent serve clients
0.xbranch merge printed the merge URL of the Keboola UI and reset the active branch. Over REST: GET /branches/{project}/merge-url.
1.0The command and the route are removed. The error names kbagent merge-request.

What to do: merge a dev branch with kbagent merge-request, or in the Keboola UI.

--id becomes --merge-request-id and --task-idOptions and inputScripts and CI, AI agents
0.xThe 10 merge-request commands and the 7 agent commands took --id.
1.0--merge-request-id and --task-id. --id is a usage error that names the new option.

What to do: change the option. The new names work on 0.x too.

reference-data --id becomes --reference-data-idOptions and inputScripts and CI, AI agents
0.xsemantic-layer reference-data get and delete took the record as --id.
1.0--reference-data-id. --id is a usage error that names the new option. The REST routes do not change.

What to do: change the option. It works on 0.100.5 too.

agent commands take --task-id and --run-id onlyOptions and inputScripts and CI, AI agents
0.xA task or a run could be a positional argument: agent show TASK_ID.
1.0--task-id and --run-id. A positional ID is a usage error that names the option.

What to do: use the options. They work on 0.x too.

stream detail and stream delete take --source-idOptions and inputScripts and CI, AI agents
0.xThe source was a positional argument: stream delete SOURCE_ID.
1.0--source-id. A positional ID is a usage error that names the option. stream detail --name also matches a source id.

What to do: use --source-id. It works on 0.100.5 too.

List options have singular namesOptions and inputScripts and CI, AI agents
0.xPlural names: org setup --project-ids, sharing share --target-project-ids and --target-users, the semantic-layer options --metrics, --new-metrics, --tables and --types, workspace load --tables and --columns.
1.0--project-id, --target-project, --target-user, --metric, --new-metric, --table-id, --type and --column, given once per value. An old name is a usage error that names the new one.

What to do: use the new names. They work on 0.100.5 too.

A file is read with --file or --X-file, not @fileOptions and inputScripts and CI, AI agents, terminal users
0.x--configuration @cfg.json read the file, and --stdin read the input. Each command named its file option in another way, for example lineage --load, --text and --file, --from-file or --input.
1.0The main input file is --file. A value is --X inline or --X-file PATH, for example --configuration-file cfg.json or --description-file notes.md. - as the path reads the input. @file, --stdin, -l and the old option names are errors that name the new form.

What to do: use the --X-file options and the new names. They work on 0.100.5 too, except inline JSON in dev-portal --data.

create-table --not-null becomes --not-null-columnOptions and inputScripts and CI, AI agents
0.xstorage create-table --not-null COL.
1.0--not-null-column COL, once per column. --not-null is a usage error that names the new option. add-column --not-null does not change.

What to do: change the option. It works on 0.100.5 too.

scope request-delete becomes request-cancelOptions and inputScripts and CI, AI agents
0.xsemantic-layer scope request-delete cancelled a pending request. Its permission key was semantic-layer.scope.request-delete.
1.0semantic-layer scope request-cancel, with the permission key semantic-layer.scope.request-cancel. The old name is a usage error that names the new one. A saved policy with the old key matches nothing.

What to do: use request-cancel, and change the key in saved policies. Both work on 0.100.5 too.

New, nothing to changeAdditions. Everything that worked before still works.
A warning when a project setting changes in your active projectJSON outputAI agents, Scripts and CI
1.0Commands that change project settings, such as project edit and project remove, add the same warning as deletes when the project comes from project use.

What to do: nothing. Give --project to make the target explicit.

--dry-run on project member-set-role and project invitation-cancelOptions and inputScripts and CI, AI agents
1.0Both show the member or invitation they would change, and change nothing.

What to do: nothing.

--json works after the command, -h shows helpOptions and inputEveryone
0.x--json worked only before the command. -h was an unknown option.
1.0kbagent config list --json works. -h shows help.

Note: if a script must also run on 0.x, keep --json first.

-p and other short flags on every commandOptions and inputEveryone
0.x-p worked on 24 of the 228 commands with --project.
1.0Every command with the option accepts its short flag: -p for --project, -n for --name, -t for --type, -L for --limit, -o for --output, -e for --email, and the others.

Note: if a script must also run on 0.x, use the long option names.

New fields in the JSON outputJSON outputScripts and CI, AI agents
1.0 addsexit_code, schema_version, where the project came from (project_source), a warning when a destructive or admin command uses a project or branch saved with project use or branch use, and the error code of each failed item. A failed item has its error text in message, no longer in error or reason. A few other keys that 0.x kept only for compatibility are removed, and project current reports source: "active_project" instead of "pin". The migration page lists them (rows 41 to 46).
Responses say which project and branch they usedkbagent servekbagent serve clients
1.0 addsKbagent-Targets and Kbagent-Warnings response headers, with the same content as in the JSON output of the command line.
Update notes list every breaking change you skippedUpdatesTerminal users, AI agents
1.0 addsAfter an update, the "What's new" notice lists the breaking changes of every version that the update skipped.
auth login --no-openTerminal outputTerminal users
1.0 addsSign in with a device code. kbagent opens no browser and prints the link and the code.
Help shows the wait and timeout defaultsTerminal outputTerminal users
1.0 addsEach command with --wait says in its help whether it waits by default and how long. No default changed.
kbagent context <group>AI agentsAI agents
1.0 addsThe agent guide for one command group, for example kbagent context storage. The command list now comes from the commands themselves, so it matches --help.