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

{keboola_cli-0.97.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,16 +628,54 @@ 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] [--branch ID]
-kbagent storage download-table --project NAME --table-id ID [--output FILE] [--columns COL ...] [--limit N] [--where-column COL --where-value VAL ... [--where-operator eq|neq]] [--changed-since WHEN] [--changed-until WHEN] [--branch ID]
+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
+#   MULTIPART upload -- 64 MiB parts (auto-scaled so the file fits in 10,000 parts), 4 in parallel,
+#   per-part retry on 429/5xx/transport errors, peak memory ~4 x part size. Before, the whole file was
+#   read into RAM and sent as one PutObject (hard 5 GiB ceiling). Also covers the SDK
+#   Client.upload_table. Azure/GCP stacks unchanged (they already stream; chunked upload there is a
+#   follow-up in #834). Limits: S3 federation credentials last 12 h (200 GB needs ~5 MB/s sustained);
+#   the source file must not change during the upload (size/mtime checked); no resume across runs; an
+#   aborted multipart upload may leave orphaned parts (the token cannot abort). A .csv.gz is uploaded
+#   byte-for-byte and imported by Storage; auto-create reads its header through gzip. Human mode shows
+#   a progress bar on stderr. `serve`'s upload route streams the body to a temp file (needs temp disk
+#   of the file size) instead of holding it in memory.
+# upload-table / load-file async import (#834): --wait (default) waits --timeout SECONDS (default 600)
+#   for the Storage import job; --no-wait still waits for the cloud upload, then enqueues the import and
+#   returns file_id / job_id / job_status (imported_rows null while pending; keys are additive). A wait
+#   timeout is STORAGE_JOB_TIMEOUT, exit 4, retryable=false: the import KEEPS RUNNING server-side, the
+#   error names job_id + file_id and `storage job-detail --job-id ID --wait`. Never re-run the upload
+#   while that job is waiting/processing -- an incremental re-run duplicates rows. An enqueue failure
+#   after the upload carries file_id -> `storage load-file --file-id` instead of re-uploading.
+#   Workflow: plugins/kbagent/skills/kbagent/references/large-upload-workflow.md. Version gate for this
+#   entry lives in gotchas.md.
+kbagent storage download-table --project NAME --table-id ID [--output FILE] [--columns COL ...] [--limit N] [--where-column COL --where-value VAL ... [--where-operator eq|neq]] [--changed-since WHEN] [--changed-until WHEN] [--branch ID] [--progress]
+# --progress on upload-table / file-upload / download-table / file-download / unload-table (with
+#   --download): ALWAYS report transfer progress on stderr -- also with --json and with no terminal.
+#   A terminal gets a Rich bar (percent, transferred/total, speed, elapsed, ETA); otherwise one plain line
+#   every 10 s plus a final line, e.g. `upload big.csv: 42.0% 4.20/10.00 GiB, 67.30 MiB/s, elapsed
+#   0:01:03, ETA 0:01:27` (last line: `avg` speed + `done`/`failed`). stdout (the JSON envelope) is
+#   untouched. Speed/ETA use a trailing 30 s window; downloads count network (compressed) bytes and start
+#   the clock when the download starts, not during the export job; a sliced download with no sizes in
+#   its manifest shows bytes + speed only. Without the flag nothing changes: a transient bar only in
+#   human mode on a terminal. Terminal-only: no serve / SDK surface. Version gate in gotchas.md.
 kbagent storage add-column --project NAME --table-id ID --column COL:TYPE[(length)] [--not-null] [--default VALUE] [--branch ID]
 kbagent storage delete-table --project NAME --table-id ID [--table-id ...] [--force] [--dry-run] [--yes] [--branch ID]
 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]
@@ -675,13 +716,19 @@ kbagent storage describe-migrate --project ALIAS [--table-id ID ...] [--bucket-i
 #   application are still accumulated into errors[] (exit 1) -- shape is a usage error, an API
 #   refusal is not.
 kbagent storage files --project NAME [--tag TAG ...] [--limit N] [--offset N] [--query Q] [--branch ID]
-kbagent storage file-upload --project NAME --file PATH [--name NAME] [--tag TAG ...] [--permanent] [--branch ID]
-kbagent storage file-download --project NAME [--file-id ID | --tag TAG ...] [--output FILE]
+kbagent storage file-upload --project NAME --file PATH [--name NAME] [--tag TAG ...] [--permanent] [--branch ID] [--progress]
+kbagent storage file-download --project NAME [--file-id ID | --tag TAG ...] [--output FILE] [--progress]
 kbagent storage file-detail --project NAME --file-id ID
 kbagent storage file-delete --project NAME --file-id ID [--file-id ...] [--dry-run] [--yes]
 kbagent storage file-tag --project NAME --file-id ID [--add TAG ...] [--remove TAG ...]
-kbagent storage load-file --project NAME --file-id ID --table-id ID [--incremental] [--delimiter D] [--enclosure E] [--branch ID]
-kbagent storage unload-table --project NAME --table-id ID [--columns COL ...] [--limit N] [--tag TAG ...] [--download] [--output FILE|DIR] [--file-type csv|parquet] [--branch ID]
+kbagent storage load-file --project NAME --file-id ID --table-id ID [--incremental] [--delimiter D] [--enclosure E] [--wait/--no-wait] [--timeout SECONDS] [--branch ID]
+kbagent storage job-detail --project NAME --job-id ID [--wait] [--timeout SECONDS]
+# storage job-detail (#834): read-class; shows a Storage API job (status, operation_name, table_id,
+#   file_id, times, imported_rows, warnings, results, error). Exit 0 success/waiting/processing, exit 1
+#   STORAGE_JOB_FAILED when the job ended in error (details still returned), exit 4 on --wait timeout.
+#   Job ids are project-scoped, independent of the active branch (no --branch). Serve:
+#   GET /storage/jobs/{project}/{job_id}?wait=&timeout=. Version gate for this entry lives in gotchas.md.
+kbagent storage unload-table --project NAME --table-id ID [--columns COL ...] [--limit N] [--tag TAG ...] [--download] [--output FILE|DIR] [--file-type csv|parquet] [--branch ID] [--progress]
 
 # stream: Data Streams (OpenTelemetry/OTLP). Storage token from config (no manage token).
 # Control plane = stream.<region> (derived from connection.<region>); the OTLP ingest URL
@@ -778,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 ...]
@@ -865,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
@@ -923,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]
@@ -991,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]
@@ -1006,7 +1093,34 @@ 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:
+#   `sync push`, `sync push/pull/diff --all-projects`, `sync clone` (also `bucket_errors`),
+#   `org setup`, `project refresh`, `project invite --from-csv`, `workspace gc`,
+#   `semantic-layer import/promote/build/edit metric`, `storage describe-batch --json`,
+#   `flow schedule-remove` (new `errors[]` key, always present, empty when nothing
+#   failed; a partial failure fills it and exits 1; when every schedule delete
+#   fails it still raises `SCHEDULE_DELETE_FAILED`). Only `sync push`, `sync clone`,
+#   `storage describe-batch`, `storage describe-migrate` and `flow schedule-remove` print
+#   a `Failed:` headline instead of a green `Success:`; the others list the failed items
+#   in a table or in summary lines, and the `--all-projects` variants state the count in
+#   their summary line. `sync push --all-projects` counts a project
+#   whose push returned `errors[]` in `summary.failed`. The --json payload is emitted
+#   BEFORE the exit; the items that succeeded stay written. A `--dry-run` of these
+#   exits 1 when it reports a failed item, like the real run. `sync diff --all-projects`
+#   exits 1 when a project failed. Other read-only fan-outs (`billing credits`, `job list`,
+#   `schedule list`, ...) still exit 0. The helper is `item_failure_exit_code()` in
+#   commands/_helpers.py (returns the code, the caller raises). Version gate for this
+#   entry lives in gotchas.md -- the placeholder cannot be written on these `# ` comment
+#   lines (check_version_gates.py parses them as ATX markdown headings).
 # sync push (since 0.91.0, #686): the manifest baseline `pull_config_hash` is stamped from the API
 #   response (or a read-back), never from disk -- push-deployed multi-statement SQL transformations
 #   (and anything disabled in the UI whose local YAML lacks `is_disabled`) no longer show permanent
@@ -1077,7 +1191,7 @@ kbagent semantic-layer add dataset --project P [--model M] --name N --table-id T
 #   --overwrite. Version gate lives in gotchas.md (no `(since vNEXT)` on `# ` lines).
 kbagent semantic-layer add relationship --project P [--model M] --name N --from TABLE_ID --to TABLE_ID --on EXPR [--type left|inner]
 kbagent semantic-layer add constraint --project P [--model M] --name N --constraint-type inequality|equality|range|composition|exclusion|temporal|conditional --rule "EXPR" --metrics M1,M2 [--severity error|warning|info]
-kbagent semantic-layer add glossary --project P [--model M] --term TERM [--definition D]
+kbagent semantic-layer add glossary --project P [--model M] --term TERM --definition D
 kbagent semantic-layer edit metric --project P [--model M] --name N [--new-name N2] [--new-sql SQL] [--new-dataset TABLE_ID] [--new-description D] [--yes]
 kbagent semantic-layer edit dataset --project P [--model M] --name N [--new-name N2] [--new-description D] [--new-grain G]
 kbagent semantic-layer edit constraint --project P [--model M] --name N [--new-name N2] [--new-rule "EXPR"] [--new-constraint-type T] [--new-severity error|warning|info] [--new-metrics M1,M2]
@@ -1088,8 +1202,8 @@ kbagent semantic-layer remove dataset --project P [--model M] --name N [--yes]
 kbagent semantic-layer remove constraint --project P [--model M] --name N [--yes]
 kbagent semantic-layer remove relationship --project P [--model M] --name N [--yes]
 kbagent semantic-layer remove glossary --project P [--model M] --term TERM [--yes]
-kbagent semantic-layer import --project P --file PATH [--model M] [--types T,T,...] [--dry-run] [--yes] [--overwrite]
-kbagent semantic-layer promote --from-project A --to-project B [--from-model M] [--to-model M] [--types T,T,...] [--dry-run] [--yes]
+kbagent semantic-layer import --project P --file PATH [--model M] [--types T,T,...] [--dry-run] [--yes] [--overwrite] [--scope project|organization|targeted] [--target-project ALIAS|ID ...]
+kbagent semantic-layer promote --from-project A --to-project B [--from-model M] [--to-model M] [--types T,T,...] [--dry-run] [--yes] [--scope project|organization|targeted] [--target-project ALIAS|ID ...]
 kbagent semantic-layer build --project P [--model M] --tables T,T,... [--name N] [--dry-run] [--keep-on-failure] [--output PATH]
 kbagent semantic-layer token --encrypt --project P --component-id C
 # scope (PSGO-140, new): visibility scope for a semantic-layer item -- "project"
@@ -1098,7 +1212,15 @@ kbagent semantic-layer token --encrypt --project P --component-id C
 #   create` and every `add <kind>` above. --scope omitted: `model create` makes a "project"
 #   item, `add <kind>` INHERITS its model's scope (an org-level model gets org-level children;
 #   a targeted model, its target projects); an inherited organization scope is permission-gated
-#   like a typed one, and a non-org-admin gets a 403 on it (pass --scope project). --target-project takes a registered alias OR a
+#   like a typed one, and a non-org-admin gets a 403 on it (pass --scope project). `import`,
+#   `promote` and `build --model` create their NEW items at the target model's scope the same way
+#   (same gate: FLAG_ESCALATIONS `semantic-layer.import|promote|build --scope organization`);
+#   `import` / `promote --scope` (+ --target-project) override it, e.g. `--scope project` for a
+#   non-org-admin under an org-level model; items they overwrite keep their own scope. Item names are unique per object type across ALL
+#   models of a project (ALREADY_EXISTS says "in this project"), so a model cannot be copied into
+#   a second model of the same project under the same item names. An item stored at schema version
+#   1.0.0 (created before 0.97.0) cannot be elevated: the error names the stored version and the
+#   fix (export, delete, create again, import). --target-project takes a registered alias OR a
 #   numeric project ID (repeatable or comma-separated; an alias must be on the owner's stack);
 #   without --scope targeted it exits 2. With --scope targeted and no --target-project: a real
 #   terminal launches an interactive picker over the other projects on the stack; --json fails

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: keboola-cli
-Version: 0.97.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.97.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.97.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.97.0 → keboola_cli-0.99.0}/pyproject.toml

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

{keboola_cli-0.97.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.97.0 → keboola_cli-0.99.0}/src/keboola_agent_cli/__init__.py

@@ -10,6 +10,7 @@ from .result_models import (
     JobResult,
     QueryResult,
     ScopedTokenResult,
+    StorageJobResult,
     StreamSourceResult,
     SyncPushResult,
     TokenListEntryResult,
@@ -32,6 +33,7 @@ __all__ = [
     "JobResult",
     "QueryResult",
     "ScopedTokenResult",
+    "StorageJobResult",
     "StreamSourceResult",
     "SyncPushResult",
     "TokenListEntryResult",

{keboola_cli-0.97.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.97.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)