keboola-cli 0.98.0__tar.gz → 0.99.0__tar.gz

{keboola_cli-0.98.0 → keboola_cli-0.99.0}/CLAUDE.md

@@ -467,7 +467,7 @@ kbagent auth register-projects [--stack URL|alias] [--all] [--project-id ID ...]
 #   bearer token, and revoking the session is a host-operator action, not a remote one. `/auth/*`
 #   is also the FIRST router to enforce the `permissions` policy: every route declares
 #   `Depends(require_permission(...))`, so a denial answers HTTP 403 `PERMISSION_DENIED` over REST
-#   exactly as on the CLI. The other ~30 routers do not check the engine yet.
+#   exactly as on the CLI. Every other route is checked too since #655 (see `permissions` below).
 #   The policy comes from the config dir `serve` RESOLVES (its own `--config-dir`, then -- since
 #   0.91.0, #679 -- an explicit root `kbagent --config-dir`, then KBAGENT_CONFIG_DIR, then the
 #   local/global chain) plus the session flags of the invocation. On 0.90.1 the root-level
@@ -479,7 +479,7 @@ kbagent auth register-projects [--stack URL|alias] [--all] [--project-id ID ...]
 #   the allow list. `kbagent --deny-writes serve` does NOT work: `serve` is admin-class and
 #   `--deny-writes` appends `cli:write`, which spans write+destructive+admin, so the CLI callback
 #   blocks the `serve` command itself (exit 6) and no server ever starts. `--deny-destructive`
-#   starts the server but no `/auth/*` operation is destructive, so it affects nothing here.
+#   starts the server and blocks every destructive route (none of them under `/auth/*`).
 #   See docs/web-server.md.
 
 kbagent project create --url URL [--project ALIAS] [--name NAME] [--backend snowflake|bigquery] [--sync-backend-init]
@@ -507,10 +507,10 @@ kbagent project create --url URL [--project ALIAS] [--name NAME] [--backend snow
 #   delivered and may have succeeded (retryable:false, message says not to repeat -- check
 #   `auth status`, whose stored session + claim link is the evidence). `--sync-backend-init`
 #   raises that call's read timeout to 300s, which can outlast an agent's foreground shell.
-kbagent project add --project NAME --url URL --token TOKEN
+kbagent project add --project NAME --url URL [--token-stdin | --token-file PATH [--keep-token-file] | --token-env NAME | --token TOKEN]
 kbagent project list
 kbagent project remove --project NAME
-kbagent project edit --project NAME [--url URL] [--token TOKEN] [--new-alias NEW]
+kbagent project edit --project NAME [--url URL] [--token-stdin | --token-file PATH [--keep-token-file] | --token-env NAME | --token TOKEN] [--new-alias NEW]
 kbagent project status [--project NAME]
 kbagent project refresh --project ALIAS [--dry-run] [--force] [--yes] [--token-description DESC] [--token-expires-in N]
 kbagent project refresh --all [--dry-run] [--force] [--yes] [--token-description DESC] [--token-expires-in N]
@@ -555,7 +555,10 @@ kbagent config set-folder --project NAME --component-id ID --config-id ID --name
 kbagent config row-create --project NAME --component-id ID --config-id ID --name ROW_NAME [--description D] [--configuration JSON|@file|-] [--is-disabled] [--branch ID] [--allow-plaintext-on-encrypt-failure]
 kbagent config row-update --project NAME --component-id ID --config-id ID --row-id ID [--name N] [--description D] [--configuration JSON|@file|-] [--change-description TEXT] [--is-disabled | --is-enabled] [--branch ID] [--allow-plaintext-on-encrypt-failure]
 kbagent config row-delete --project NAME --component-id ID --config-id ID --row-id ID [--branch ID] [--yes]
-kbagent config oauth-url --project NAME --component-id ID --config-id ID [--redirect-url URL]
+kbagent config oauth-url --project NAME --component-id ID --config-id ID [--redirect-url URL] [--no-open]
+# oauth-url: opens the link in the default browser (interactive human mode only; never with
+#   --json, over SSH, in a container or in WSL without wslview); --no-open only prints it.
+#   Version gate in gotchas.md.
 kbagent config state-get --project NAME --component-id ID --config-id ID [--row-id ID] [--branch ID]
 kbagent config state-set --project NAME --component-id ID --config-id ID [--row-id ID] --state JSON|@file|- [--branch ID] [--dry-run] [--yes]
 # state-get/state-set (0.84.2+, #593): read/write a config's runtime state via the dedicated
@@ -625,7 +628,7 @@ kbagent storage table-detail --project NAME --table-id ID [--branch ID]
 #   and `sql_path` (quoted, directly queryable path; null when Storage reports no location) --
 #   see the semantic-layer dataset fqn note (#761); version gate in gotchas.md.
 kbagent storage create-bucket --project NAME --stage STAGE --name NAME [--description D] [--backend B] [--branch ID]
-kbagent storage create-table --project NAME --bucket-id ID --name NAME [--column COL:TYPE[(length)] ...] [--primary-key COL] [--not-null COL ...] [--default NAME=VALUE ...] [--source-table-id ID] [--source-branch-id N] [--time-partitioning-type DAY|HOUR|MONTH|YEAR] [--time-partitioning-field COL] [--time-partitioning-expiration-ms MS] [--range-partitioning-field COL --range-partitioning-start S --range-partitioning-end E --range-partitioning-interval I] [--clustering-field COL ...] [--branch ID] [--if-not-exists]
+kbagent storage create-table --project NAME --bucket-id ID --name NAME [--column COL:TYPE[(length)] ...] [--primary-key COL] [--not-null COL ...] [--default NAME=VALUE ...] [--source-table-id ID] [--source-branch-id N] [--time-partitioning-type DAY|HOUR|MONTH|YEAR] [--time-partitioning-field COL] [--time-partitioning-expiration-ms MS] [--range-partitioning-field COL --range-partitioning-start S --range-partitioning-end E --range-partitioning-interval I] [--clustering-field COL ...] [--branch ID] [--if-not-exists] [--timeout SECONDS]
 # --column XOR --source-table-id (0.66.0+, BigQuery only): --source-table-id copies an existing table's data into the requested partition/clustering layout (schema derived from source) -> swap into place with swap-tables. Partition/clustering flags work in both modes (BigQuery only); time vs range partitioning are mutually exclusive. A non-BigQuery project fails fast (pre-flight backend check).
 kbagent storage upload-table --project NAME --table-id ID --file PATH [--incremental] [--delimiter D] [--enclosure E] [--no-auto-create] [--wait/--no-wait] [--timeout SECONDS] [--branch ID] [--progress]
 # upload-table / file-upload cloud upload (#834): on AWS stacks a file above 64 MiB goes up as an S3
@@ -663,7 +666,16 @@ kbagent storage delete-table --project NAME --table-id ID [--table-id ...] [--fo
 kbagent storage truncate-table --project NAME --table-id ID [--table-id ...] [--dry-run] [--yes] [--branch ID]
 kbagent storage delete-column --project NAME --table-id ID --column COL [--column ...] [--force] [--dry-run] [--yes] [--branch ID]
 kbagent storage delete-bucket --project NAME --bucket-id ID [--bucket-id ...] [--force] [--dry-run] [--yes] [--branch ID]
-kbagent storage swap-tables --project NAME --table-id ID --target-table-id ID --branch ID [--dry-run] [--yes]
+kbagent storage swap-tables --project NAME --table-id ID --target-table-id ID --branch ID [--dry-run] [--yes] [--timeout SECONDS]
+    # --timeout SECONDS on create-table and swap-tables (since 0.99.0, #713): both halves
+    #   of the repartition path move real data yet used to inherit the 60s metadata-job
+    #   budget, so a large BigQuery table reported STORAGE_JOB_TIMEOUT for a job that was
+    #   still running and would succeed. Default is now 300s on both. A local timeout
+    #   NEVER cancels the job -- it keeps running server-side. The error is
+    #   STORAGE_JOB_TIMEOUT, exit 4, retryable=false, details.job_id, and the message
+    #   names `storage job-detail --job-id ID --wait` (create-table also names
+    #   `storage table-detail`). Never re-run: a repeated swap swaps the tables back,
+    #   a repeated --source-table-id create starts a second copy.
 kbagent storage clone-table --project NAME --table-id ID --branch ID [--dry-run]
 kbagent storage snapshot-create --project NAME --table-id ID [--description D] [--branch ID]
 kbagent storage snapshots --project NAME --table-id ID [--limit N] [--branch ID]
@@ -813,6 +825,25 @@ kbagent token refresh --project NAME --token-id ID [--yes]
 #   is persisted. `permissions show` / `kbagent doctor` also generalized: they now flag ANY
 #   persisted pattern matching zero known operations, not only the retired tool:* namespace.
 #   PermissionEngine itself stays lenient at evaluation time -- only `permissions set` is strict.
+# (since 0.99.0, #655) The policy also firewalls the WHOLE `kbagent serve` REST surface: every
+#   route is classified in server/route_permissions.py and checked by one app-level dependency
+#   against the SERVED config dir's policy -> HTTP 403 error_code PERMISSION_DENIED, the same
+#   code the CLI exits on. On 0.98.0 and older only /auth/* (0.90.1+) and /merge-requests/*
+#   (0.94.0+) were checked and every other route executed unchecked. Routes that declare their
+#   own `require_permission(...)` (those two routers) are skipped by the table. An unclassified
+#   route is REFUSED, not exempted (a test keeps the table
+#   and the live app in sync both ways); bootstrap paths (/health/ping, /health/auth-info,
+#   /ui-config, /docs, /redoc, /openapi.json, SPA shell) are never checked. A path param
+#   that collapses CLI leaves is checked like the CLI: POST/PUT/DELETE
+#   /semantic-layer/items/{kind}[/{name}] check the parent key (`semantic-layer.add`) AND
+#   the leaf `semantic-layer.add.<kind>` (route_permissions.LEAF_PATH_PARAMS).
+#   A `--scope organization` semantic-layer write is destructive-class over REST too:
+#   the handlers of scope PUT, models, items/{kind} (per-kind leaf key), import, promote
+#   and build check `<key> --scope organization` (FLAG_ESCALATIONS) for a typed OR an
+#   inherited organization scope, like the CLI.
+#   `GET /permissions/show` (serve, since 0.99.0) reports the EFFECTIVE policy (persisted block
+#   merged with the daemon's --deny-* flags); read-only by design -- no REST route can widen
+#   the policy that constrains it, so `permissions set|reset` stay terminal actions on the host.
 kbagent permissions list [--category read|write|destructive|admin]
 kbagent permissions show
 kbagent permissions set --mode allow|deny [--allow PATTERN ...] [--deny PATTERN ...]
@@ -900,6 +931,17 @@ kbagent merge-request resolve --component-id C --config-id I (--take ours|theirs
 #   its hint-next respects it.
 
 kbagent workspace create --project ALIAS [--name NAME] [--backend TYPE] [--ui] [--read-only/--no-read-only]
+# workspace create (#755): a failed create -- headless or --ui -- moves the keboola.sandboxes
+#   config it created to the trash and says so (--json error.details: sandbox_config_id,
+#   sandbox_config_rolled_back, branch_id, job_id for --ui) -- except when the outcome is
+#   unknown, where the config is kept (sandbox_config_kept_reason: outcome_unknown): a 5xx, a
+#   read/write TIMEOUT or RETRY_EXHAUSTED on the create POST, or any error after the --ui job was
+#   queued other than QUEUE_JOB_FAILED / WORKSPACE_NOT_FOUND; the --ui job is queued on the branch
+#   the config lives in (was: default branch -> Queue 400 on a pinned dev branch). --ui itself
+#   still ends in WORKSPACE_NOT_FOUND on current SaaS stacks: the keboola.sandboxes `create` task
+#   dropped Snowflake/BigQuery provisioning in 2026-03 (the UI uses SQL Editor sessions), so the
+#   green job attaches no Storage workspace. Not a race -- do not retry; use headless. Version
+#   gate for this entry lives in gotchas.md (these `# ` lines parse as ATX headings).
 kbagent workspace list [--project NAME ...] [--orphaned] [--branch ID] [--qs-compatible]
 kbagent workspace detail --project ALIAS --workspace-id ID [--branch ID]
 kbagent workspace delete --project ALIAS --workspace-id ID
@@ -958,10 +1000,17 @@ kbagent data-app create --project ALIAS --name NAME --slug SLUG (--git-repo URL
 #   (1) create --use-managed-git-repo -> (2) `git-credentials-create --type http_token --permissions
 #   readWrite` + `git push` code to the managed repo URL (from `git-repo`) -> (3) `data-app deploy`.
 #   The platform injects the clone credentials at deploy time, so no credential wiring is needed.
-#   deploy pins the LATEST configVersion when a git block is present and omits it for a PURE managed
-#   repo (deploys from managedGitRepoId). Use `data-app runs` to debug a deploy that reverts to
-#   stopped (setup-phase failures produce no container logs).
-kbagent data-app deploy --project NAME --app-id ID [--config-version N] [--wait] [--timeout SECONDS] [--branch ID] [--copy] [--reveal]
+#   deploy pins the LATEST configVersion. For a PURE managed repo (no git block yet), it first
+#   backfills parameters.dataApp.git from the managed repo's URL, then pins the resulting version
+#   (CLI-15) -- omitting configVersion alone does NOT provision the app's workspace;
+#   grant provisioning is gated on that block's presence, not on configVersion. The deploy result
+#   reports it (`git_backfilled`, `git_branch`, `warnings[]`). The branch written is `--git-branch`;
+#   without it, `main` for an app with no runs, and a VALIDATION_ERROR before any write for an app
+#   with runs (branch unknown: pass `--git-branch` with the branch the code is on). It has no effect
+#   on a deploy that does not backfill. Push the managed repo's code to that branch.
+#   Version gate lives in gotchas.md (no `(since vNEXT)` on `# ` lines). Use `data-app runs`
+#   to debug a deploy that reverts to stopped (setup-phase failures produce no container logs).
+kbagent data-app deploy --project NAME --app-id ID [--config-version N] [--wait] [--timeout SECONDS] [--branch ID] [--git-branch BRANCH] [--copy] [--reveal]
 kbagent data-app start --project NAME --app-id ID [--wait] [--timeout SECONDS]
 kbagent data-app stop --project NAME --app-id ID [--wait] [--timeout SECONDS]
 kbagent data-app delete --project NAME --app-id ID [--yes]
@@ -1026,6 +1075,9 @@ kbagent config new --component-id ID [--name NAME] [--project NAME] [--output-di
 #   the scaffold had no ID and always landed in the default branch tree, so the next
 #   `sync push` created a DUPLICATE (34-config incident). With --configuration, the local file
 #   mirrors the pushed encrypted body -- placeholders would overwrite the remote on next push.
+#   The scaffold also records _keboola.base_config_hash (#792 E), the created config as the API
+#   returned it, so `sync diff` compares it 3-way and push never overwrites an edit made in the UI.
+#   Version gate in gotchas.md.
 
 # sync: GitOps -- configs as local files. init/pull/push/diff are filesystem-local (no serve REST surface).
 kbagent sync init --project ALIAS [--directory DIR] [--git-branching] [--adopt-existing] [--with-workspaces]
@@ -1041,6 +1093,13 @@ kbagent sync push --project ALIAS [--all-projects] [--dry-run] [--force] [--allo
 #   under skipped_deletions (+ skipped_deletions_reason), also in --dry-run, whose summary.deleted counts only
 #   what push would delete. A config/row deleted on the remote since the last pull diffs as remote_deleted and
 #   is never re-created (it lands in skipped). Version gate in gotchas.md.
+# sync diff/push/pull and adopted files (#792 E): an untracked _config.yml whose _keboola.config_id
+#   exists on the target has no baseline unless it records _keboola.base_config_hash; without one a
+#   difference is a conflict (push skips it), two files with one id are both conflicts, and pull keeps
+#   such a file with local changes (skipped) -- only --theirs overwrites it. Version gate in gotchas.md.
+# sync push encryption (#792 F): every #-secret is encrypted before the first write, so an
+#   ENCRYPTION_FAILED stops push before anything reaches the remote (the message ends with "Nothing
+#   was pushed.") and a retry creates nothing twice. Version gate in gotchas.md.
 # sync push workspace delete (CLI-25): in a `syncWorkspaces` tree, a `push --force` that deletes a shared SQL workspace also deletes its SQL editor sessions (every user's, push branch) and their backend workspaces, which `config restore` does not bring back; `push --dry-run --force` lists them (warnings[] workspace_sessions), a plain push lists the workspace under skipped_deletions and touches no session. `--force` is destructive-class (FLAG_ESCALATIONS `sync.push --force`), so `--deny-destructive` / a cli:destructive deny blocks it while a plain push stays write-class. Version gate for this entry lives in gotchas.md.
 # Partial failures change the exit code (#745): commands that collect per-item failures
 #   and keep going exit 1 (was 0) when at least one item failed:

{keboola_cli-0.98.0 → keboola_cli-0.99.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: keboola-cli
-Version: 0.98.0
+Version: 0.99.0
 Summary: AI-friendly CLI for managing Keboola projects
 Author-email: Keboola <dev@keboola.com>
 License-Expression: Apache-2.0
@@ -84,6 +84,29 @@ A fresh Windows install has no real Python either: `python` resolves to a Micros
 
 Auto-updates kbagent on every launch; the self-update prefers the prebuilt wheel when available. Run `kbagent changelog` to see what changed. (Since 0.85.0 kbagent updates itself only -- if you also run `keboola-mcp-server` in Claude Desktop / Cursor, refresh it yourself with `uv tool install --upgrade --prerelease=allow keboola-mcp-server`.)
 
+### Installed under the old package name
+
+The package was named `keboola-agent-cli` up to 0.62.0. It is named `keboola-cli` from 0.63.0. Both packages install the `kbagent` executable. uv treats an update to `keboola-cli` as a new tool and does not overwrite the executable that the old tool owns.
+
+To check which name you have, run `uv tool list`. An old install is listed as `keboola-agent-cli`.
+
+- kbagent 0.59.x and older cannot update itself. Every command prints `Auto-update failed; continuing with current version.` and the version does not change. Without the `[server]` extras, the uv error behind it is ``error: Executable already exists: kbagent (use `--force` to overwrite)``. No release can change this, because the update code runs from the old install.
+- kbagent 0.60.0 to 0.62.x updates through a compatibility wheel and stays on the old name.
+- kbagent 0.63.1 and newer installs a second tool, `keboola-cli`, when it updates. The new tool takes over the `kbagent` executable and the old `keboola-agent-cli` entry stays in `uv tool list`.
+
+To move to `keboola-cli`, run these two commands in this order, in a shell where no kbagent is running:
+
+```bash
+uv tool uninstall keboola-agent-cli
+curl -LsSf https://raw.githubusercontent.com/keboola/cli/main/install.sh | sh
+```
+
+On Windows, run the PowerShell install from the Windows section above as the second step. Your configuration is not touched: the configuration folder keeps the name `keboola-agent-cli` on purpose.
+
+If `uv tool list` shows `keboola-cli` next to `keboola-agent-cli`, the update already worked. kbagent runs from `keboola-cli` and the old entry does no harm. Do not remove the old entry on its own: `uv tool uninstall keboola-agent-cli` also deletes the `kbagent` executable that `keboola-cli` uses, and the shell then reports `command not found`. To restore the executable, run `uv tool install --force --reinstall "keboola-cli[server] @ https://github.com/keboola/cli/releases/download/v<version>/keboola_cli-<version>-py3-none-any.whl"` with the latest version number from the [releases page](https://github.com/keboola/cli/releases/latest).
+
+A failed startup update prints the last line of the uv output as `Cause:` (since 0.99.0), then the recovery command.
+
 ## Web UI (optional)
 
 Want a browser dashboard? One command:
@@ -155,7 +178,7 @@ Then either let the `kbagent` skill auto-trigger from natural prompts, or delega
 kbagent init --from-global --read-only
 ```
 
-Three protection layers (kbagent policy + filesystem chmod + Claude Code deny rules) prevent the agent from writing, deleting, or bypassing restrictions. See [Permissions Guide](docs/guide.md#permissions) for details.
+Three protection layers (kbagent policy + filesystem chmod + Claude Code deny rules) stop the agent from writing, deleting, or changing the restrictions by mistake. They are guard rails, not a sandbox: a process that runs as the same OS user can get around them. For a hard lockout, run the agent as a different OS user ([ADR 0002](docs/adr/0002-sec-09-config-privilege-separation.md)). See [Permissions Guide](docs/guide.md#permissions) for details.
 
 ## Use as a library
 
@@ -182,9 +205,9 @@ with Client(url=os.environ["KBC_URL"], token=os.environ["KBC_TOKEN"]) as kbc:
 ![30-second demo](docs/assets/demo-readme-main.gif)
 
 ```bash
-# Connect a project (Storage API token from Keboola UI)
+# Connect a project (Storage API token from Keboola UI, typed at a hidden prompt)
 kbagent project add --project prod \
-  --url https://connection.keboola.com --token YOUR_TOKEN
+  --url https://connection.keboola.com --token-stdin
 
 # Find anything (table / config / flow / data app) across ALL projects in one call
 kbagent search "customer_id"
@@ -233,9 +256,12 @@ Four ways to register projects, depending on what you have. If you are a human
 at a terminal with a browser, start with **browser login** (last one below);
 the token-based options are the ones to use for CI and anything unattended.
 
-**Single project** — you have a Storage API token from the UI:
+**Single project** — you have a Storage API token from the UI. `--token-stdin` shows a hidden prompt on a terminal and reads a pipe otherwise, so the token stays out of your shell history:
 ```bash
-kbagent project add --project prod --url https://connection.keboola.com --token YOUR_TOKEN
+kbagent project add --project prod --url https://connection.keboola.com --token-stdin
+
+# CI / non-interactive: pipe the token in
+printf '%s' "$KBC_TOKEN" | kbagent project add --project prod --url https://connection.keboola.com --token-stdin
 ```
 
 **Many projects by ID** — you have a Manage API or Personal Access Token + the project IDs:

{keboola_cli-0.98.0 → keboola_cli-0.99.0}/README.md

@@ -56,6 +56,29 @@ A fresh Windows install has no real Python either: `python` resolves to a Micros
 
 Auto-updates kbagent on every launch; the self-update prefers the prebuilt wheel when available. Run `kbagent changelog` to see what changed. (Since 0.85.0 kbagent updates itself only -- if you also run `keboola-mcp-server` in Claude Desktop / Cursor, refresh it yourself with `uv tool install --upgrade --prerelease=allow keboola-mcp-server`.)
 
+### Installed under the old package name
+
+The package was named `keboola-agent-cli` up to 0.62.0. It is named `keboola-cli` from 0.63.0. Both packages install the `kbagent` executable. uv treats an update to `keboola-cli` as a new tool and does not overwrite the executable that the old tool owns.
+
+To check which name you have, run `uv tool list`. An old install is listed as `keboola-agent-cli`.
+
+- kbagent 0.59.x and older cannot update itself. Every command prints `Auto-update failed; continuing with current version.` and the version does not change. Without the `[server]` extras, the uv error behind it is ``error: Executable already exists: kbagent (use `--force` to overwrite)``. No release can change this, because the update code runs from the old install.
+- kbagent 0.60.0 to 0.62.x updates through a compatibility wheel and stays on the old name.
+- kbagent 0.63.1 and newer installs a second tool, `keboola-cli`, when it updates. The new tool takes over the `kbagent` executable and the old `keboola-agent-cli` entry stays in `uv tool list`.
+
+To move to `keboola-cli`, run these two commands in this order, in a shell where no kbagent is running:
+
+```bash
+uv tool uninstall keboola-agent-cli
+curl -LsSf https://raw.githubusercontent.com/keboola/cli/main/install.sh | sh
+```
+
+On Windows, run the PowerShell install from the Windows section above as the second step. Your configuration is not touched: the configuration folder keeps the name `keboola-agent-cli` on purpose.
+
+If `uv tool list` shows `keboola-cli` next to `keboola-agent-cli`, the update already worked. kbagent runs from `keboola-cli` and the old entry does no harm. Do not remove the old entry on its own: `uv tool uninstall keboola-agent-cli` also deletes the `kbagent` executable that `keboola-cli` uses, and the shell then reports `command not found`. To restore the executable, run `uv tool install --force --reinstall "keboola-cli[server] @ https://github.com/keboola/cli/releases/download/v<version>/keboola_cli-<version>-py3-none-any.whl"` with the latest version number from the [releases page](https://github.com/keboola/cli/releases/latest).
+
+A failed startup update prints the last line of the uv output as `Cause:` (since 0.99.0), then the recovery command.
+
 ## Web UI (optional)
 
 Want a browser dashboard? One command:
@@ -127,7 +150,7 @@ Then either let the `kbagent` skill auto-trigger from natural prompts, or delega
 kbagent init --from-global --read-only
 ```
 
-Three protection layers (kbagent policy + filesystem chmod + Claude Code deny rules) prevent the agent from writing, deleting, or bypassing restrictions. See [Permissions Guide](docs/guide.md#permissions) for details.
+Three protection layers (kbagent policy + filesystem chmod + Claude Code deny rules) stop the agent from writing, deleting, or changing the restrictions by mistake. They are guard rails, not a sandbox: a process that runs as the same OS user can get around them. For a hard lockout, run the agent as a different OS user ([ADR 0002](docs/adr/0002-sec-09-config-privilege-separation.md)). See [Permissions Guide](docs/guide.md#permissions) for details.
 
 ## Use as a library
 
@@ -154,9 +177,9 @@ with Client(url=os.environ["KBC_URL"], token=os.environ["KBC_TOKEN"]) as kbc:
 ![30-second demo](docs/assets/demo-readme-main.gif)
 
 ```bash
-# Connect a project (Storage API token from Keboola UI)
+# Connect a project (Storage API token from Keboola UI, typed at a hidden prompt)
 kbagent project add --project prod \
-  --url https://connection.keboola.com --token YOUR_TOKEN
+  --url https://connection.keboola.com --token-stdin
 
 # Find anything (table / config / flow / data app) across ALL projects in one call
 kbagent search "customer_id"
@@ -205,9 +228,12 @@ Four ways to register projects, depending on what you have. If you are a human
 at a terminal with a browser, start with **browser login** (last one below);
 the token-based options are the ones to use for CI and anything unattended.
 
-**Single project** — you have a Storage API token from the UI:
+**Single project** — you have a Storage API token from the UI. `--token-stdin` shows a hidden prompt on a terminal and reads a pipe otherwise, so the token stays out of your shell history:
 ```bash
-kbagent project add --project prod --url https://connection.keboola.com --token YOUR_TOKEN
+kbagent project add --project prod --url https://connection.keboola.com --token-stdin
+
+# CI / non-interactive: pipe the token in
+printf '%s' "$KBC_TOKEN" | kbagent project add --project prod --url https://connection.keboola.com --token-stdin
 ```
 
 **Many projects by ID** — you have a Manage API or Personal Access Token + the project IDs:

{keboola_cli-0.98.0 → keboola_cli-0.99.0}/formal/sync/README.md

@@ -81,8 +81,8 @@ explores traces of up to 5 actions. BFS returns the shortest counterexample.
 | I5 pull keeps local work | violated: a remote delete plus a local edit ends with plain or `--force` pull deleting the edited directory silently |
 | I6 push then diff is clean | violated on `--branch` promote (finding D, since fixed in the engine; the TLA model is unchanged). Holds on production only (30,334 states) |
 | I8 manifest matches disk | violated: the stale sweep, and a promote write-back that records a `devt/` entry for a file in `main/` |
-| I9 an aborted push is atomic | violated (strong reading): the changes before the failing one reached the API and the manifest was never saved |
-| I11 no lost remote update | violated: an adopted file with a config id is diffed 2-way, so push reverts a UI edit |
+| I9 an aborted push is atomic | violated (strong reading): the changes before the failing one reached the API and the manifest was never saved. Fixed in the code (F: push encrypts before its first write); the model is unchanged |
+| I11 no lost remote update | violated: an adopted file with a config id is diffed 2-way, so push reverts a UI edit. Fixed in the code (E); the model is unchanged |
 | I11b no silent resurrect | violated: a remote delete followed by any push re-creates the config, even with no local edit (S2). Fixed in the code (H); the model is unchanged |
 | I12 a pull resolves REMOTE MODIFIED | violated: after a cosmetic edit, plain pull skips the file forever and `--force` raises a conflict (S3) |
 
@@ -103,8 +103,8 @@ the regression test for each in `tests/test_sync_formal_counterexamples.py`.
 | B | Pull compares only `_config.yml`: local edits in `transform.sql`/`code.py`/`_description.md` are silently overwritten when the remote changed, no SYNC_CONFLICT | Lean F6 | HIGH -- **FIXED** (pull's local-modification check now covers every `pull_extra_hashes` companion file) | `test_b_pull_never_overwrites_local_sql_edit` (unmarked regression guard) + `tests/test_sync_pull_companion_files.py` |
 | C | Remote delete + local edit: pull (plain/`--force`) deletes the locally-edited directory with no conflict | Lean F7, TLA I5 | HIGH -- **fixed** (#792 A/C PR) | `test_c_pull_never_deletes_locally_edited_dir_on_remote_delete` |
 | D | `sync push --branch dev` (promote) creates another dev copy of a prod-only config on every push. **Fixed** (fix/792-dev-promote-duplicates): on the promote path the target-branch entry shadows the production entry for the same `main/` dir (`sync/branch_scope.py::_promoted_paths`) | TLA I6/I1 | HIGH | `test_d_promote_push_is_idempotent`, `test_d_promote_push_diff_is_clean_and_edits_update_the_dev_copy` (regression guards) |
-| E | An untracked file carrying a config id (`config new --push --output-dir` scaffold / adopted orphan) is diffed 2-way: push overwrites a UI edit made after the scaffold was written | TLA I11 | MED | `test_e_adopted_scaffold_push_does_not_overwrite_remote_edit` |
-| F | A push aborted by `ENCRYPTION_FAILED` leaves the manifest unsaved; the retry duplicates the change(s) the aborted push already applied | TLA I1b (model trace only; replayed live for this pilot) | MED | `test_f_aborted_push_does_not_duplicate_already_created_config` |
+| E | An untracked file carrying a config id (`config new --push --output-dir` scaffold / adopted orphan) is diffed 2-way: push overwrites a UI edit made after the scaffold was written | TLA I11, Lean F4/F5 | MED -- **fixed** (without a baseline a difference is a `conflict`; the scaffold records `_keboola.base_config_hash`; pull keeps such a file) | `test_e_adopted_scaffold_push_does_not_overwrite_remote_edit` + `tests/test_sync_adopted_files.py` |
+| F | A push aborted by `ENCRYPTION_FAILED` leaves the manifest unsaved; the retry duplicates the change(s) the aborted push already applied | TLA I1b (model trace only; replayed live for this pilot) | MED -- **fixed** (push encrypts every secret before its first write, so the abort writes nothing) | `test_f_aborted_push_does_not_duplicate_already_created_config` + `tests/test_sync_push_encrypt_first.py` |
 | G | `sync push` deletes remote configs with no `--force`; the CLI help text says `--force` gates deletion (soft delete to trash since 0.89.0, restorable) | Spec S1, Lean F1, TLA I2b | MED -- **fixed** (push deletes only with `--force`) | `test_g_push_without_force_does_not_delete_remote_config` |
 | H | A config deleted remotely by another actor is silently re-created by the next push, no warning | Spec S2, Lean F2, TLA I11b | MED -- **fixed** (diff reports `remote_deleted`, push skips it) | `test_h_push_does_not_silently_resurrect_deleted_config` |
 | I | Moving a config's directory by hand (`mv`/`git mv`) is seen as remote DELETE + CREATE under a new id | Lean F3 | LOW-MED | `test_i_moving_config_dir_is_not_delete_plus_create` |
@@ -120,11 +120,11 @@ and is deleted only by `--theirs`. That is what the I2 (sweep half), I5 and I8
 TLC/Lean rerun still reports them until the model's `Pull` is updated to match.
 Their tests are ordinary regression guards now.
 
-E, F and I reproduce on current code and are `xfail(strict=True)` (D, G and H
+I reproduces on current code and is `xfail(strict=True)` (D, E, F, G and H
 are fixed) -- flipping to a hard failure the moment a fix lands is the point:
-delete the `xfail` marker to adopt the fix. F's test now reaches the aborted
+delete the `xfail` marker to adopt the fix. F's test reaches the aborted
 create through a promote push, because push no longer re-creates the
-remote-deleted config its first version used. J reproduces and
-is `xfail`. K is deliberate, documented behavior, so it is an ordinary
+remote-deleted config its first version used; since the F fix the aborted
+push creates nothing. J reproduces and is `xfail`. K is deliberate, documented behavior, so it is an ordinary
 (unmarked) regression guard instead. B is fixed: its marker was removed
 and the test is now an ordinary regression guard.

{keboola_cli-0.98.0 → keboola_cli-0.99.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "keboola-cli"
-version = "0.98.0"
+version = "0.99.0"
 description = "AI-friendly CLI for managing Keboola projects"
 readme = "README.md"
 requires-python = ">=3.12"

{keboola_cli-0.98.0 → keboola_cli-0.99.0}/scripts/file_size_baseline.json

@@ -4,7 +4,7 @@
     "commands/config.py": 2007,
     "commands/lineage.py": 1271,
     "commands/storage.py": 2221,
-    "services/data_app_service.py": 1633,
+    "services/data_app_service.py": 1600,
     "services/storage_service.py": 1684,
     "services/sync_service.py": 1655
   }

{keboola_cli-0.98.0 → keboola_cli-0.99.0}/src/keboola_agent_cli/auth/auth_client.py

@@ -792,7 +792,7 @@ class AuthClient(BaseHttpClient):
                     f"project that already exists: create one at {self._base_url} in a "
                     f"browser, then connect it with `kbagent auth login --stack "
                     f"{self._base_url}` or `kbagent project add --project <alias> --url "
-                    f"{self._base_url} --token <token>`."
+                    f"{self._base_url} --token-stdin`."
                 ),
                 status_code=404,
                 error_code=ErrorCode.AUTH_NOT_SUPPORTED_ON_STACK,
@@ -969,7 +969,7 @@ class AuthClient(BaseHttpClient):
                 message=(
                     f"Browser login is not enabled on this Keboola stack yet "
                     f"({self._base_url}). Use a static Storage token instead: "
-                    "kbagent project add --project <alias> --url <stack> --token <token>."
+                    "kbagent project add --project <alias> --url <stack> --token-stdin."
                 ),
                 status_code=404,
                 error_code=ErrorCode.AUTH_NOT_SUPPORTED_ON_STACK,
@@ -1042,7 +1042,7 @@ class AuthClient(BaseHttpClient):
                 message=(
                     f"Programmatic auth is not enabled on this Keboola stack yet "
                     f"({self._base_url}). Use a static Storage token instead: "
-                    "kbagent project add --project <alias> --url <stack> --token <token>."
+                    "kbagent project add --project <alias> --url <stack> --token-stdin."
                 ),
                 status_code=404,
                 error_code=ErrorCode.AUTH_NOT_SUPPORTED_ON_STACK,

{keboola_cli-0.98.0 → keboola_cli-0.99.0}/src/keboola_agent_cli/auth/environment.py

@@ -28,6 +28,10 @@ from dataclasses import dataclass
 # wslview from stalling the login flow.
 _WSLVIEW_PROBE_TIMEOUT_SECONDS = 2.0
 
+# Timeout for handing a URL to `wslview`: it returns as soon as the Windows side
+# has accepted the request, so anything longer means the shim is wedged.
+_WSLVIEW_OPEN_TIMEOUT_SECONDS = 10.0
+
 
 @dataclass(frozen=True)
 class BrowserEnvironment:
@@ -168,6 +172,24 @@ def detect_browser_environment() -> BrowserEnvironment:
     return BrowserEnvironment(loopback_browser_usable=True, reason="", opener=opener)
 
 
+def _open_via_wslview(url: str) -> None:
+    """Thread target for `open_browser` under WSL: hand ``url`` to `wslview`.
+
+    `wslview` passes the URL to the Windows-side default browser. Output is
+    captured, never logged, and every error is swallowed -- the URL must not
+    reach stderr (see `_open_silently`).
+    """
+    try:
+        subprocess.run(
+            ["wslview", url],
+            capture_output=True,
+            timeout=_WSLVIEW_OPEN_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except Exception:
+        return
+
+
 def open_browser(url: str, *, wait_seconds: float = 0.0) -> bool:
     """Best-effort `webbrowser.open` on a daemon thread.
 
@@ -182,13 +204,24 @@ def open_browser(url: str, *, wait_seconds: float = 0.0) -> bool:
     right after the call (``data-app password --open``) passes it, because a
     daemon thread dies with the process -- possibly before the opener starts.
     The login flow keeps polling afterwards, so it leaves the default 0.
-    """
-    try:
-        webbrowser.get()
-    except webbrowser.Error:
-        return False
 
-    thread = threading.Thread(target=_open_silently, args=(url,), daemon=True)
+    Under WSL the URL goes to `wslview` first: `webbrowser` keys its Windows
+    handling off ``sys.platform == "win32"``, which is ``linux`` inside WSL, so
+    it would either find no handler at all or open a browser in the Linux
+    session -- a separate profile that shares none of the logins the URL needs.
+    It runs on the same daemon thread and honors ``wait_seconds`` the same way;
+    a working `wslview` (probed synchronously) counts as the available handler.
+    """
+    if _env_flag_set("WSL_INTEROP") and _wslview_is_working():
+        target = _open_via_wslview
+    else:
+        try:
+            webbrowser.get()
+        except webbrowser.Error:
+            return False
+        target = _open_silently
+
+    thread = threading.Thread(target=target, args=(url,), daemon=True)
     thread.start()
     if wait_seconds > 0:
         thread.join(timeout=wait_seconds)

{keboola_cli-0.98.0 → keboola_cli-0.99.0}/src/keboola_agent_cli/auto_update.py

@@ -14,7 +14,9 @@ import logging
 import os
 import shutil
 import sys
+import tempfile
 import time
+from dataclasses import dataclass
 from importlib.metadata import distribution
 from pathlib import Path
 
@@ -39,6 +41,7 @@ from .services.version_service import (
     get_update_timeout,
     prepare_kbagent_update_plan,
     resolve_kbagent_wheel_url,
+    summarize_install_failure,
 )
 from .update_runner import (
     DeferredUpdateReport,
@@ -68,6 +71,14 @@ class UpdateOutcome(enum.Enum):
     FAILED = "failed"
 
 
+@dataclass(frozen=True)
+class UpdateResult:
+    """An :class:`UpdateOutcome` plus what the installer printed when it failed (issue #771)."""
+
+    outcome: UpdateOutcome
+    output: str = ""
+
+
 # Process-level sentinel for the auto-update flow.
 #
 # Bug D fix from issue #263: ``kbagent repl`` re-enters the entire CLI
@@ -135,7 +146,22 @@ def _write_cache(latest_version: str | None) -> None:
             "last_check": time.time(),
             "latest_version": latest_version,
         }
-        cache_path.write_text(json.dumps(payload), encoding="utf-8")
+        # Atomic replace (issue #271 sec-12): write a temp file next to the
+        # cache, then rename it over the cache in one step. A reader never sees
+        # a partial file, and a failed write keeps the previous cache. Each
+        # writer has its own temp file, so parallel kbagent starts need no
+        # lock: the last rename wins, and each value is a complete check result.
+        fd, tmp_name = tempfile.mkstemp(
+            dir=cache_path.parent, prefix=f".{cache_path.name}.", suffix=".tmp"
+        )
+        tmp_path = Path(tmp_name)
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as tmp_file:
+                tmp_file.write(json.dumps(payload))
+            os.replace(tmp_path, cache_path)
+        except OSError:
+            tmp_path.unlink(missing_ok=True)
+            raise
     except OSError:
         pass  # Non-critical; next run will re-fetch
 
@@ -273,9 +299,7 @@ def _should_skip() -> bool:
     return _should_skip_kbagent_stage() or _should_skip_all()
 
 
-def _perform_update(
-    latest_version: str, *, command: tuple[str, ...] | None = None
-) -> UpdateOutcome:
+def _perform_update(latest_version: str, *, command: tuple[str, ...] | None = None) -> UpdateResult:
     """Download and install the latest version.
 
     Delegates to :func:`build_kbagent_upgrade_command` so this path stays
@@ -290,10 +314,10 @@ def _perform_update(
         latest_version: The version being updated to (for logging).
 
     Returns:
-        :class:`UpdateOutcome`: ``SUCCESS`` on a clean install, ``TIMEOUT`` when
-        the install outran :func:`get_update_timeout` -- it is still running and
-        will finish on its own, so the next launch picks it up -- and ``FAILED``
-        otherwise.
+        :class:`UpdateResult` whose ``outcome`` is ``SUCCESS`` on a clean install,
+        ``TIMEOUT`` when the install outran :func:`get_update_timeout` -- it is
+        still running and will finish on its own, so the next launch picks it up --
+        and ``FAILED`` otherwise, with the installer's output in ``output``.
     """
     # ``command`` is supplied by the startup planner. Keep the fallback only
     # for direct legacy callers; it must never be used after another stage has
@@ -304,17 +328,32 @@ def _perform_update(
     else:
         cmd = list(command)
     if cmd is None:
-        return UpdateOutcome.FAILED
+        return UpdateResult(UpdateOutcome.FAILED)
 
     # Deliberately does NOT kill the installer when the deadline passes -- see
     # ``update_runner.run_install``. A terminated uv leaves the same
     # half-removed venv a Windows file lock does (issue #528).
     run = run_install(tuple(cmd), timeout=get_update_timeout())
     if run.status is InstallStatus.SUCCEEDED:
-        return UpdateOutcome.SUCCESS
+        return UpdateResult(UpdateOutcome.SUCCESS)
     if run.status is InstallStatus.STILL_RUNNING:
-        return UpdateOutcome.TIMEOUT
-    return UpdateOutcome.FAILED
+        return UpdateResult(UpdateOutcome.TIMEOUT)
+    return UpdateResult(UpdateOutcome.FAILED, run.output)
+
+
+def _format_update_failure(output: str, recovery_command: str | None) -> str:
+    """Render the startup banner for a failed install (issue #771).
+
+    Names the line the installer ended with, so the user can tell a network
+    error from a permanent one.
+    """
+    lines = ["Auto-update failed; continuing with current version."]
+    cause = summarize_install_failure(output)
+    if cause:
+        lines.append(f"Cause: {cause}")
+    if recovery_command:
+        lines.append(f"Recover with: {recovery_command}")
+    return "\n".join(lines) + "\n"
 
 
 def _re_exec() -> None:
@@ -594,9 +633,10 @@ def maybe_auto_update() -> None:
             return
 
         sys.stderr.write(f"Updating kbagent v{__version__} -> v{kbagent_plan.latest_version}...\n")
-        outcome = _perform_update(
+        result = _perform_update(
             kbagent_plan.latest_version or __version__, command=kbagent_plan.command
         )
+        outcome = result.outcome
         if outcome is UpdateOutcome.SUCCESS:
             sys.stderr.write(f"Updated to v{kbagent_plan.latest_version}. Re-launching...\n")
             os.environ[ENV_UPDATED_FROM] = __version__
@@ -611,10 +651,7 @@ def maybe_auto_update() -> None:
                 "background and applies on the next launch.\n"
             )
         else:
-            sys.stderr.write(
-                "Auto-update failed; continuing with current version. Recover with: "
-                f"{kbagent_plan.recovery_command}\n"
-            )
+            sys.stderr.write(_format_update_failure(result.output, kbagent_plan.recovery_command))
     except Exception:
         # Blanket catch: auto-update must NEVER crash the CLI.
         logger.debug("Auto-update check failed", exc_info=True)