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

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

@@ -627,8 +627,37 @@ kbagent storage table-detail --project NAME --table-id ID [--branch ID]
 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]
 # --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]
@@ -675,13 +704,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
@@ -1007,6 +1042,26 @@ kbagent sync push --project ALIAS [--all-projects] [--dry-run] [--force] [--allo
 #   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 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
@@ -1054,7 +1109,7 @@ kbagent dev-portal deprecate --app VENDOR.APP_ID [--identity A] [--dry-run]
 kbagent encrypt values --project ALIAS --component-id ID --input JSON|@file|- [--output-file PATH]
 
 kbagent semantic-layer model list --project P
-kbagent semantic-layer model create --project P --name N [--description D] [--sql-dialect Snowflake]
+kbagent semantic-layer model create --project P --name N [--description D] [--sql-dialect Snowflake] [--scope project|organization|targeted] [--target-project ALIAS|ID ...]
 kbagent semantic-layer model delete --project P --model M [--yes]
 kbagent semantic-layer show --project P [--model M] [--type dataset|metric|relationship|constraint|glossary]
 kbagent semantic-layer search-context --project P [--pattern G ...] [--type model|dataset|metric|relationship|constraint|glossary|all] [--limit N]
@@ -1077,7 +1132,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,23 +1143,67 @@ 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"
+#   (owner only), "organization" (every project in the org), or "targeted" (owner +
+#   explicit --target-project grants). --scope/--target-project are also accepted by `model
+#   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). `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
+#   fast (exit 2). A bad alias/ID/--scope/--type is a usage error (exit 2), never a traceback.
+#   Creating directly at --scope organization requires the organization-admin ROLE (403
+#   otherwise) -- an ordinary token instead uses `scope request-create` + an org-admin's
+#   `scope set --scope organization`. Elevation is ONE-WAY (no downgrade endpoint), which is why
+#   every `--scope organization` (here and on `model create` / `add <kind>`) is destructive-class
+#   (FLAG_ESCALATIONS). `edit`, `import --overwrite` and `promote` update in place (PUT): an item
+#   keeps its id, scope, grants and pending elevation request. `scope add|remove` merge into the
+#   grants client-side (not atomic; refused from a project that does not own the item, because
+#   the server hides the grants from a non-owner -- use `scope set --target-project` there).
+#   Verbs follow the CLI spec (#791): get / add / remove / set / request-create / request-delete /
+#   request-list; `scope set` takes exactly ONE of --scope organization, --target-project (replace
+#   the whole list) or --clear.
+kbagent semantic-layer scope get --project P --type model|dataset|metric|relationship|constraint|glossary --context-id ID
+kbagent semantic-layer scope add --project P --type T --context-id ID --target-project ALIAS|ID [--target-project ...]
+kbagent semantic-layer scope remove --project P --type T --context-id ID --target-project ALIAS|ID [--target-project ...]
+kbagent semantic-layer scope set --project P --type T --context-id ID (--scope organization | --target-project ALIAS|ID [...] | --clear) [--dry-run] [--yes]
+kbagent semantic-layer scope request-create --project P --type T --context-id ID
+kbagent semantic-layer scope request-delete --project P --type T --context-id ID
+kbagent semantic-layer scope request-list --project P --type T [--limit N] [--offset N]
+# scope over `kbagent serve`: GET/PUT /semantic-layer/scope/{context_id}, POST/DELETE
+#   .../target-projects, PUT/DELETE .../elevation-request, GET /semantic-layer/scope/elevation-requests;
+#   POST /semantic-layer/models and /items/{kind} take `scope` + `target_projects`.
 kbagent semantic-layer reference-data list --project P [--model M]
 kbagent semantic-layer reference-data get --project P (--id ID | --dimension D)
 kbagent semantic-layer reference-data set --project P [--model M] --dimension D --members-file PATH [--dataset-id T] [--description X]
 kbagent semantic-layer reference-data delete --project P --id ID [--yes]
 # Alias: `kbagent sl ...` (hidden) is equivalent to `kbagent semantic-layer ...`.
-# semantic-layer REQUIRES A MASTER (project admin) Storage token (#711): the Metastore's
-#   auth gate -- unlike the Storage API -- rejects every valid non-master token with an opaque
-#   401 "Failed to create project scope" (the underlying MasterTokenRequiredError is swallowed
-#   server-side). kbagent reclassifies exactly that 401 to MISSING_MASTER_TOKEN (exit 3) with
-#   the remedy; other unexplained 401s anywhere map to AUTH_REJECTED instead of the false
-#   "Invalid or expired token" (INVALID_TOKEN stays for 401s that DO blame the credential).
-#   Version gate for this entry lives in gotchas.md -- `(since vNEXT)` cannot be written on
-#   these `# ` comment lines (check_version_gates.py parses them as ATX headings).
+# semantic-layer READS work with any valid, non-disabled, non-expired Storage token
+#   (0.97.0, PSGO-282): the Metastore no longer requires a master token for GET/List. WRITES
+#   (add/edit/remove/import/promote/build/scope add|remove|set) still need a project-admin token
+#   (master token or any admin-role user token) -- a non-admin token 403s on the write. Before
+#   PSGO-282 the Metastore's auth gate rejected EVERY valid non-master token, including reads,
+#   with an opaque 401 "Failed to create project scope" (#711, MasterTokenRequiredError swallowed
+#   server-side); kbagent still reclassifies exactly that 401 to MISSING_MASTER_TOKEN (exit 3) as
+#   a safety net for a deployment that predates the fix. Other unexplained 401s anywhere map to
+#   AUTH_REJECTED instead of the false "Invalid or expired token" (INVALID_TOKEN stays for 401s
+#   that DO blame the credential). Version gate for this entry lives in gotchas.md -- `(since
+#   0.97.0)` cannot be written on these `# ` comment lines (check_version_gates.py parses them as
+#   ATX headings).
 
 kbagent http get PATH [--timeout SECONDS]
 kbagent http post PATH [--body JSON|@file|-] [--timeout SECONDS]

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: keboola-cli
-Version: 0.96.2
+Version: 0.98.0
 Summary: AI-friendly CLI for managing Keboola projects
 Author-email: Keboola <dev@keboola.com>
 License-Expression: Apache-2.0

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

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

{keboola_cli-0.96.2 → keboola_cli-0.98.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.96.2 → keboola_cli-0.98.0}/src/keboola_agent_cli/changelog.py

@@ -26,6 +26,60 @@ from .constants import CHANGELOG_HEADLINE_MAX_CHARS
 
 # Ordered newest-first.  Each value is a list of brief one-line descriptions.
 CHANGELOG: dict[str, list[str]] = {
+    "0.98.0": [
+        "New (#837): `storage upload-table` and `file-upload` now upload large files to AWS "
+        "stacks in parts, so files over 5 GB work and memory stays flat. Files above 64 MiB are "
+        "sent as an S3 multipart upload: 64 MiB parts, four in parallel, each part retried on "
+        "its own. Before, kbagent read the whole file into memory and S3 refused anything over "
+        "5 GB. In a test, a 10 GB file that 0.97.0 could not upload (it used 10 GB of memory and "
+        "then failed) uploaded in about four minutes with under 350 MB of memory. A `.csv.gz` "
+        "file is uploaded as it is. Azure and GCP stacks are unchanged.",
+        "New (#837): `storage upload-table` and `load-file` can queue the import without waiting "
+        "for it, and the new `storage job-detail` command follows the import. `--no-wait` "
+        "returns `job_id` and `file_id` as soon as the import is queued; `--timeout` sets how "
+        "long the default `--wait` waits. `storage job-detail --job-id ID [--wait]` shows the "
+        "status, the table and the imported rows. When the wait times out, the error says the "
+        "import keeps running, names the job, and is no longer marked retryable, so a long "
+        "upload is not repeated by mistake. `kbagent serve` (`GET /storage/jobs/{project}/"
+        "{job_id}`) and the SDK (`Client.storage_job()`) have the same functions.",
+        "New (#837): `--progress` shows percent, speed, elapsed time and time left for storage "
+        "uploads and downloads. It works on `storage upload-table`, `file-upload`, "
+        "`download-table`, `file-download` and `unload-table --download`, and writes to stderr, also with `--json`: a progress bar in "
+        "a terminal, otherwise one line every 10 seconds.",
+        "Fix (#837): `storage download-table --keep-slices`, `file-download` and `unload-table` "
+        "now keep every slice file inside the output directory. A slice name from the export manifest that "
+        "could point outside it (`..`, a backslash, a drive letter) is replaced by "
+        "`part-NNNNN`.",
+        "Fix (#747): commands that process several items now exit 1 and print `Failed:` when "
+        "an item fails. Before, `sync push`, `sync clone`, `org setup`, `project refresh`, "
+        "`workspace gc`, several `semantic-layer` commands, `storage describe-batch --json`, "
+        "`flow schedule-remove` and others printed `Success:` and exited 0 even when items "
+        "failed. A `--dry-run` that reports a failed item exits 1 too. The `--json` output "
+        "keeps its keys, with a few additions such as `errors[]` in `flow schedule-remove`.",
+        "Fix (#836): `semantic-layer import`, `promote` and `build --model` now give new items "
+        "the scope of the target model. Before, they created every item at `project` scope, "
+        "also in a shared model, so the other projects could not see it. Items they overwrite "
+        "keep their own scope. Duplicate-name and elevation errors now say what is wrong and "
+        "how to fix it.",
+        "Change (#836): `semantic-layer add glossary` now requires `--definition`. Without it the "
+        "Metastore always rejected the item with a bare 422 error, so no working call breaks.",
+    ],
+    "0.97.0": [
+        "New (#715): semantic-layer items can now be shared with chosen projects or with the "
+        "whole organization, not only kept in the owning project (AI-3790). `model create` and "
+        "every `add <kind>` take `--scope project|targeted|organization` and `--target-project` "
+        "(a registered alias or a project ID). The new `semantic-layer scope` command group "
+        "shows and changes who sees an existing item: `get`, `add`, `remove` and `set`, plus "
+        "`request-create`, `request-delete` and `request-list` for requests to make an item "
+        "organization-wide. Without `--scope`, `model create` keeps the model in its project, "
+        "and `add <kind>` uses the scope of its model. Making an item organization-wide needs "
+        "the organization-admin role and cannot be reverted, so `--deny-destructive` blocks it. "
+        "`kbagent serve` has the same functions under `/semantic-layer/scope`.",
+        "Fix (#715): `semantic-layer edit`, `import --overwrite` and `promote` now update an item "
+        "in place, so it keeps its ID, its visibility and its history. Before, they deleted the "
+        "item and created it again with a new ID. A failed update changes nothing, so the "
+        "`rollback` field in the result is now always `null`.",
+    ],
     "0.96.2": [
         "Fix (#825): the `data-app` commands now label the app link `Open the app:` and the "
         "Keboola UI link `Configuration:`, so it is clear which link opens what. Before, the "

{keboola_cli-0.96.2 → keboola_cli-0.98.0}/src/keboola_agent_cli/client/__init__.py

@@ -16,6 +16,7 @@ import time  # noqa: F401  -- re-exported: tests patch keboola_agent_cli.client.
 
 from ..constants import QUERY_RESULTS_PAGE_SIZE
 from ._client import KeboolaClient
+from ._core import storage_job_error_message
 from ._transfer import (
     InlineQueryResult,
     _assert_safe_download_url,
@@ -27,11 +28,13 @@ from ._transfer import (
     _iter_poll_intervals,
     _unwrap_bigquery_error,
 )
+from .storage_tables import TableUploadOutcome
 
 __all__ = [
     "QUERY_RESULTS_PAGE_SIZE",
     "InlineQueryResult",
     "KeboolaClient",
+    "TableUploadOutcome",
     "_CloudDownloader",
     "_assert_safe_download_url",
     "_build_abs_upload_url",
@@ -40,4 +43,5 @@ __all__ = [
     "_extract_query_job_error",
     "_iter_poll_intervals",
     "_unwrap_bigquery_error",
+    "storage_job_error_message",
 ]

{keboola_cli-0.96.2 → keboola_cli-0.98.0}/src/keboola_agent_cli/client/_core.py

@@ -16,13 +16,18 @@ from typing import Any, Self
 
 import httpx
 
-from ..constants import DEFAULT_TIMEOUT, STORAGE_JOB_MAX_WAIT, STORAGE_JOB_POLL_INTERVAL
+from ..constants import (
+    DEFAULT_TIMEOUT,
+    IMPORT_JOB_MAX_WAIT,
+    STORAGE_JOB_MAX_WAIT,
+    STORAGE_JOB_POLL_INTERVAL,
+)
 from ..errors import ErrorCode, KeboolaApiError
 from ..http_base import BaseHttpClient
 from ..stream_client import StreamClient
 
 
-def _storage_job_error_message(job: dict[str, Any]) -> str:
+def storage_job_error_message(job: dict[str, Any]) -> str:
     """Best-effort human message out of a failed Storage job's ``error`` field.
 
     Written tolerantly on purpose. An API ``error`` field is not reliably a
@@ -278,6 +283,8 @@ class _CoreClient(BaseHttpClient):
         self,
         job: dict[str, Any],
         max_wait: float | None = None,
+        *,
+        raise_on_error: bool = True,
     ) -> dict[str, Any]:
         """Poll a Storage API job until it reaches a terminal state.
 
@@ -309,12 +316,20 @@ class _CoreClient(BaseHttpClient):
                 ``STORAGE_JOB_MAX_WAIT``. Callers whose jobs are legitimately
                 slower pass their own budget -- e.g. a workspace load moving
                 gigabytes (``WORKSPACE_LOAD_JOB_MAX_WAIT``).
+            raise_on_error: When False, a job that ended in ``error`` is
+                returned like a successful one instead of raising
+                ``STORAGE_JOB_FAILED`` -- for a caller that reports the job
+                itself (``storage job-detail --wait``) and would otherwise
+                lose every field but the message.
 
         Returns:
-            Completed job dict (with results on success).
+            Terminal job dict (with results on success; with ``error`` when
+            ``raise_on_error`` is False and the job failed).
 
         Raises:
-            KeboolaApiError: If the job fails or times out.
+            KeboolaApiError: If the job fails (unless ``raise_on_error`` is
+                False) or the budget runs out. The timeout carries
+                ``details={"job_id": ...}``.
         """
         budget = STORAGE_JOB_MAX_WAIT if max_wait is None else max_wait
         job_id = job.get("id")
@@ -324,8 +339,10 @@ class _CoreClient(BaseHttpClient):
             if status == "success":
                 return job
             if status == "error":
+                if not raise_on_error:
+                    return job
                 raise KeboolaApiError(
-                    message=_storage_job_error_message(job),
+                    message=storage_job_error_message(job),
                     status_code=500,
                     error_code=ErrorCode.STORAGE_JOB_FAILED,
                     retryable=False,
@@ -351,4 +368,43 @@ class _CoreClient(BaseHttpClient):
             status_code=504,
             error_code=ErrorCode.STORAGE_JOB_TIMEOUT,
             retryable=True,
+            details={"job_id": job_id},
+        )
+
+    def get_storage_job(self, job_id: int | str) -> dict[str, Any]:
+        """Fetch one Storage API job (``GET /v2/storage/jobs/{id}``).
+
+        Job IDs are project-scoped and branch-independent: the route has no
+        ``/branch/{id}`` variant, so no branch is taken here.
+
+        Args:
+            job_id: Storage job ID (as returned by any async Storage write).
+
+        Returns:
+            The raw job dict (``id``, ``status``, ``operationName``,
+            ``operationParams``, ``results``, ``error``, timestamps, ...).
+        """
+        return self._request("GET", f"/v2/storage/jobs/{job_id}").json()
+
+    def follow_storage_job(
+        self, job_id: int | str, max_wait: float | None = None
+    ) -> dict[str, Any]:
+        """Fetch a Storage job and poll it to a terminal state.
+
+        Unlike the write paths, a job that ended in ``error`` is RETURNED, not
+        raised: the caller asked about the job, and the error is part of the
+        answer. A job already terminal costs exactly one GET.
+
+        Args:
+            job_id: Storage job ID.
+            max_wait: Seconds to poll. ``None`` means ``IMPORT_JOB_MAX_WAIT``
+                -- the jobs worth following by hand are the long imports.
+
+        Raises:
+            KeboolaApiError: ``STORAGE_JOB_TIMEOUT`` when the budget runs out
+                (the job keeps running; following it again is safe).
+        """
+        budget = IMPORT_JOB_MAX_WAIT if max_wait is None else max_wait
+        return self._wait_for_storage_job(
+            self.get_storage_job(job_id), max_wait=budget, raise_on_error=False
         )