Import a .env file

Bring a .env or .env.op file into an app's environment, with secrets created and 1Password references synced, and export the environment back as a file.

Last updated 18 November 2026View as Markdown

An import is planned first and applied in one transaction: secrets created, rotated and granted, and the environment replaced. Either all of it lands, or none of it does. No value is ever sent back. Replace app-id with the app's id.

Prerequisites

  • Permission for deploy:ManageEnv on the app. A file with op:// references also needs secrets:UseSecretSource on the source, already for the preview. Applying needs, as the plan requires, secrets:CreateSecret (new secrets), secrets:RotateSecret (a new value for a key that is already a secret) and secrets:GetSecretValue (an ews-secret:// binding). To redeploy in the same step, deploy:DeployApp.
  • In the console, also deploy:DescribeApp to open the app's page (without it the page is not found).

Import the file

  1. Open the app's Environment tab, then choose Import .env.
  2. Paste the file into the text box, or choose Upload file and pick it.
  3. For Mode, choose Merge (keep variables the file omits) or Replace (remove variables the file omits).
  4. (Optional) When the file holds op:// references and several secret sources are connected, for Source for new references, choose one. Automatic (the one that reaches the vault) is the default.
  5. Choose Preview. Each key is listed with its Change (Add, Update, Unchanged, Remove or Error), what it is Stored as and What happens.
  6. (Optional) For a key detected as Plain or Secret, change Stored as. The preview runs again.
  7. Choose Apply, or Apply & redeploy (shown only with deploy:DeployApp). Both stay unavailable until a preview without errors. The dialog reports how many variables were added, updated and removed, and whether a redeploy was queued.

How each line is stored

Value Stored as
op://vault/item/field a synced secret, through the source that synced it or reaches the vault
ews-secret://NAME a binding to the existing secret NAME
looks sensitive a new secret, encrypted under your CMK, granted to deploy and bound
anything else, and NEXT_PUBLIC_*, VITE_* a plain variable

A value looks sensitive if any of these hold:

  • its name says so (SECRET, PASSWORD, TOKEN, API_KEY, …_KEY, DSN, …);
  • it is a URL with a password;
  • it starts with a known credential prefix (sk-, ghp_, AKIA, -----BEGIN, …);
  • it is long and random.

Numbers and flags stay plain. A key that already exists keeps the kind it has. The preview is the plan: every key is marked add, update, unchanged, remove or error with what will happen, and references are checked against 1Password. Nothing is applied while any key has an error.

  • merge (default) keeps variables the file does not mention; replace removes them.
  • A pasted value for a key that is already a secret rotates that secret, writing a new version so the old one can be rolled back.
  • A reference already synced elsewhere reuses that synced secret. When several secret sources reach a vault, choose the source for new references.
  • A multi-line value is an error on its key: "Multi-line values are not supported (each variable is written as one line). Store it base64-encoded, or as a file in the image."
  • A key that the app's database binding generates is an error too: "KEY is generated by this app's database binding".

An apply that would create a secret needs an enabled encryption key in KMS; without one the import is refused with 409 "No enabled encryption key in this organization — create one under KMS first". Applying a plan that still has errors answers 422 "The import has N error(s); nothing was changed". The file can be at most 512 KiB.

Export the environment

On the Environment tab, choose Export, or:

dcloud deploy env export app-id

The file holds plain values in full; synced secrets as their op:// reference, so the export of a .env.op import is a .env.op; other secrets as ews-secret://NAME; database-binding variables as comments. No secret value is ever exported. The file imports back unchanged.

Result

The app's environment holds the file's variables. Without a redeploy, the panel shows Saved, not running. until someone redeploys; see Set environment variables.

Did this page help you?