deploy.env.import

Import a .env or .env.op file — dry run for the plan, then apply atomically

POST /deploy/api/apps/{id}/env/importIAM deploy:ManageEnvChanges stateDestructive

dcloud deploy env import <appId> --content "$(cat .env.op)" --preview. op:// references become synced secrets; sensitive-looking values become secrets, the rest plain (override per key with classify); dcloud-secret://NAME (or ews-secret://NAME) binds an existing secret. mode=merge keeps keys the file omits, replace removes them. Nothing is applied if any key has an error. No value is ever echoed back. 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:CreateSecret, secrets:RotateSecret, secrets:UseSecretSource, secrets:GetSecretValue, deploy:DeployApp instead; hold all of them to be sure it is allowed.

Request syntax

POST /deploy/api/apps/{id}/env/import
{
  "content": "string",
  "mode": "enum",
  "classify": "map of string",
  "source": "string",
  "sourceId": "string",
  "keyId": "string",
  "preview": "boolean",
  "redeploy": "boolean"
}

Path parameters

  • idRequired

    string

    Constraints: uuid

Request body

  • contentRequired

    string

    The .env / .env.op file text

    Constraints: max 524288 chars

  • modeOptional

    enum

    merge (default) keeps variables the file does not mention; replace removes them

    One of: merge, replace

  • classifyOptional

    map of string

    Per key, plain or secret, overriding the kind the import would pick

    Constraints: key=value

  • sourceOptional

    string

    Secret source (by name) for NEW op:// references, needed only when several sources reach the vault

    Constraints: 2-63 chars

    May be null.

  • sourceIdOptional

    string

    The same secret source as source, by id (the older spelling)

    Constraints: uuid

    May be null.

  • keyIdOptional

    string

    KMS key new secrets are encrypted under; default the organization’s default key

    Constraints: uuid

    May be null.

  • previewOptional

    boolean

    Return the plan without changing anything; default false

  • redeployOptional

    boolean

    Also roll the live deployment onto the imported environment; default false, ignored with preview

Response

200 with `data`: `applied` (false for a preview) and `plan` — `items` (per key, what happens to it), `issues` (lines that could not be read), `summary` (counts of add, update, unchanged, remove, error) and `applicable`. The top-level `redeploy` is null unless redeploy was requested; then { ok: true, deploymentId, generation, reusedDeploymentId } or { ok: false, error }. A plan with errors is answered 422 with the plan and nothing changed.

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

Fields of data

  • appliedAlways

    boolean

    False for a preview: nothing was changed
  • planAlways

    object

    The plan
  • plan.​itemsAlways

    array of object

    Per key, what happens to it
  • plan.​items[].​keyAlways

    string

    Variable name
  • plan.​items[].​kindAlways

    one of plain, secret, reference, existing-secret, removed

    What it becomes
  • plan.​items[].​changeAlways

    one of add, update, unchanged, remove, error

    What happens to it
  • plan.​items[].​reasonAlways

    string

    Why it was classified so
  • plan.​items[].​detailAlways

    string

    What applying does, in a sentence
  • plan.​items[].​errorAlways

    string, may be null

    Why it cannot be applied; null if it can
  • plan.​items[].​lineAlways

    number, may be null

    Line in the file; null for a removal
  • plan.​issuesAlways

    array of object

    Lines that could not be read
  • plan.​issues[].​lineAlways

    number

    Line in the file
  • plan.​issues[].​keyAlways

    string, may be null

    Variable name, if one could be read
  • plan.​issues[].​messageAlways

    string

    What is wrong
  • plan.​summaryAlways

    object

    Counts by change
  • plan.​summary.​addAlways

    number

    Variables added
  • plan.​summary.​updateAlways

    number

    Variables changed
  • plan.​summary.​unchangedAlways

    number

    Variables left as they are
  • plan.​summary.​removeAlways

    number

    Variables removed
  • plan.​summary.​errorAlways

    number

    Variables with an error
  • plan.​applicableAlways

    boolean

    False when any item has an error; nothing is applied then

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 import id --content 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_import.