vortex-cli 6.2.1__tar.gz → 6.4.0__tar.gz

{vortex_cli-6.2.1 → vortex_cli-6.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vortex_cli
-Version: 6.2.1
+Version: 6.4.0
 Summary: Vortex CLI
 Author-email: Jordan Amos <jordan.amos@gmail.com>
 License: MIT License
@@ -108,6 +108,18 @@ While it is possible to use without it, this software has been purposefully desi
    java_environment_name = JavaSE-17 ; Java Execution Environment name https://docs.osgi.org/reference/eenames.html
    ```
 
+## Upgrading to 6.3
+
+- **`vortex push` only uploads what changed.** On a `backend = gateway` server the push first
+  reads the server's element hashes and skips every file that already matches - a full-app push
+  that used to re-send (and journal) hundreds of identical files now sends the few that differ.
+  `--all` restores the old push-everything behaviour; `backend = soap` still pushes everything.
+- **Uploads run concurrently** - up to `--jobs N` elements at once (default 8; `-j 1` is the
+  old one-at-a-time push). A Java element's source and class still go in that order, and a
+  failed source stops that element's class from being uploaded over it.
+- **`push --name` prefers an exact match.** Previously `--name dashboard` also pushed a
+  `Dashboard` element; now the case-insensitive match only applies when nothing matches exactly.
+
 ## Upgrading to 6.0
 
 6.0 is additive - **the default behaviour is unchanged**. Every server keeps using the SOAP
@@ -163,13 +175,14 @@ For a full list of commands see `--help`.
 - `log`: View the server log.
 - `status`: Show the server status - via the agent gateway when available, otherwise the raw console `status` output.
 - `agenda`: List every scheduled action with its decoded schedule, last and next run, and whether it is overdue (read-only, gateway only).
-- `push`: Upload local design files (source, compiled classes, pages, resources) to the server without a watch session - journaled and deploy-confirmed when routed via the gateway.
+- `push`: Upload local design files (source, compiled classes, pages, resources) to the server without a watch session - journaled and deploy-confirmed when routed via the gateway. On a gateway server only files whose content differs from the server's are uploaded (compared by the server's element hashes; `--all` pushes everything), and elements upload concurrently (`--jobs N`, default 8) while each Java element's source always lands before its class. `--name` matches exactly first, case-insensitively only when nothing matches exactly.
 - `pull`: Refresh cloned applications in place via the gateway's incremental sync - only elements changed since the last sync are downloaded. Refuses to overwrite locally modified files without `--force`.
 - `render`: Render a PAGE server-side as your identity and print it (or `--out FILE`) - see a change without a browser login (gateway only).
 - `undo`: The server-side undo journal. No arguments lists journal entries; with an entry id it dry-runs a restore, and `--confirm` writes the journaled version back (gateway only).
 - `find`: Find Design Objects of cloned applications by name.
 - `grep`: Search the contents of cloned Design Objects using a Regular Expression.
 - `new`: Create new Design Objects, Applications, or Keywords. Use `--update <ID>` to update instead. Run without flags to launch an interactive wizard.
+- `keyword` (or `kw`): Read or update an application's Keyword values. `vortex keyword 9` lists them, `-n <Name>` filters to one, and `-n <Name> --values ...` updates it, printing the prior value beside the new one before asking to continue. Secret-looking names are redacted unless `--reveal` is given - see [Keyword values and secrets](#keyword-values-and-secrets).
 - `copy`: Copy a Design Object from one application to another.
 - `delete`: Delete Design Objects by ID.
 - `db`: Interact with Database Connections. Accepts `--server`/`-s` like other commands for one-off queries against another server.
@@ -179,6 +192,42 @@ For a full list of commands see `--help`.
 - `docs`: Open the Tornado Server Blackbook.
 - `execute`: Execute a command on the server.
 
+### Keyword values and secrets
+
+Keywords are an application's live configuration, and in practice they hold credentials in
+cleartext - API keys, passwords, vendor secrets, signing keys. `vortex keyword` therefore
+**redacts by default**, following the same precedent as `vortex config --show-server`:
+
+```
+vortex keyword 9                      # list every Keyword (secrets redacted)
+vortex keyword 9 -n AppVersion        # just this one
+vortex keyword 9 -n AppVersion --values 3.7.0    # update it
+vortex keyword 9 --reveal             # print secret values in full
+```
+
+- A Keyword is treated as secret when its **name** contains a marker such as `password`,
+  `passwd`, `passphrase`, `secret`, `credential`, `signature`, `apikey`, `privatekey`,
+  `keystore`, `webhook`, `connectionstring` or `mnemonic`, or when any *word* of the name
+  is one of `key`, `keys`, `pwd`, `token`, `salt`, `hash`, `private`, `auth`, `bearer`,
+  `cert`, `pem`, `jwt`, `dsn`, `otp`, `pin`, `seed` or `sig`. Names are split on
+  camelCase/snake_case/kebab-case, so `AccessKeyId` and `API_KEY` are redacted while
+  `Monkey` and `Concert` are not. The match is on the name only - a value-based heuristic
+  would leak the thing it is trying to hide on every near miss. Classification is
+  deliberately biased towards over-redaction: a false positive costs one `--reveal`, a
+  false negative prints a live credential.
+- Redacted values print as `<redacted>`, one per value, so the value *count* stays visible.
+- `--reveal` is the explicit opt-in. Without it, neither a listing nor an update's
+  before/after diff can put a live credential into your terminal scrollback, your shell
+  history or a CI log.
+
+An update always prints the prior value beside the new one and waits for `[Y/y]` on stdin
+before writing; on a `protected = true` server the server name must also be typed back
+(`--yes` does not bypass that). The write uses the gateway's keyword upsert, so it never
+inserts a duplicate KEYWORD row.
+
+Reading does **not** require the application to be cloned locally - diagnosing a bad
+configuration value should not depend on having a working copy.
+
 ### Cloning a whole group
 
 `vortex clone` takes an ID, a TemplateName, an application group, or `group/name`:
@@ -353,6 +402,8 @@ needs no change to the gateway.
 | `copy`, `new object` | webdesign `POST`/`PUT design`, `PUT design/params` | SOAP |
 | `new app` | webdesign `POST vortex` | SOAP `saveApplication` |
 | `new keyword` | gateway `keyword` (upsert) | SOAP `saveKeyword` |
+| `keyword` (read) | gateway `download` (metadata window; `GatewayDesignRead`) | **unsupported** - SOAP has no keyword read call |
+| `keyword --values` (write) | gateway `keyword` (upsert) | **unsupported** |
 | `schema`, `db --list`, `db --schema` | gateway `dictionary` (webdesign's `database`/`table`/`column` routes run server-side; `GatewayDBRead`/`GatewayDBWrite`) | SOAP SQL + `savePuakma*` |
 | `export` | webdesign `ExportPMX` action | SOAP `downloadPmx` |
 | `import` | **still SOAP** - webdesign has no import route yet | SOAP `uploadPmx` |

{vortex_cli-6.2.1 → vortex_cli-6.4.0}/README.md

@@ -64,6 +64,18 @@ While it is possible to use without it, this software has been purposefully desi
    java_environment_name = JavaSE-17 ; Java Execution Environment name https://docs.osgi.org/reference/eenames.html
    ```
 
+## Upgrading to 6.3
+
+- **`vortex push` only uploads what changed.** On a `backend = gateway` server the push first
+  reads the server's element hashes and skips every file that already matches - a full-app push
+  that used to re-send (and journal) hundreds of identical files now sends the few that differ.
+  `--all` restores the old push-everything behaviour; `backend = soap` still pushes everything.
+- **Uploads run concurrently** - up to `--jobs N` elements at once (default 8; `-j 1` is the
+  old one-at-a-time push). A Java element's source and class still go in that order, and a
+  failed source stops that element's class from being uploaded over it.
+- **`push --name` prefers an exact match.** Previously `--name dashboard` also pushed a
+  `Dashboard` element; now the case-insensitive match only applies when nothing matches exactly.
+
 ## Upgrading to 6.0
 
 6.0 is additive - **the default behaviour is unchanged**. Every server keeps using the SOAP
@@ -119,13 +131,14 @@ For a full list of commands see `--help`.
 - `log`: View the server log.
 - `status`: Show the server status - via the agent gateway when available, otherwise the raw console `status` output.
 - `agenda`: List every scheduled action with its decoded schedule, last and next run, and whether it is overdue (read-only, gateway only).
-- `push`: Upload local design files (source, compiled classes, pages, resources) to the server without a watch session - journaled and deploy-confirmed when routed via the gateway.
+- `push`: Upload local design files (source, compiled classes, pages, resources) to the server without a watch session - journaled and deploy-confirmed when routed via the gateway. On a gateway server only files whose content differs from the server's are uploaded (compared by the server's element hashes; `--all` pushes everything), and elements upload concurrently (`--jobs N`, default 8) while each Java element's source always lands before its class. `--name` matches exactly first, case-insensitively only when nothing matches exactly.
 - `pull`: Refresh cloned applications in place via the gateway's incremental sync - only elements changed since the last sync are downloaded. Refuses to overwrite locally modified files without `--force`.
 - `render`: Render a PAGE server-side as your identity and print it (or `--out FILE`) - see a change without a browser login (gateway only).
 - `undo`: The server-side undo journal. No arguments lists journal entries; with an entry id it dry-runs a restore, and `--confirm` writes the journaled version back (gateway only).
 - `find`: Find Design Objects of cloned applications by name.
 - `grep`: Search the contents of cloned Design Objects using a Regular Expression.
 - `new`: Create new Design Objects, Applications, or Keywords. Use `--update <ID>` to update instead. Run without flags to launch an interactive wizard.
+- `keyword` (or `kw`): Read or update an application's Keyword values. `vortex keyword 9` lists them, `-n <Name>` filters to one, and `-n <Name> --values ...` updates it, printing the prior value beside the new one before asking to continue. Secret-looking names are redacted unless `--reveal` is given - see [Keyword values and secrets](#keyword-values-and-secrets).
 - `copy`: Copy a Design Object from one application to another.
 - `delete`: Delete Design Objects by ID.
 - `db`: Interact with Database Connections. Accepts `--server`/`-s` like other commands for one-off queries against another server.
@@ -135,6 +148,42 @@ For a full list of commands see `--help`.
 - `docs`: Open the Tornado Server Blackbook.
 - `execute`: Execute a command on the server.
 
+### Keyword values and secrets
+
+Keywords are an application's live configuration, and in practice they hold credentials in
+cleartext - API keys, passwords, vendor secrets, signing keys. `vortex keyword` therefore
+**redacts by default**, following the same precedent as `vortex config --show-server`:
+
+```
+vortex keyword 9                      # list every Keyword (secrets redacted)
+vortex keyword 9 -n AppVersion        # just this one
+vortex keyword 9 -n AppVersion --values 3.7.0    # update it
+vortex keyword 9 --reveal             # print secret values in full
+```
+
+- A Keyword is treated as secret when its **name** contains a marker such as `password`,
+  `passwd`, `passphrase`, `secret`, `credential`, `signature`, `apikey`, `privatekey`,
+  `keystore`, `webhook`, `connectionstring` or `mnemonic`, or when any *word* of the name
+  is one of `key`, `keys`, `pwd`, `token`, `salt`, `hash`, `private`, `auth`, `bearer`,
+  `cert`, `pem`, `jwt`, `dsn`, `otp`, `pin`, `seed` or `sig`. Names are split on
+  camelCase/snake_case/kebab-case, so `AccessKeyId` and `API_KEY` are redacted while
+  `Monkey` and `Concert` are not. The match is on the name only - a value-based heuristic
+  would leak the thing it is trying to hide on every near miss. Classification is
+  deliberately biased towards over-redaction: a false positive costs one `--reveal`, a
+  false negative prints a live credential.
+- Redacted values print as `<redacted>`, one per value, so the value *count* stays visible.
+- `--reveal` is the explicit opt-in. Without it, neither a listing nor an update's
+  before/after diff can put a live credential into your terminal scrollback, your shell
+  history or a CI log.
+
+An update always prints the prior value beside the new one and waits for `[Y/y]` on stdin
+before writing; on a `protected = true` server the server name must also be typed back
+(`--yes` does not bypass that). The write uses the gateway's keyword upsert, so it never
+inserts a duplicate KEYWORD row.
+
+Reading does **not** require the application to be cloned locally - diagnosing a bad
+configuration value should not depend on having a working copy.
+
 ### Cloning a whole group
 
 `vortex clone` takes an ID, a TemplateName, an application group, or `group/name`:
@@ -309,6 +358,8 @@ needs no change to the gateway.
 | `copy`, `new object` | webdesign `POST`/`PUT design`, `PUT design/params` | SOAP |
 | `new app` | webdesign `POST vortex` | SOAP `saveApplication` |
 | `new keyword` | gateway `keyword` (upsert) | SOAP `saveKeyword` |
+| `keyword` (read) | gateway `download` (metadata window; `GatewayDesignRead`) | **unsupported** - SOAP has no keyword read call |
+| `keyword --values` (write) | gateway `keyword` (upsert) | **unsupported** |
 | `schema`, `db --list`, `db --schema` | gateway `dictionary` (webdesign's `database`/`table`/`column` routes run server-side; `GatewayDBRead`/`GatewayDBWrite`) | SOAP SQL + `savePuakma*` |
 | `export` | webdesign `ExportPMX` action | SOAP `downloadPmx` |
 | `import` | **still SOAP** - webdesign has no import route yet | SOAP `uploadPmx` |

{vortex_cli-6.2.1 → vortex_cli-6.4.0}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "vortex_cli"
-version = "6.2.1"
+version = "6.4.0"
 description = "Vortex CLI"
 requires-python = ">=3.10"
 readme = { file = "README.md", content-type = "text/markdown" }

{vortex_cli-6.2.1 → vortex_cli-6.4.0}/vortex/cli.py

@@ -14,6 +14,7 @@ from typing import NamedTuple
 from vortex.commands.db import DEFAULT_LIMIT_N_RESULTS
 from vortex.commands.db import MAX_LIMIT_N_RESULTS
 from vortex.commands.db import MIN_LIMIT_N_RESULTS
+from vortex.commands.push import DEFAULT_JOBS as DEFAULT_PUSH_JOBS
 from vortex.models import DesignType
 from vortex.models import PuakmaApplication
 
@@ -197,6 +198,7 @@ def validate_args(
     new_parser: ArgumentParser,
     clone_parser: ArgumentParser,
     db_parser: ArgumentParser,
+    keyword_parser: ArgumentParser,
 ) -> None:
     if args.command == "new":
         msg = None
@@ -264,6 +266,11 @@ def validate_args(
                 clone_parser.error(
                     f"--group expects group names, not {', '.join(not_groups)}"
                 )
+    elif args.command in ("keyword", "kw"):
+        # A write needs a target: '--values' with no '--name' would
+        # otherwise be a silent no-op, or worse, ambiguous
+        if args.values is not None and not args.name:
+            keyword_parser.error("--values requires --name")
     elif args.command == "db" and args.sql is not None:
         try:
             args.database = int(args.database)
@@ -718,7 +725,31 @@ def add_push_parser(command_parser: _SubParsersAction[ArgumentParser]) -> None:
         "-n",
         dest="name_filter",
         default=None,
-        help="Only push the design element with this name",
+        help=(
+            "Only push the design element with this name (an exact match "
+            "wins; case-insensitive only when nothing matches exactly)"
+        ),
+    )
+    push_parser.add_argument(
+        "--all",
+        "-a",
+        action="store_true",
+        help=(
+            "Push every local file, including ones whose content already "
+            "matches the server. By default (gateway backend) unchanged "
+            "files are skipped using the server's element hashes"
+        ),
+    )
+    push_parser.add_argument(
+        "--jobs",
+        "-j",
+        type=int,
+        default=DEFAULT_PUSH_JOBS,
+        metavar="N",
+        help=(
+            "Maximum elements uploaded concurrently "
+            f"(default {DEFAULT_PUSH_JOBS}; 1 uploads one at a time)"
+        ),
     )
     _add_server_option(push_parser)
 
@@ -981,6 +1012,58 @@ def add_new_parser(
     return new_parser
 
 
+def add_keyword_parser(
+    command_parser: _SubParsersAction[ArgumentParser],
+) -> ArgumentParser:
+    keyword_parser = command_parser.add_parser(
+        "keyword",
+        aliases=("kw",),
+        help=(
+            "Read or update an application's Keyword values. With no "
+            "--values it lists them; with --values it updates one, "
+            "showing the prior value first (gateway only)"
+        ),
+    )
+    keyword_parser.add_argument(
+        "app_id",
+        metavar="APP_ID",
+        type=int,
+        help="The application id whose Keywords to read or update",
+    )
+    keyword_parser.add_argument(
+        "--name",
+        "-n",
+        help=(
+            "Only this Keyword (exact, case-insensitive). Required when "
+            "--values is given"
+        ),
+    )
+    keyword_parser.add_argument(
+        "--values",
+        nargs="*",
+        default=None,
+        metavar="VALUE",
+        help=(
+            "Set --name to these value(s), replacing what is there. Pass "
+            "with no values to set it empty. Requires --name"
+        ),
+    )
+    keyword_parser.add_argument(
+        "--reveal",
+        action="store_true",
+        help=(
+            "Print secret-looking Keyword values in full. Values of "
+            "Keywords whose NAME looks like a credential (password, "
+            "secret, key, token, auth, cert, hash, salt, pin, otp, "
+            "webhook, connection string and similar) are redacted by "
+            "default so a plain listing cannot leak a live credential "
+            "into the terminal, shell history or a CI log"
+        ),
+    )
+    _add_server_option(keyword_parser)
+    return keyword_parser
+
+
 def add_copy_parser(command_parser: _SubParsersAction[ArgumentParser]) -> None:
     copy_parser = command_parser.add_parser(
         "copy", help="Copy a Design Object from one application to another"

vortex_cli-6.4.0/vortex/commands/keyword.py

@@ -0,0 +1,309 @@
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+
+import tabulate
+
+from vortex.colour import Colour
+from vortex.gateway import GatewayClient
+from vortex.gateway import GatewayRefused
+from vortex.gateway import GatewayUnavailable
+from vortex.gateway import refusal_detail
+from vortex.models import PuakmaServer
+from vortex.util import confirm_protected
+
+logger = logging.getLogger("vortex")
+
+_REFUSAL_HELP = {
+    "FORBIDDEN": (
+        "this identity does not hold the required gateway role on this "
+        "server (listing needs GatewayDesignRead; setting a value needs "
+        "GatewayDesignWrite - or Admin)"
+    ),
+    "NOT_FOUND": "no application with that id on this server",
+}
+
+# Keyword values are an application's live configuration and routinely
+# hold credentials in cleartext (API keys, passwords, vendor secrets,
+# signing keys). Printing them by default would put them in the terminal
+# scrollback, the shell history and any CI log that captured the run, so
+# a Keyword whose NAME matches this is redacted unless --reveal is given.
+# This follows the gateway's own 'server_config' precedent, which
+# redacts the server's secrets before they ever reach the wire.
+# Long, unambiguous markers - matched anywhere in the name.
+SECRET_SUBSTRINGS = (
+    "password",
+    "passwd",
+    "passphrase",
+    "secret",
+    "credential",
+    "signature",
+    "mnemonic",
+    "keystore",
+    "truststore",
+    "keyphrase",
+    "connectionstring",
+    "connstring",
+    "webhook",
+    "apikey",
+    "privatekey",
+)
+
+# Short/ambiguous markers - matched only as a whole word of the name, so
+# 'Monkey' and 'Spinner' are not mistaken for 'key' and 'pin'.
+SECRET_WORDS = frozenset(
+    {
+        "pwd",
+        "token",
+        "tokens",
+        "salt",
+        "hash",
+        "key",
+        "keys",
+        "private",
+        "bearer",
+        "auth",
+        "authorization",
+        "authentication",
+        "cert",
+        "certificate",
+        "pem",
+        "pfx",
+        "jwt",
+        "dsn",
+        "otp",
+        "pin",
+        "seed",
+        "sig",
+    }
+)
+
+# camelCase / PascalCase / snake_case / kebab-case / ALLCAPS -> words
+_WORD_PATTERN = re.compile(r"[A-Z]+(?![a-z])|[A-Z][a-z]*|[a-z]+|\d+")
+
+REDACTED = "<redacted>"
+
+
+def name_words(name: str) -> list[str]:
+    """The name split into lowercased words, however it is cased."""
+    return [w.casefold() for w in _WORD_PATTERN.findall(name)]
+
+
+def is_secret_name(name: str) -> bool:
+    """
+    True when a Keyword name looks like it holds a credential. Matched
+    on the NAME only - a value-based heuristic would leak the very thing
+    it is trying to hide on every near miss.
+
+    Deliberately biased towards over-redaction: a false positive costs
+    one '--reveal', a false negative prints a live credential into the
+    terminal scrollback, the shell history and any CI log.
+    """
+    folded = name.casefold()
+    if any(marker in folded for marker in SECRET_SUBSTRINGS):
+        return True
+    return any(word in SECRET_WORDS for word in name_words(name))
+
+
+def redact_values(name: str, values: list[str], reveal: bool) -> list[str]:
+    """
+    What to display for a Keyword: the real values, or one <redacted>
+    marker per value (the COUNT is safe and useful; the content is not).
+    """
+    if reveal or not is_secret_name(name):
+        return list(values)
+    return [REDACTED for _ in values]
+
+
+def _format_values(values: list[str]) -> str:
+    return " | ".join(values)
+
+
+def _app_label(app: dict[str, Any], app_id: int) -> str:
+    group = str(app.get("group") or "")
+    name = str(app.get("name") or "")
+    label = f"{group}/{name}".strip("/")
+    return f"{label} [{app_id}]" if label else f"[{app_id}]"
+
+
+def _fetch(
+    client: GatewayClient, app_id: int, name: str | None
+) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+    app, rows = client.get_keywords(app_id)
+    if name is not None:
+        needle = name.casefold()
+        rows = [r for r in rows if str(r.get("name", "")).casefold() == needle]
+    return app, rows
+
+
+def _client_or_error(server: PuakmaServer) -> GatewayClient | None:
+    """
+    The gateway client, or None with the reason already logged. Keywords
+    are gateway-only here: the legacy SOAP designer has no keyword READ
+    call at all, which is exactly why reading one was impossible before
+    this command existed.
+    """
+    try:
+        client = server.negotiate_gateway()
+    except GatewayUnavailable as e:
+        logger.error(e)
+        return None
+    if client is None:
+        logger.error(
+            "'vortex keyword' needs the gateway backend "
+            f"(set 'backend = gateway' for '{server.name}') - the legacy "
+            "SOAP designer has no keyword read call"
+        )
+        return None
+    return client
+
+
+def keyword(
+    server: PuakmaServer,
+    app_id: int,
+    *,
+    name: str | None = None,
+    values: list[str] | None = None,
+    reveal: bool = False,
+    yes: bool = False,
+) -> int:
+    """
+    Read or update an application's Keyword values.
+
+    With no --values this LISTS Keywords (all of them, or just --name).
+    With --values it UPDATES --name, showing the prior value beside the
+    new one before writing, so the change is visible rather than blind;
+    the write goes through the gateway's keyword upsert, which never
+    inserts a duplicate row.
+
+    The application does NOT need to be cloned locally - diagnosing a
+    bad configuration value must not require a working copy.
+    """
+    if values is not None:
+        if not name:
+            # argparse rejects this first; belt-and-braces so a direct
+            # call cannot upsert a nameless Keyword
+            logger.error("--values requires --name")
+            return 1
+        return _set_keyword(server, app_id, name, values, reveal=reveal, yes=yes)
+    return _list_keywords(server, app_id, name, reveal=reveal)
+
+
+def _list_keywords(
+    server: PuakmaServer,
+    app_id: int,
+    name: str | None,
+    *,
+    reveal: bool,
+) -> int:
+    with server as s:
+        client = _client_or_error(s)
+        if client is None:
+            return 1
+        try:
+            app, rows = _fetch(client, app_id, name)
+        except GatewayRefused as e:
+            logger.error(refusal_detail(e, _REFUSAL_HELP))
+            return 1
+        except GatewayUnavailable as e:
+            logger.error(e)
+            return 1
+
+    label = _app_label(app, app_id)
+    if not rows:
+        if name:
+            logger.error(f"No Keyword named '{name}' in {label}")
+            return 1
+        print(f"[{server.name}] {label} has no Keywords.")
+        return 0
+
+    redacted = 0
+    table = []
+    for row in sorted(rows, key=lambda r: str(r.get("name", "")).casefold()):
+        kw_name = str(row.get("name") or "")
+        raw = [str(v) for v in (row.get("values") or [])]
+        shown = redact_values(kw_name, raw, reveal)
+        if shown != raw:
+            redacted += 1
+        flag = "DUPLICATE" if row.get("duplicate") else ""
+        table.append([row.get("id"), kw_name, _format_values(shown), flag])
+
+    header = f"[{server.name}] {label} - {len(table)} Keyword(s)"
+    if redacted:
+        header += f", {redacted} redacted (--reveal to show)"
+    print(header)
+    print(tabulate.tabulate(table, headers=["ID", "Name", "Values", ""]))
+    return 0
+
+
+def _set_keyword(
+    server: PuakmaServer,
+    app_id: int,
+    name: str,
+    values: list[str],
+    *,
+    reveal: bool,
+    yes: bool,
+) -> int:
+    with server as s:
+        client = _client_or_error(s)
+        if client is None:
+            return 1
+
+        try:
+            app, existing = _fetch(client, app_id, name)
+        except GatewayRefused as e:
+            logger.error(refusal_detail(e, _REFUSAL_HELP))
+            return 1
+        except GatewayUnavailable as e:
+            logger.error(e)
+            return 1
+
+        prior = (
+            [str(v) for v in (existing[0].get("values") or [])] if existing else None
+        )
+
+        # Showing the prior value IS the feature: a blind write is how a
+        # bad Keyword value becomes an outage nobody can diagnose. A
+        # secret-looking name stays redacted even in the diff.
+        label = _app_label(app, app_id)
+        verb = (
+            Colour.colour("UPDATED", Colour.YELLOW)
+            if existing
+            else Colour.colour("CREATED", Colour.GREEN)
+        )
+        print(f"Keyword '{name}' in {label} will be {verb}:\n")
+        if prior is None:
+            print("  from: (does not exist)")
+        else:
+            print(f"  from: {_format_values(redact_values(name, prior, reveal))}")
+        print(f"    to: {_format_values(redact_values(name, values, reveal))}")
+        if prior is not None and prior == values:
+            print("\nThe Keyword already has this value; nothing to do.")
+            return 0
+
+        if not yes and input("\n[Y/y] to continue:") not in ["Y", "y"]:
+            logger.error("Operation Cancelled")
+            return 1
+        # Deliberately NOT bypassed by --yes: on a protected server the
+        # name must still be typed back
+        if not confirm_protected(s, f"update the Keyword '{name}'"):
+            return 1
+
+        try:
+            reply = client.keyword_upsert(app_id, name, values)
+        except GatewayRefused as e:
+            logger.error(refusal_detail(e, _REFUSAL_HELP))
+            return 1
+        except GatewayUnavailable as e:
+            logger.error(e)
+            return 1
+
+    dupes = int(reply.get("duplicatesConsolidated") or 0)
+    extra = f" ({dupes} duplicate row(s) consolidated)" if dupes else ""
+    logger.info(
+        f"Upserted Keyword '{name}' [{reply.get('keywordId')}] via gateway{extra}"
+    )
+    return 0