keboola-cli 0.63.4__tar.gz → 0.65.0__tar.gz

{keboola_cli-0.63.4 → keboola_cli-0.65.0}/CLAUDE.md

@@ -424,13 +424,26 @@ kbagent workspace from-transformation --project ALIAS --component-id ID --config
 
 kbagent data-app list [--project NAME ...] [--branch ID]
 kbagent data-app detail --project NAME --app-id ID [--branch ID]
-kbagent data-app create --project ALIAS --name NAME --slug SLUG --git-repo URL [--description STR | --description-file PATH] [--git-branch main] [--git-public/--no-git-public] [--git-username USER] [--git-pat-env VAR | --git-pat-file PATH | --git-pat-encrypted KBC::Project...] [--auth password|public] [--size tiny|small|medium|large] [--auto-suspend SECONDS] [--type python-js|python|streamlit|r|...] [--branch ID] [--no-deploy] [--wait] [--timeout SECONDS] [--keep-on-failure] [--dry-run]
+kbagent data-app create --project ALIAS --name NAME --slug SLUG (--git-repo URL | --use-managed-git-repo) [--description STR | --description-file PATH] [--git-branch main] [--git-public/--no-git-public] [--git-username USER] [--git-pat-env VAR | --git-pat-file PATH | --git-pat-encrypted KBC::Project...] [--auth password|public] [--size tiny|small|medium|large] [--auto-suspend SECONDS] [--type python-js|python|streamlit|r|...] [--branch ID] [--no-deploy] [--wait] [--timeout SECONDS] [--keep-on-failure] [--dry-run]
+# Exactly one git source is required: --git-repo URL (external) OR --use-managed-git-repo (0.65.0+).
+# --use-managed-git-repo provisions an EMPTY Keboola-hosted repo (POST useManagedGitRepo:true), writes
+#   NO parameters.dataApp.git block, and forces --no-deploy (nothing to run yet). Mutually exclusive with
+#   --git-repo and all --git-*/PAT auth flags. Full flow to a RUNNING managed-repo app (0.65.0+):
+#   (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
+#   git-bind-credential` (mints an http_token ON the app, encrypts it under the project KMS, and writes
+#   parameters.dataApp.git so the runtime's `git clone` can authenticate -- required on stacks that do NOT
+#   inject managed-repo creds at deploy time) -> (4) `data-app deploy`. 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, e.g. git-clone "could not read Username", produce no container logs).
 kbagent data-app deploy --project NAME --app-id ID [--config-version N] [--wait] [--timeout SECONDS] [--branch ID]
 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]
 kbagent data-app password --project NAME --app-id ID
 kbagent data-app logs --project NAME --app-id ID [--lines N] [--since ISO8601]
+kbagent data-app runs --project NAME --app-id ID [--limit N]
 kbagent data-app secrets-set --project ALIAS --app-id ID --secret '#KEY=VALUE' [--secret ...] [--secrets-file PATH] [--branch ID] [--allow-plaintext-on-encrypt-failure] [--dry-run] [--no-hint-next]
 kbagent data-app secrets-list --project ALIAS --app-id ID [--branch ID] [--show-fingerprint]
 kbagent data-app secrets-get --project ALIAS --app-id ID --key 'KEY' [--branch ID]   # '#' optional; plain values return their value, encrypted return metadata only
@@ -441,6 +454,7 @@ kbagent data-app git-branches --project NAME --app-id ID
 kbagent data-app git-entrypoints --project NAME --app-id ID
 kbagent data-app git-credentials --project NAME --app-id ID
 kbagent data-app git-credentials-create --project NAME --app-id ID --type ssh_key|http_token --permissions readOnly|readWrite [--public-key KEY | --public-key-file PATH] [--name LABEL] [--yes]
+kbagent data-app git-bind-credential --project NAME --app-id ID [--branch-name main] [--permissions readOnly|readWrite] [--dry-run]
 # git-repo/git-branches/git-entrypoints introspect the deployed-from git repo (sandboxes-service /apps/{id}/git-repo/*); they return 409 "no Git repository configured" until the app has been DEPLOYED at least once (git config syncs Storage->DS record at deploy). git-credentials* manage credentials for a MANAGED repo only; apps from `data-app create --git-repo` are external => git-credentials-create returns 409. http_token mints a ONE-TIME secret (shown once); credentials endpoints need an admin storage token.
 
 kbagent component list [--project NAME] [--type TYPE] [--query QUERY]

{keboola_cli-0.63.4 → keboola_cli-0.65.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: keboola-cli
-Version: 0.63.4
+Version: 0.65.0
 Summary: AI-friendly CLI for managing Keboola projects
 Author-email: Keboola <dev@keboola.com>
 License-Expression: MIT

{keboola_cli-0.63.4 → keboola_cli-0.65.0}/pyproject.toml

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

{keboola_cli-0.63.4 → keboola_cli-0.65.0}/src/keboola_agent_cli/changelog.py

@@ -24,6 +24,77 @@ 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.65.0": [
+        "New: deploy a data app from a Keboola-MANAGED git repository end-to-end. "
+        "`data-app create --use-managed-git-repo` provisions an EMPTY Keboola-hosted repo (POST "
+        "`useManagedGitRepo:true`, no `parameters.dataApp.git` block, forces `--no-deploy`; "
+        "mutually exclusive with `--git-repo` and every `--git-*`/PAT flag). The full flow to a "
+        "running app: create -> `git-credentials-create --type http_token --permissions readWrite` "
+        "+ `git push` to the managed URL -> `data-app git-bind-credential` -> `data-app deploy`. "
+        "Verified live (tic-tac-toe serving from a managed repo).",
+        "New: `data-app git-bind-credential --project P --app-id ID [--branch-name main] "
+        "[--permissions readOnly|readWrite]` mints an `http_token` ON the app, encrypts it under "
+        "the project KMS, and writes `parameters.dataApp.git` (repository + placeholder username + "
+        "encrypted `#password` + branch). Required on stacks that do not inject managed-repo "
+        "credentials at deploy time -- without it the runtime's `git clone` of the managed repo "
+        "fails `could not read Username` and the deploy reverts to stopped. The token is encrypted "
+        "in place and never printed; `--dry-run` previews what would be wired without minting the "
+        "one-time credential or touching the config.",
+        "New: `data-app runs --project P --app-id ID [--limit N]` lists a data app's recent "
+        "deployment attempts with `failure_reason` + `startup_logs`, including setup-phase failures "
+        "(e.g. a git-clone error during `app_setup`) that produce no container logs. It works on "
+        "never-started / failed apps where `data-app logs` returns HTTP 400 -- the canonical way to "
+        "find out why a deploy reverted to `stopped` without the app ever serving.",
+        "Fix: `data-app deploy` now resolves the deployed `configVersion` by source location -- it "
+        "pins the latest Storage version when a git block is present (external repos AND a "
+        "credential-wired managed repo) so the operator reads the current source, and omits "
+        "`configVersion` only for a pure managed repo (deploys from `app.managedGitRepoId`). "
+        "Previously it always pinned, which pointed managed-repo deploys at a config snapshot with "
+        "no git source and made them silently revert to stopped.",
+        "UX: when `data-app deploy --wait` times out or the app reaches state=error, the error now "
+        "auto-fetches the latest run's `failure_reason` (via /apps/{id}/runs) and includes it inline "
+        '-- including setup-phase failures with no container logs -- instead of a bare "timed out" '
+        "message. A managed-repo clone-auth failure (`could not read Username`) adds an actionable "
+        "hint to run `data-app git-bind-credential`. The diagnostic is best-effort and never masks "
+        "the original error.",
+        "All of the above are mirrored 1:1 on the `kbagent serve` REST API "
+        "(`/data-app/.../runs`, `/data-app/.../git-repo/bind-credential`, and the "
+        "`use_managed_git_repo` field on create).",
+        "New (#446): the `install.sh` bootstrap got a first-run onboarding pass -- it "
+        "auto-installs `uv` when it is missing (opt out with `KBAGENT_NO_UV_BOOTSTRAP=1`), quiets "
+        "the install output behind tidy step lines, and finishes with a Keboola banner plus a "
+        "'next steps' footer (`kbagent project add`, `kbagent --help`) so first-time users know "
+        "what to run next.",
+    ],
+    "0.64.0": [
+        "New: data-app git-repo introspection + managed-repo credentials -- five `data-app "
+        "git-*` commands over the sandboxes-service `/apps/{id}/git-repo/*` endpoints. "
+        "`git-repo` shows the clone URLs + a managed flag, `git-branches` lists remote branches "
+        "with commit metadata, `git-entrypoints` lists root-level `.py` files, `git-credentials` "
+        "lists managed-repo credentials, and `git-credentials-create` mints an SSH key or HTTP "
+        "token (a one-time secret for `http_token`). Mirrored 1:1 on the `kbagent serve` REST "
+        "API. The read trio needs only the project storage token; the credential pair is "
+        "managed-repo only (admin token). Gotcha: the introspection endpoints return 409 until "
+        "the app has been deployed at least once -- the git block syncs from the Storage config "
+        "into the Data Science app record at deploy time (first tagged 0.63.3, #414).",
+        "Security: `kbagent serve --ui` now decides which paths require auth via the router "
+        "match protocol and fails closed, fixing a fastapi-0.137 nested-router bypass that "
+        "served `/doctor`, `/version`, `/changelog`, and `/agents` unauthenticated "
+        "(GHSA-ffpq-prmh-3gx2); the temporary `fastapi<0.137` cap is lifted (0.63.4).",
+        "Fix: invalid `--mode` / `--poll-strategy` (`job run`), `--role` / `--default-role` "
+        "(`project invite`, `member-set-role`) and `--role-hint` (`dev-portal identity`) values "
+        "fail with a clean exit-2 usage error again instead of an uncaught traceback -- they "
+        "regressed under Typer >=0.25's vendored Click, so the choice options now use `StrEnum`. "
+        "The interactive REPL `help` and tab-completion again list every command (0.63.4).",
+        "Change: kbagent now ships as a self-contained native binary via Homebrew / apt / dnf / "
+        "apk / Chocolatey / WinGet (PyInstaller + nfpm release pipeline), alongside the existing "
+        "pip / uv install (#405).",
+        "Internal: the data-app command and service layers were split into sibling modules "
+        "(`commands/_data_app_git.py`, `commands/_data_app_runtime.py`, "
+        "`services/data_app_git_service.py`) to keep `data_app.py` under the file-size budget -- "
+        "no behavior change (#423). Dependency bumps: cryptography 48, starlette 1.3, "
+        "python-multipart 0.0.31, pyjwt 2.13.",
+    ],
     "0.63.4": [
         "Fix: the interactive REPL `help` command and tab-completion again list every "
         "command instead of only `help`/`exit`. `_build_command_tree` guarded its walk "

{keboola_cli-0.63.4 → keboola_cli-0.65.0}/src/keboola_agent_cli/commands/_data_app_git.py

@@ -341,3 +341,70 @@ def register_git_commands(app: typer.Typer) -> None:
                 )
 
         formatter.output(result, _human)
+
+    @app.command("git-bind-credential")
+    def data_app_git_bind_credential(
+        ctx: typer.Context,
+        project: str = typer.Option(..., "--project", help="Project alias"),
+        app_id: str = typer.Option(..., "--app-id", help="Data Science numeric app id"),
+        branch: str = typer.Option(
+            "main", "--branch-name", help="Managed-repo branch to deploy from (default main)."
+        ),
+        permissions: str = typer.Option(
+            "readOnly",
+            "--permissions",
+            help="Credential access level: readOnly (default) | readWrite.",
+        ),
+        dry_run: bool = typer.Option(
+            False,
+            "--dry-run",
+            help="Preview what would be wired (repo/branch/permissions) WITHOUT minting a credential or editing the config.",
+        ),
+    ) -> None:
+        """Make a MANAGED-repo app deployable by wiring a credential into its config.
+
+        A `--use-managed-git-repo` app owns an empty Keboola-hosted repo but its
+        Storage config has no git block. On stacks that do NOT inject managed-repo
+        credentials at deploy time, the runtime's `git clone` of the managed repo
+        fails ("could not read Username") and the deploy reverts to stopped. This
+        command mints a fresh `http_token` ON the app, encrypts it under the
+        project KMS, and writes `parameters.dataApp.git` (repository + placeholder
+        username + encrypted `#password` + branch) so the next `data-app deploy`
+        can clone. The token is encrypted in-place and never printed.
+
+        `--dry-run` validates the app + resolves the managed repo URL but mints
+        nothing and leaves the config untouched -- the http_token is one-time, so
+        a real run that you abort would orphan it.
+        """
+        formatter = get_formatter(ctx)
+        service = get_service(ctx, "data_app_service")
+        try:
+            result = service.bind_managed_credential(
+                project, app_id, branch=branch, permissions=permissions, dry_run=dry_run
+            )
+        except KeboolaApiError as exc:
+            formatter.error(
+                message=exc.message,
+                error_code=exc.error_code,
+                retryable=exc.retryable,
+                details=exc.details,
+            )
+            raise typer.Exit(code=map_error_to_exit_code(exc)) from None
+        except ConfigError as exc:
+            formatter.error(message=exc.message, error_code=ErrorCode.CONFIG_ERROR)
+            raise typer.Exit(code=5) from None
+
+        def _human(c: Console, d: dict) -> None:
+            if d.get("dry_run"):
+                c.print("[bold]DRY RUN -- no credential minted, config unchanged.[/bold]")
+                c.print(f"  [bold]Repository:[/bold] {d.get('repository', '')}")
+                c.print(f"  [bold]Branch:[/bold] {d.get('branch', '')}")
+                c.print(f"  [bold]Permissions:[/bold] {d.get('permissions', '')}")
+                return
+            c.print(f"[bold green]Success:[/bold green] {d['message']}")
+            c.print(f"  [bold]Repository:[/bold] {d.get('repository', '')}")
+            c.print(f"  [bold]Branch:[/bold] {d.get('branch', '')}")
+            c.print(f"  [bold]Permissions:[/bold] {d.get('permissions', '')}")
+            c.print(f"  [bold]Config version:[/bold] {d.get('config_version', '')}")
+
+        formatter.output(result, _human)

keboola_cli-0.65.0/src/keboola_agent_cli/commands/_data_app_runtime.py

@@ -0,0 +1,436 @@
+"""Data-app runtime-secrets commands -- secrets-set / -list / -get / -remove.
+
+Split out of ``data_app.py`` to keep that module under the CONTRIBUTING.md
+file-size budget (see "File-size budgets"). These commands manage the
+``parameters.dataApp.secrets`` block of a data app's Storage config (the
+app-runtime env-var secrets); the business logic stays on ``DataAppService``.
+They attach to the existing ``data-app`` Typer sub-app via
+:func:`register_secrets_commands`, called at the bottom of ``data_app.py``, so
+they still surface as ``kbagent data-app secrets-*`` with identical names,
+permission keys, and serve REST routes.
+
+The module is deliberately NOT named ``_data_app_secrets.py``: the repo's
+permission config denies Read/Write/Edit on any path matching ``*secrets*``.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from ..errors import ConfigError, ErrorCode, KeboolaApiError
+from ._helpers import get_formatter, get_service, map_error_to_exit_code
+
+# Canonical Keboola help-doc reference (mirrors data_app.py).
+_REF_STORAGE_ACCESS = "https://help.keboola.com/data-apps/storage-access/"
+
+
+def _parse_secret_arg(arg: str) -> tuple[str, str]:
+    """Split ``#KEY=VALUE`` into ``(key, value)``.
+
+    The value may contain ``=``; only the FIRST ``=`` is the separator.
+    """
+    if "=" not in arg:
+        raise typer.BadParameter(
+            f"Expected '#KEY=VALUE'; got {arg!r} (no '=' separator).",
+            param_hint="--secret",
+        )
+    key, _, value = arg.partition("=")
+    if not key:
+        raise typer.BadParameter(
+            f"Empty secret key in {arg!r}; expected '#KEY=VALUE'.",
+            param_hint="--secret",
+        )
+    return key, value
+
+
+def _read_secrets_file(path: Path) -> dict[str, str]:
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise typer.BadParameter(
+            f"Cannot read secrets file {path}: {exc}",
+            param_hint="--secrets-file",
+        ) from exc
+    try:
+        parsed = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise typer.BadParameter(
+            f"Secrets file {path} is not valid JSON: {exc}",
+            param_hint="--secrets-file",
+        ) from exc
+    if not isinstance(parsed, dict):
+        raise typer.BadParameter(
+            f"Secrets file {path} must be a JSON object mapping #KEY -> value.",
+            param_hint="--secrets-file",
+        )
+    out: dict[str, str] = {}
+    for key, value in parsed.items():
+        if not isinstance(key, str) or not isinstance(value, str):
+            raise typer.BadParameter(
+                f"Secrets file {path} contains non-string entry for {key!r}.",
+                param_hint="--secrets-file",
+            )
+        out[key] = value
+    if not out:
+        raise typer.BadParameter(
+            f"Secrets file {path} is empty.",
+            param_hint="--secrets-file",
+        )
+    return out
+
+
+def data_app_secrets_set(
+    ctx: typer.Context,
+    project: str = typer.Option(..., "--project", help="Project alias"),
+    app_id: str = typer.Option(..., "--app-id", help="Data Science numeric app id"),
+    secret: list[str] | None = typer.Option(
+        None,
+        "--secret",
+        help=(
+            "One or more '#KEY=VALUE' plaintext entries. Repeatable. "
+            "Mutually exclusive with --secrets-file."
+        ),
+    ),
+    secrets_file: Path | None = typer.Option(
+        None,
+        "--secrets-file",
+        help="Path to a JSON file mapping '#KEY' -> 'plaintext value'.",
+        exists=True,
+        readable=True,
+        dir_okay=False,
+    ),
+    branch: int | None = typer.Option(
+        None,
+        "--branch",
+        help="Storage branch ID for the linked config (defaults to production).",
+    ),
+    allow_plaintext_on_encrypt_failure: bool = typer.Option(
+        False,
+        "--allow-plaintext-on-encrypt-failure",
+        help=(
+            "Bootstrap/debug only: write the value as-is if the Encryption API "
+            "did not return a project-scoped ciphertext. NEVER use in production."
+        ),
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Show the encryption request and Storage PUT body without making either call.",
+    ),
+    no_hint_next: bool = typer.Option(
+        False,
+        "--no-hint-next",
+        help="Suppress the 'now run kbagent data-app deploy' hint in the output.",
+    ),
+) -> None:
+    """Encrypt and write app-runtime secrets to the linked Storage config.
+
+    The '#'-prefix is required on every key (Keboola encryption convention).
+    The runtime exposes each secret as an env var with '#' stripped, '-'
+    replaced with '_', and uppercased ('#my-api-key' -> 'MY_API_KEY').
+
+    The command never auto-deploys; the running container keeps the old
+    config until the next 'kbagent data-app deploy' call.
+
+    Reference: https://help.keboola.com/data-apps/python-js/
+    """
+
+    formatter = get_formatter(ctx)
+    service = get_service(ctx, "data_app_service")
+
+    if secret and secrets_file:
+        formatter.error(
+            message=("--secret and --secrets-file are mutually exclusive; pick one input mode."),
+            error_code=ErrorCode.USAGE_ERROR,
+        )
+        raise typer.Exit(code=2) from None
+
+    if not secret and not secrets_file:
+        formatter.error(
+            message=("Provide at least one --secret '#KEY=VALUE' or --secrets-file PATH."),
+            error_code=ErrorCode.MISSING_PARAMETER,
+        )
+        raise typer.Exit(code=2) from None
+
+    secrets_map: dict[str, str] = {}
+    if secret:
+        for entry in secret:
+            try:
+                key, value = _parse_secret_arg(entry)
+            except typer.BadParameter as exc:
+                formatter.error(
+                    message=str(exc),
+                    error_code=ErrorCode.DATA_APP_INVALID_SECRET,
+                )
+                raise typer.Exit(code=2) from None
+            secrets_map[key] = value
+    if secrets_file:
+        try:
+            secrets_map.update(_read_secrets_file(secrets_file))
+        except typer.BadParameter as exc:
+            formatter.error(
+                message=str(exc),
+                error_code=ErrorCode.DATA_APP_INVALID_SECRET,
+            )
+            raise typer.Exit(code=2) from None
+
+    try:
+        result = service.set_data_app_secrets(
+            alias=project,
+            app_id=app_id,
+            secrets=secrets_map,
+            branch_id=branch,
+            allow_plaintext_on_encrypt_failure=allow_plaintext_on_encrypt_failure,
+            dry_run=dry_run,
+        )
+    except KeboolaApiError as exc:
+        formatter.error(
+            message=exc.message,
+            error_code=exc.error_code,
+            retryable=exc.retryable,
+            details=exc.details,
+        )
+        raise typer.Exit(code=map_error_to_exit_code(exc)) from None
+    except ConfigError as exc:
+        formatter.error(message=exc.message, error_code=ErrorCode.CONFIG_ERROR)
+        raise typer.Exit(code=5) from None
+
+    # Reserved-name shadowing -- emit stderr WARN per collision so a
+    # script piping stdout to a JSON parser is unaffected.
+    shadowed = result.get("shadowed_by_runtime", [])
+    if shadowed and not formatter.json_mode:
+        for env_var in shadowed:
+            formatter.err_console.print(
+                f"[yellow]Warning:[/yellow] {env_var} is auto-injected by the data-app "
+                f"runtime; the platform value silently shadows yours. See {_REF_STORAGE_ACCESS}.",
+                style="yellow",
+            )
+
+    if no_hint_next and isinstance(result, dict):
+        result.pop("next_step", None)
+
+    formatter.output(
+        result,
+        lambda c, d: c.print(f"[bold green]Success:[/bold green] {d['message']}"),
+    )
+    if not no_hint_next and not formatter.json_mode and result.get("next_step"):
+        formatter.console.print(f"[dim]Next: {result['next_step']}[/dim]")
+
+
+def data_app_secrets_list(
+    ctx: typer.Context,
+    project: str = typer.Option(..., "--project", help="Project alias"),
+    app_id: str = typer.Option(..., "--app-id", help="Data Science numeric app id"),
+    branch: int | None = typer.Option(
+        None,
+        "--branch",
+        help="Storage branch ID for the linked config (defaults to production).",
+    ),
+    show_fingerprint: bool = typer.Option(
+        False,
+        "--show-fingerprint",
+        help="Include a short ciphertext fingerprint per key. Default omits to keep --json safe to paste into tickets.",
+    ),
+) -> None:
+    """List the keys in parameters.dataApp.secrets, with derived runtime env-var names.
+
+    Never echoes the encrypted ciphertext in full and never decrypts.
+
+    Reference: https://help.keboola.com/data-apps/python-js/
+    """
+
+    formatter = get_formatter(ctx)
+    service = get_service(ctx, "data_app_service")
+    try:
+        result = service.list_data_app_secrets(
+            alias=project,
+            app_id=app_id,
+            branch_id=branch,
+            show_fingerprint=show_fingerprint,
+        )
+    except KeboolaApiError as exc:
+        formatter.error(
+            message=exc.message,
+            error_code=exc.error_code,
+            retryable=exc.retryable,
+            details=exc.details,
+        )
+        raise typer.Exit(code=map_error_to_exit_code(exc)) from None
+    except ConfigError as exc:
+        formatter.error(message=exc.message, error_code=ErrorCode.CONFIG_ERROR)
+        raise typer.Exit(code=5) from None
+
+    if formatter.json_mode:
+        formatter.output(result)
+        return
+
+    if not result["secrets"]:
+        formatter.console.print("[dim]No secrets set on this data app.[/dim]")
+        return
+    formatter.console.print(
+        f"\n[bold]{result['count']} secret(s)[/bold] on data app "
+        f"[cyan]{result['app_id']}[/cyan] in [magenta]{result['project_alias']}[/magenta]:"
+    )
+    for entry in result["secrets"]:
+        marker = (
+            " [yellow](shadowed by runtime)[/yellow]" if entry.get("shadowed_by_runtime") else ""
+        )
+        line = f"  [bold]{entry['key']}[/bold] -> env [cyan]{entry['env_var']}[/cyan]{marker}"
+        if "fingerprint" in entry:
+            line += f"  [dim]fingerprint={entry['fingerprint']}  prefix={entry.get('encryption_prefix', '')}[/dim]"
+        formatter.console.print(line)
+
+
+def data_app_secrets_get(
+    ctx: typer.Context,
+    project: str = typer.Option(..., "--project", help="Project alias"),
+    app_id: str = typer.Option(..., "--app-id", help="Data Science numeric app id"),
+    key: str = typer.Option(
+        ..., "--key", help="Env-var key (with optional '#' prefix for encrypted secrets)."
+    ),
+    branch: int | None = typer.Option(
+        None,
+        "--branch",
+        help="Storage branch ID for the linked config (defaults to production).",
+    ),
+) -> None:
+    """Show ONE key from parameters.dataApp.secrets.
+
+    For an ENCRYPTED ('#') secret this is metadata only -- the Encryption
+    API has no decrypt endpoint, so the CLI never echoes the decrypted
+    value. For a PLAIN (unencrypted) config value the literal value is
+    shown; it is already stored in clear and visible via `config detail`.
+
+    Reference: https://help.keboola.com/data-apps/python-js/
+    """
+
+    formatter = get_formatter(ctx)
+    service = get_service(ctx, "data_app_service")
+    try:
+        result = service.get_data_app_secret(
+            alias=project,
+            app_id=app_id,
+            key=key,
+            branch_id=branch,
+        )
+    except KeboolaApiError as exc:
+        formatter.error(
+            message=exc.message,
+            error_code=exc.error_code,
+            retryable=exc.retryable,
+            details=exc.details,
+        )
+        raise typer.Exit(code=map_error_to_exit_code(exc)) from None
+    except ConfigError as exc:
+        formatter.error(message=exc.message, error_code=ErrorCode.CONFIG_ERROR)
+        raise typer.Exit(code=5) from None
+
+    if formatter.json_mode:
+        formatter.output(result)
+        return
+    formatter.console.print(
+        f"\n[bold]{result['key']}[/bold] -> env [cyan]{result['env_var']}[/cyan]"
+    )
+    if result.get("encrypted"):
+        formatter.console.print(
+            f"  [dim]fingerprint={result['fingerprint']}  prefix={result['encryption_prefix']}[/dim]"
+        )
+    else:
+        formatter.console.print(f"  value (plaintext, unencrypted): {result['value']}")
+        formatter.err_console.print(
+            "  [yellow]Note:[/yellow] this value is stored unencrypted in the config. "
+            "Use `data-app secrets-set '#KEY=...'` to store sensitive values encrypted."
+        )
+    if result.get("shadowed_by_runtime"):
+        # Same stdout/stderr-separation rationale as secrets-set: keep
+        # warnings off stdout so a script piping the metadata to a parser
+        # is unaffected.
+        formatter.err_console.print(
+            f"  [yellow]Warning:[/yellow] {result['env_var']} is auto-injected by "
+            f"the data-app runtime; the platform value silently shadows yours. "
+            f"See {_REF_STORAGE_ACCESS}."
+        )
+
+
+def data_app_secrets_remove(
+    ctx: typer.Context,
+    project: str = typer.Option(..., "--project", help="Project alias"),
+    app_id: str = typer.Option(..., "--app-id", help="Data Science numeric app id"),
+    key: list[str] = typer.Option(
+        ...,
+        "--key",
+        help="Env-var key to remove (with optional '#' prefix). Repeatable.",
+    ),
+    branch: int | None = typer.Option(
+        None,
+        "--branch",
+        help="Storage branch ID for the linked config (defaults to production).",
+    ),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip the confirmation prompt."),
+    dry_run: bool = typer.Option(
+        False, "--dry-run", help="Preview the Storage PUT body without making the call."
+    ),
+) -> None:
+    """Remove one or more app-runtime secrets. Idempotent (missing keys are exit 0).
+
+    A removal can break the running app at the next deploy if it relied on
+    the secret; the command flags this in the response and never auto-deploys.
+
+    Reference: https://help.keboola.com/data-apps/python-js/
+    """
+
+    formatter = get_formatter(ctx)
+    service = get_service(ctx, "data_app_service")
+
+    if (
+        not yes
+        and not formatter.json_mode
+        and not dry_run
+        and not typer.confirm(
+            f"Remove {len(key)} secret(s) from data app {app_id} in '{project}'? "
+            "This may break the app at next deploy if it depends on these values."
+        )
+    ):
+        formatter.console.print("Aborted.")
+        raise typer.Exit(code=0)
+
+    try:
+        result = service.remove_data_app_secrets(
+            alias=project,
+            app_id=app_id,
+            keys=key,
+            branch_id=branch,
+            dry_run=dry_run,
+        )
+    except KeboolaApiError as exc:
+        formatter.error(
+            message=exc.message,
+            error_code=exc.error_code,
+            retryable=exc.retryable,
+            details=exc.details,
+        )
+        raise typer.Exit(code=map_error_to_exit_code(exc)) from None
+    except ConfigError as exc:
+        formatter.error(message=exc.message, error_code=ErrorCode.CONFIG_ERROR)
+        raise typer.Exit(code=5) from None
+
+    formatter.output(
+        result,
+        lambda c, d: c.print(f"[bold green]Success:[/bold green] {d['message']}"),
+    )
+
+
+def register_secrets_commands(app: typer.Typer) -> None:
+    """Attach the data-app secrets-* commands to the data-app sub-app.
+
+    Module-level command functions registered explicitly (rather than via
+    inline ``@app.command`` closures) keep the large bodies un-indented and
+    diff-friendly relative to their previous home in ``data_app.py``.
+    """
+    app.command("secrets-set")(data_app_secrets_set)
+    app.command("secrets-list")(data_app_secrets_list)
+    app.command("secrets-get")(data_app_secrets_get)
+    app.command("secrets-remove")(data_app_secrets_remove)