cpflow 5.2.0 → 5.3.0

data/lib/command/apply_template.rb

@@ -9,7 +9,8 @@ module Command
       app_option(required: true),
       location_option,
       skip_confirm_option,
-      add_app_identity_option
+      add_app_identity_option,
+      preserve_existing_runtime_option
     ].freeze
     DESCRIPTION = "Applies application-specific configs from templates"
     LONG_DESCRIPTION = <<~DESC
@@ -17,6 +18,8 @@ module Command
       - Publishes (creates or updates) those at Control Plane infrastructure
       - Picks templates from the `.controlplane/templates` directory
       - Templates are ordinary Control Plane templates but with variable preprocessing
+      - Use `--preserve-existing-runtime` to retain each workload container's configured app image, even when the workload is unready, and skip existing secret resources entirely while applying other template changes
+      - Missing or invalid workload images use only an unambiguous app image from ready workloads; refresh fails before applying templates when no safe fallback exists
 
       **Preprocessed template variables:**
 
@@ -58,6 +61,7 @@ module Command
       @skipped_templates = []
 
       templates = @template_parser.parse(@names_to_filenames.values)
+      templates = preserve_existing_runtime(templates) if config.options[:preserve_existing_runtime]
       pending_templates = confirm_templates(templates)
       add_app_identity_template(pending_templates) if config.options[:add_app_identity]
       pending_templates.each do |template|
@@ -117,7 +121,7 @@ module Command
     end
 
     def confirm_workload(template) # rubocop:disable Naming/PredicateMethod
-      workload = cp.fetch_workload(template["name"])
+      workload = fetch_workload(template["name"])
       return true unless workload
 
       confirmed = confirm_apply("Workload '#{template['name']}' already exists, do you want to re-create it?")
@@ -146,6 +150,104 @@ module Command
       pending_templates
     end
 
+    def preserve_existing_runtime(templates)
+      cache_existing_workloads(templates)
+      ready_fallback_image = unambiguous_ready_app_image
+
+      templates.filter_map do |template|
+        if template["kind"] == "secret" && cp.fetch_secret(template["name"])
+          report_skipped(template)
+          next
+        end
+
+        preserve_workload_images(template, ready_fallback_image) if template["kind"] == "workload"
+        template
+      end
+    end
+
+    def cache_existing_workloads(templates)
+      template_names = templates.filter_map { |template| template["name"] if template["kind"] == "workload" }
+      workloads = cp.fetch_workloads
+      cp.fetch_gvc! unless workloads
+      @existing_workloads = Array(workloads.fetch("items")).to_h do |workload|
+        [workload.fetch("name"), workload]
+      end
+      template_names.each { |name| @existing_workloads[name] = nil unless @existing_workloads.key?(name) }
+    end
+
+    def fetch_workload(name)
+      return @existing_workloads[name] if @existing_workloads&.key?(name)
+
+      cp.fetch_workload(name)
+    end
+
+    def unambiguous_ready_app_image
+      app_images = ready_existing_app_workloads.flat_map do |workload|
+        Array(workload.dig("spec", "containers")).filter_map do |container|
+          container["image"] if deployable_app_image?(container["image"])
+        end
+      end
+      image_prefix = "/org/#{config.org}/image/"
+      canonical_images = app_images.map { |image| image.delete_prefix(image_prefix) }
+      app_images.first if canonical_images.uniq.one?
+    end
+
+    def ready_existing_app_workloads
+      @existing_workloads.values.compact.filter_map do |workload|
+        next unless Array(workload.dig("spec", "containers")).any? do |container|
+          deployable_app_image?(container["image"])
+        end
+
+        workload = workload_with_readiness(workload)
+        workload if workload_ready?(workload)
+      end
+    end
+
+    def preserve_workload_images(template, ready_fallback_image) # rubocop:disable Metrics/MethodLength
+      existing_workload = fetch_workload(template["name"])
+      existing_containers = Array(existing_workload&.dig("spec", "containers"))
+                            .to_h { |container| [container["name"], container] }
+
+      Array(template.dig("spec", "containers")).each do |container|
+        next unless app_image?(container["image"])
+
+        existing_image = existing_containers.dig(container["name"], "image")
+        preserved_image = preserved_image(existing_image, ready_fallback_image)
+        unless preserved_image
+          raise "Cannot safely refresh app image for workload '#{template['name']}' " \
+                "without a valid existing workload image or an unambiguous ready fallback image."
+        end
+
+        container["image"] = preserved_image
+      end
+    end
+
+    def preserved_image(existing_image, ready_fallback_image)
+      return existing_image if deployable_app_image?(existing_image)
+
+      ready_fallback_image
+    end
+
+    def workload_ready?(workload)
+      workload&.dig("status", "readyLatest") == true
+    end
+
+    def workload_with_readiness(workload)
+      return workload unless workload.dig("status", "readyLatest").nil?
+
+      cp.fetch_workload_with_status(workload.fetch("name")) || workload
+    end
+
+    def app_image?(image)
+      image.to_s.match?(
+        %r{\A(?:/org/#{Regexp.escape(config.org)}/image/)?#{Regexp.escape(config.app)}[:@]}
+      )
+    end
+
+    def deployable_app_image?(image)
+      app_image?(image) && !image.to_s.end_with?(Controlplane::NO_IMAGE_AVAILABLE)
+    end
+
     def add_app_identity_template(templates)
       app_template_index = templates.index { |template| template["name"] == config.app }
       app_identity_template_index = templates.index { |template| template["name"] == config.identity }

data/lib/command/base.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "shellwords"
 require_relative "../core/helpers"
 
 module Command
@@ -11,6 +12,7 @@ module Command
     VALIDATIONS_WITHOUT_ADDITIONAL_OPTIONS = %w[config].freeze
     VALIDATIONS_WITH_ADDITIONAL_OPTIONS = %w[templates].freeze
     ALL_VALIDATIONS = VALIDATIONS_WITHOUT_ADDITIONAL_OPTIONS + VALIDATIONS_WITH_ADDITIONAL_OPTIONS
+    GENERATED_POSTGRES_PASSWORD_PLACEHOLDER = "the_password"
 
     # Used to call the command (`cpflow SUBCOMMAND_NAME NAME`)
     SUBCOMMAND_NAME = nil
@@ -459,6 +461,28 @@ module Command
       }
     end
 
+    def self.refresh_templates_option(required: false)
+      {
+        name: :refresh_templates,
+        params: {
+          desc: "Refreshes configured templates for an existing app without running post-creation hooks",
+          type: :boolean,
+          required: required
+        }
+      }
+    end
+
+    def self.preserve_existing_runtime_option(required: false)
+      {
+        name: :preserve_existing_runtime,
+        params: {
+          desc: "Preserves deployed app images and skips existing secret resources entirely while applying templates",
+          type: :boolean,
+          required: required
+        }
+      }
+    end
+
     def self.skip_pre_deletion_hook_option(required: false)
       {
         name: :skip_pre_deletion_hook,
@@ -528,10 +552,12 @@ module Command
       end
     end
 
-    # NOTE: use simplified variant atm, as shelljoin do different escaping
-    # TODO: most probably need better logic for escaping various quotes
     def args_join(args)
-      args.join(" ")
+      # A single CLI argument is an intentional shell program (for example, an env assignment or pipeline).
+      # Multiple CLI arguments are argv elements and must be escaped before entering the remote shell script.
+      return args.first if args.size == 1
+
+      Shellwords.join(args)
     end
 
     def progress
@@ -619,9 +645,32 @@ module Command
       raise shared_secret_policy_missing_message(grant) if policy.nil?
 
       ensure_shared_secret_policy_targets_secret!(grant, policy)
+      warn_if_shared_secret_uses_generated_password_placeholder(grant)
       policy
     end
 
+    def warn_if_shared_secret_uses_generated_password_placeholder(grant)
+      secret_name = grant.fetch(:secret_name)
+      secret = cp.reveal_secret(secret_name)
+      return unless secret&.dig("data", "password") == GENERATED_POSTGRES_PASSWORD_PLACEHOLDER
+
+      Shell.warn(
+        "Shared secret grant '#{grant.fetch(:name)}' targets secret '#{secret_name}', whose password " \
+        "is still the generated placeholder. Review apps will fail authentication until it is replaced."
+      )
+    # This is a best-effort warning. API, transport, and response-shape failures
+    # must not turn an optional diagnostic into a deployment blocker.
+    rescue StandardError
+      debug_shared_secret_placeholder_check_failure(secret_name)
+    end
+
+    def debug_shared_secret_placeholder_check_failure(secret_name)
+      Shell.debug(
+        "WARN",
+        "Could not inspect shared secret '#{secret_name}'; continuing without the optional placeholder diagnostic."
+      )
+    end
+
     def bind_shared_secret_policy_grant(grant, policy)
       policy_name = grant.fetch(:policy_name)
       return if identity_bound_to_policy_with_reveal?(policy)

data/lib/command/deploy_image.rb

@@ -107,17 +107,25 @@ module Command
       @requested_workload_names ||= Array(config.options[:workload]).map(&:to_s).uniq
     end
 
+    def app_image?(image)
+      image.to_s.match?(
+        %r{\A(?:/org/#{Regexp.escape(config.org)}/image/)?#{Regexp.escape(config.app)}[:@]}
+      )
+    end
+
     def deploy_image_to_workloads(image, workload_data_by_name) # rubocop:disable Metrics/MethodLength
       deployed_endpoints = {}
 
       workload_data_by_name.each do |workload, workload_data|
         workload_data.dig("spec", "containers").each do |container|
-          next unless container["image"].match?(%r{^/org/#{config.org}/image/#{config.app}[:@]})
+          next unless app_image?(container["image"])
 
           container_name = container["name"]
           step("Deploying image '#{image}' for workload '#{workload}'") do
             cp.workload_set_image_ref(workload, container: container_name, image: image)
             deployed_endpoints[workload] = endpoint_for_workload(workload_data)
+            # A missing public endpoint is valid; the image update still completed successfully.
+            true
           end
           # Deploy the first matching app-image container per workload; CPLN workloads
           # are expected to have a single container that runs the app image.
@@ -131,7 +139,7 @@ module Command
     def print_deployed_endpoints(deployed_endpoints)
       progress.puts("\nDeployed endpoints:")
       deployed_endpoints.each do |workload, endpoint|
-        progress.puts("  - #{workload}: #{endpoint}")
+        progress.puts("  - #{workload}: #{endpoint || '(no public endpoint)'}")
       end
     end
 
@@ -172,9 +180,15 @@ module Command
 
     def endpoint_for_workload(workload_data)
       endpoint = workload_data.dig("status", "endpoint")
+      return fallback_endpoint_for_workload(workload_data) unless endpoint
+
       Resolv.getaddress(endpoint.split("/").last)
       endpoint
     rescue Resolv::ResolvError
+      fallback_endpoint_for_workload(workload_data)
+    end
+
+    def fallback_endpoint_for_workload(workload_data)
       deployments = cp.fetch_workload_deployments(workload_data["name"])
       deployments.dig("items", 0, "status", "endpoint")
     end

data/lib/command/run.rb

@@ -47,8 +47,21 @@ module Command
         and also overridden per job through `--cpu` and `--memory`)
       - By default, the job is stopped if it takes longer than 6 hours to finish
         (can be configured though `runner_job_timeout` in `controlplane.yml`)
+      - Waiting for a runner replica is limited to the smaller of `runner_job_timeout` and 1000 seconds.
+        A terminal cron status fails immediately, and reaching the observation deadline reports the last safe status
       - Non-interactive jobs return the Control Plane cron job status even when the job finishes before
         Control Plane exposes a runner replica to attach logs to
+      - Injects `CPFLOW_GVC_ID` and `CPFLOW_GVC_CREATED` into the job, exposing the app's immutable GVC
+        identity, so that a command such as a release script can tell which GVC incarnation it is running in.
+        These change when a GVC is deleted and recreated under the same name, and only then, unlike
+        `CPLN_GVC_ALIAS`, which is also embedded in mutable derived values such as the app domain and so
+        cannot be attributed to recreation alone
+      - `CPFLOW_GVC_CREATED` is the GVC's creation timestamp as returned by the Control Plane API and passed
+        through unmodified, currently an ISO 8601 UTC timestamp with millisecond precision and a `Z` suffix
+        (e.g. `2026-08-28T00:54:48.648Z`)
+      - Both variables are always set, and are empty when the GVC cannot be read, so that a consumer can
+        fail closed. They are never omitted, because the runner inherits the original workload's
+        environment and an omitted variable could otherwise expose a stale inherited value
     DESC
     EXAMPLES = <<~EX.freeze
       ```sh
@@ -69,7 +82,8 @@ module Command
       # - stop the job
       cpflow run -a $APP_NAME --detached -- rails db:migrate
 
-      # The command needs to be quoted if setting an env variable or passing args.
+      # Quote the whole command to intentionally opt into shell syntax such as an env assignment.
+      # Separately supplied command arguments are passed literally.
       cpflow run -a $APP_NAME -- 'SOME_ENV_VAR=some_value rails db:migrate'
 
       # Uses a different image (which may not be promoted yet).
@@ -95,6 +109,9 @@ module Command
     DEFAULT_JOB_MEMORY = "2Gi"
     DEFAULT_JOB_TIMEOUT = 21_600 # 6 hours
     DEFAULT_JOB_HISTORY_LIMIT = 10
+    MAX_REPLICA_OBSERVATION_SECONDS = 1_000
+    REPLICA_OBSERVATION_POLL_INTERVAL_SECONDS = 1
+    NORMALIZED_JOB_STATUS_PATTERN = /\A[a-z][a-z0-9_-]{0,31}\z/
     MAGIC_END = "---cpflow run command finished---"
 
     attr_reader :interactive, :detached, :location, :original_workload, :runner_workload,
@@ -268,27 +285,80 @@ module Command
     end
 
     def wait_for_replica_for_job
-      step("Waiting for replica to start, which runs job '#{job}'", retry_on_failure: true) do
-        result = cp.fetch_workload_replicas(runner_workload, location: location)
-        @replica = result&.dig("items")&.find { |item| item.include?(job) }
+      observation_limit = [job_timeout, MAX_REPLICA_OBSERVATION_SECONDS].min
+      observation_deadline = monotonic_time + observation_limit
 
-        replica || completed_job_before_replica? || false
+      step("Waiting for runner replica to start") do
+        observe_replica_until(observation_deadline, observation_limit)
       end
     end
 
-    def completed_job_before_replica?
-      case current_job_status
+    def observe_replica_until(observation_deadline, observation_limit)
+      last_status = nil
+
+      loop do
+        ensure_before_replica_observation_deadline!(observation_deadline, observation_limit, last_status)
+
+        @replica = replica_for_job
+        return replica if replica
+
+        ensure_before_replica_observation_deadline!(observation_deadline, observation_limit, last_status)
+
+        last_status = current_job_status
+        return true if completed_job_before_replica?(last_status)
+
+        sleep_before_replica_observation_retry(observation_deadline, observation_limit, last_status)
+      end
+    end
+
+    def ensure_before_replica_observation_deadline!(observation_deadline, observation_limit, status)
+      return if monotonic_time < observation_deadline
+
+      raise replica_observation_timeout_message(observation_limit, status)
+    end
+
+    def replica_for_job
+      result = cp.fetch_workload_replicas(runner_workload, location: location)
+      result&.dig("items")&.find { |item| item.include?(job) }
+    end
+
+    def sleep_before_replica_observation_retry(observation_deadline, observation_limit, status)
+      progress.print(".")
+      remaining = observation_deadline - monotonic_time
+      raise replica_observation_timeout_message(observation_limit, status) unless remaining.positive?
+
+      Kernel.sleep([REPLICA_OBSERVATION_POLL_INTERVAL_SECONDS, remaining].min)
+    end
+
+    # Returns true for success, false while pending, and raises for a terminal non-success status.
+    def completed_job_before_replica?(status)
+      case status
       when "successful"
         @job_completed_before_replica_exit_status = ExitCode::SUCCESS
         true
       when nil, "active", "pending"
         false
       else
-        @job_completed_before_replica_exit_status = ExitCode::ERROR_DEFAULT
-        true
+        raise "Runner job ended before a replica was observed (status: #{normalized_job_status(status)})."
       end
     end
 
+    def normalized_job_status(status)
+      return "unavailable" if status.nil?
+
+      token = status.to_s.downcase
+      token.match?(NORMALIZED_JOB_STATUS_PATTERN) ? token : "unknown"
+    end
+
+    def replica_observation_timeout_message(observation_limit, status)
+      "Runner replica was not observed before the observation limit: #{format('%g', observation_limit)} seconds " \
+        "(status: #{normalized_job_status(status)})."
+    end
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
     def run_interactive
       progress.puts("Connecting to replica '#{replica}'...\n\n")
       # workload_exec returns false on non-zero exit, nil when signal-killed (e.g. Ctrl-C).
@@ -389,11 +459,12 @@ module Command
       job_start_hash["args"].push("-c")
       job_start_hash["env"] ||= []
       job_start_hash["env"].push({ "name" => "CPFLOW_RUNNER_SCRIPT", "value" => runner_script })
+      job_start_hash["env"].concat(gvc_identity_env_vars)
       if interactive
         job_start_hash["env"].push({ "name" => "CPFLOW_MONITORING_SCRIPT", "value" => interactive_monitoring_script })
 
         job_start_hash["args"].push('eval "$CPFLOW_MONITORING_SCRIPT"')
-        @command = %(bash -c 'eval "$CPFLOW_RUNNER_SCRIPT"')
+        @command = ["bash", "-c", 'eval "$CPFLOW_RUNNER_SCRIPT"']
       else
         job_start_hash["args"].push('eval "$CPFLOW_RUNNER_SCRIPT"')
       end
@@ -413,6 +484,58 @@ module Command
       job_start_hash.to_yaml
     end
 
+    # Exposes the GVC's immutable identity to the job. cpflow authenticates client-side with the
+    # operator/CI credentials, so reading the GVC here adds no GVC-view binding to the app's workload
+    # identity and leaves nothing behind for the delete lifecycle to clean up.
+    #
+    # Both variables are always emitted, empty when unknown, rather than omitted. `update_runner_workload`
+    # copies the original workload's env wholesale into the runner, so omitting them would let a value
+    # inherited from the workload survive a failed read and be mistaken for a live identity. Emitting an
+    # explicit empty value is the only way a consumer can actually fail closed.
+    def gvc_identity_env_vars
+      gvc_data = fetch_gvc_for_identity
+      gvc_id = (gvc_data && gvc_data["id"]).to_s
+      # Gated on the id so a fresh id can never be paired with an inherited timestamp.
+      gvc_created = gvc_id.empty? ? "" : gvc_data["created"].to_s
+
+      [
+        { "name" => "CPFLOW_GVC_ID", "value" => gvc_id },
+        { "name" => "CPFLOW_GVC_CREATED", "value" => gvc_created }
+      ]
+    end
+
+    # The identity is an optional enrichment, so failing to read it must never stop the job, and the
+    # variables are still emitted (empty) rather than dropped.
+    # Two reasons the rescue is deliberately broad rather than a narrow class list:
+    #
+    # 1. Availability. `cpflow run` is also the release-phase mechanism for `deploy-image`, `setup-app`,
+    #    and `delete`, so a transient error on the GVC endpoint would otherwise fail a deploy over a
+    #    variable the command does not need.
+    # 2. Taxonomy. `handle_response` raises a bare `RuntimeError` for 401 and 5xx responses, so any
+    #    "narrow" list that actually covered the real failures would have to include `RuntimeError`.
+    #
+    # `MaintenanceMode#domain_workload_update_confirmed?` rescues `StandardError` against this same API
+    # client for the same reason. The rescued body is a single external call, so a bug in this file's own
+    # logic still raises.
+    def fetch_gvc_for_identity
+      cp.fetch_gvc
+    rescue StandardError => e
+      # Deliberately `Shell.warn` rather than a `step`. `step_finish` prints a red "failed!" banner
+      # whenever its block is falsy, regardless of `abort_on_error`, so routing an optional lookup
+      # through it would show a failure on every deploy for anyone whose token omits `gvc` view -- for
+      # a read that stops nothing and leaves the exit code at 0.
+      Shell.warn(gvc_identity_error_message(e))
+      nil
+    end
+
+    # A 403 here is normally a missing `view` grant on kind `gvc`, but `ForbiddenError` renders any
+    # `/org/...` URL as "Double check your org", which sends the operator after the wrong thing.
+    def gvc_identity_error_message(error)
+      "Continuing without the GVC identity, so CPFLOW_GVC_ID and CPFLOW_GVC_CREATED are set to empty " \
+        "strings. A permission failure here usually means the token lacks `view` on kind `gvc` for this " \
+        "app, even when the message below mentions the org. #{error.message}"
+    end
+
     def interactive_monitoring_script
       <<~SCRIPT
         primary_pid=""

data/lib/command/setup_app.rb

@@ -1,13 +1,14 @@
 # frozen_string_literal: true
 
 module Command
-  class SetupApp < Base
+  class SetupApp < Base # rubocop:disable Metrics/ClassLength
     NAME = "setup-app"
     OPTIONS = [
       app_option(required: true),
       skip_secret_access_binding_option,
       skip_secrets_setup_option,
-      skip_post_creation_hook_option
+      skip_post_creation_hook_option,
+      refresh_templates_option
     ].freeze
     DESCRIPTION = "Creates an app and all its workloads"
     LONG_DESCRIPTION = <<~DESC
@@ -23,18 +24,21 @@ module Command
       - Runs a post-creation hook after the app is created if `hooks.post_creation` is specified in the `.controlplane/controlplane.yml` file
       - If the hook exits with a non-zero code, the command will stop executing and also exit with a non-zero code
       - Use `--skip-post-creation-hook` to skip the hook if specified in `controlplane.yml`
+      - Use `--refresh-templates` to apply configured templates noninteractively to an existing app while preserving each workload's configured app image even when workloads are unready or use mixed image versions, skipping existing secret resources entirely, repairing secrets access bindings, and skipping the post-creation hook
     DESC
     VALIDATIONS = %w[config templates].freeze
 
-    def call # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength
+    def call # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
       templates = config[:setup_app_templates]
+      refresh_templates = config.options[:refresh_templates]
 
       app = cp.fetch_gvc
-      if app
+      if app && !refresh_templates
         raise "App '#{config.app}' already exists. If you want to update this app, " \
               "either run 'cpflow delete -a #{config.app}' and then re-run this command, " \
               "or run 'cpflow apply-template #{templates.join(' ')} -a #{config.app}'."
       end
+      raise "App '#{config.app}' does not exist, so its templates cannot be refreshed." if !app && refresh_templates
 
       skip_secrets_setup = skip_secrets_setup?
 
@@ -45,11 +49,12 @@ module Command
 
       args = []
       args.push("--add-app-identity") unless skip_secrets_setup
+      args.push("--yes", "--preserve-existing-runtime") if refresh_templates
       run_cpflow_command("apply-template", *templates, "-a", config.app, *args)
 
       bind_identity_to_policy unless skip_secrets_setup
       bind_shared_secret_policy_grants(shared_secret_policy_grant_pairs) unless skip_secrets_setup
-      run_post_creation_hook unless config.options[:skip_post_creation_hook]
+      run_post_creation_hook unless refresh_templates || config.options[:skip_post_creation_hook]
     end
 
     private

data/lib/core/controlplane.rb

@@ -177,6 +177,28 @@ class Controlplane # rubocop:disable Metrics/ClassLength
     api.workload_get(workload: workload, gvc: gvc, org: org)
   end
 
+  def fetch_workload_with_status(workload)
+    result = workload_status_result(workload)
+
+    unless result[:success]
+      Shell.warn("Failed to fetch status for '#{workload}': #{result[:error_output].to_s.strip}")
+      return
+    end
+
+    JSON.parse(result[:output])
+  rescue JSON::ParserError => e
+    Shell.warn("Failed to parse status for '#{workload}': #{e.message}")
+    nil
+  end
+
+  def workload_status_result(workload)
+    # The direct API response omits computed fields such as status.readyLatest.
+    args = ["cpln", "workload", "get", workload, "--gvc", gvc, "--org", org, "-o", "json"]
+    Shell.debug("CMD", Shellwords.join(args))
+    Shell.cmd(*args, separate_stderr: true)
+  end
+  private :workload_status_result
+
   def fetch_workload!(workload)
     workload_data = fetch_workload(workload)
     return workload_data if workload_data
@@ -279,9 +301,14 @@ class Controlplane # rubocop:disable Metrics/ClassLength
   end
 
   def workload_exec(workload, replica, location:, container: nil, command: nil)
-    cmd = "cpln workload exec #{workload} #{gvc_org} --replica #{replica} --location #{location} -it"
-    cmd += " --container #{container}" if container
-    cmd += " -- #{command}"
+    cmd = [
+      "cpln", "workload", "exec", workload,
+      "--gvc", gvc, "--org", org,
+      "--replica", replica, "--location", location, "-it"
+    ]
+    cmd.push("--container", container) if container
+    cmd << "--"
+    cmd.concat(Array(command))
     perform(cmd, output_mode: :all)
   end
 
@@ -383,6 +410,10 @@ class Controlplane # rubocop:disable Metrics/ClassLength
     api.fetch_secret(org: org, secret: secret)
   end
 
+  def reveal_secret(secret)
+    api.reveal_secret(org: org, secret: secret)
+  end
+
   # identities
 
   def fetch_identity(identity, a_gvc = gvc)
@@ -509,6 +540,7 @@ class Controlplane # rubocop:disable Metrics/ClassLength
   # or the return value of `Shell.should_hide_output?`.
   def build_command(cmd, output_mode: nil) # rubocop:disable Metrics/MethodLength
     output_mode ||= determine_command_output_mode
+    raise "Array commands require output mode 'all'." if cmd.is_a?(Array) && %i[errors_only none].include?(output_mode)
 
     case output_mode
     when :all
@@ -535,7 +567,8 @@ class Controlplane # rubocop:disable Metrics/ClassLength
   def perform(cmd, output_mode: nil, sensitive_data_pattern: nil)
     cmd = build_command(cmd, output_mode: output_mode)
 
-    Shell.debug("CMD", cmd, sensitive_data_pattern: sensitive_data_pattern)
+    debug_cmd = cmd.is_a?(Array) ? Shellwords.join(cmd) : cmd
+    Shell.debug("CMD", debug_cmd, sensitive_data_pattern: sensitive_data_pattern)
 
     kernel_system_with_pid_handling(cmd)
   end
@@ -544,7 +577,7 @@ class Controlplane # rubocop:disable Metrics/ClassLength
   # Returns true on zero exit, false on non-zero exit, nil when the process was signal-killed.
   # SystemCallError (e.g. cpln binary missing) propagates — startup checks ensure this is unreachable in practice.
   def kernel_system_with_pid_handling(cmd)
-    pid = Process.spawn(cmd)
+    pid = cmd.is_a?(Array) ? Process.spawn(*cmd) : Process.spawn(cmd)
     $child_pids << pid # rubocop:disable Style/GlobalVars
 
     _, status = Process.wait2(pid)

data/lib/core/controlplane_api.rb

@@ -122,6 +122,14 @@ class ControlplaneApi # rubocop:disable Metrics/ClassLength
     api_json("/org/#{org}/secret/#{secret}", method: :get)
   end
 
+  def reveal_secret(org:, secret:)
+    api_json(
+      "/org/#{org}/secret/#{secret}/-reveal",
+      method: :get,
+      request_policy: ControlplaneApiDirect::BEST_EFFORT_SENSITIVE_REQUEST_POLICY
+    )
+  end
+
   def delete_secret(org:, secret:)
     api_json("/org/#{org}/secret/#{secret}", method: :delete)
   end