deploy.env.replace

Replace the whole environment of an app

PUT /deploy/api/apps/{id}/envIAM deploy:ManageEnvChanges stateDestructive

Binding a secret needs secrets:GetSecretValue on it and grants it to the deploy consumer. Saving does not restart the app. Pass redeploy: true to roll the live deployment’s own source onto the new configuration (also needs deploy:DeployApp); otherwise the response and GET …/env report pending until someone redeploys.

Depending on the resource, the call checks secrets:GetSecretValue, deploy:DeployApp instead; hold all of them to be sure it is allowed.

Request syntax

PUT /deploy/api/apps/{id}/env
{
  "vars": "array of json",
  "redeploy": "boolean"
}

Path parameters

  • idRequired

    string

    Constraints: uuid

Request body

  • varsRequired

    array of json

    The complete environment: each entry is a key with valueKind plain (and plainValue, one line) or secret (and kmsSecretId, the Secret to bind). Keys left out are removed

  • redeployOptional

    boolean

    Also roll the live deployment onto the new environment; default false

Response

200 with `data`: the variables now stored (id, key, valueKind, plainValue, kmsSecretId, createdAt, updatedAt). The top-level `redeploy` is null unless redeploy was requested; then { ok: true, deploymentId, generation, reusedDeploymentId } or { ok: false, error }.

A JSON response is wrapped as { "success": true, "data": … }; the CLI prints the whole body with --json.

Fields of data

  • [].​idAlways

    string

    Variable id
  • [].​appIdAlways

    string

    The app
  • [].​keyAlways

    string

    Variable name
  • [].​valueKindAlways

    one of plain, secret

    plain (a value) or secret (a bound Secret)
  • [].​plainValueAlways

    string, may be null

    The value of a plain variable; null for a secret
  • [].​kmsSecretIdAlways

    string, may be null

    The Secret bound to a secret variable; null for plain, or when it was deleted
  • [].​createdAtAlways

    string

    When it was first set
  • [].​updatedAtAlways

    string

    When it was last changed

Checked against the handlers: every route test validates their answers against this schema.

Errors

  • 400The request does not pass the schema above. The body is { "error": …, "issues": […] }, one issue per field.
  • 401No credentials, or an access key that is unknown, revoked or expired.
  • 403The caller's policies do not allow deploy:ManageEnv on this resource. The body names the action and the resource, and the refusal is recorded in the audit log.
  • 404The resource does not exist in your organization.

Examples

The required parameters only, with example values. Replace id and the other placeholders with your own.

dcloud deploy env replace id --vars '["example"]'

Generated from the API description, the same one the API checks requests against and the CLI is built from. MCP tool: dcloud_deploy_env_replace.