# 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.

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

**Console**
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.

**CLI**
```sh
dcloud deploy env import app-id --content "$(cat .env.op)" --preview
dcloud deploy env import app-id --content "$(cat .env.op)" --redeploy
```

`--mode replace` removes variables the file does not mention. `--classify` overrides how a key is
stored, once per key: `--classify API_URL=plain --classify STRIPE_KEY=secret`.

**API**
```http
POST /deploy/api/apps/3f1c2b4a-5d6e-4f70-8a91-b2c3d4e5f601/env/import
{ "content": "LOG_LEVEL=info\nAPI_TOKEN=op://Production/api/token\n", "mode": "merge", "preview": true }
```

Send the same body without `preview` to apply it; `classify` switches a key between `plain` and
`secret`.

## 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:

```sh
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](set-environment-variables.md).

## Related

- [Secrets](/docs/secrets)
- `deploy.env.import` · `dcloud deploy env import` · `deploy.env.export`
