# How to add environment variables during deployment

Pass encrypted environment variables or an env file to Ample without packaging secret files into the release.

## The short version

Pass deployment values with repeated --env arguments or import a dotenv-style file with --env-file. Ample encrypts deployment environment variables and excludes common env files from the source package. Declare secret keys in ample.toml without literal values, then supply the values when you deploy.

## Who this is for

This guide is for apps that need API keys, database URLs, runtime settings, or public build-time configuration.

## How to do it

1. **Separate secrets from public values.** Server-side tokens, passwords, and private keys are secrets. Framework prefixes such as VITE_, NEXT_PUBLIC_, PUBLIC_, and NUXT_PUBLIC_ are browser-visible and must contain only public values.

2. **Declare the shape in ample.toml.** A secret declaration records that the service needs the value without committing the value itself.
   
   ```
   $ SMTP_KEY = { secret = true }
   ```

3. **Pass a value directly.** Repeat --env for multiple values. A bare key can prompt for its value where interactive input is available.
   
   ```
   $ ample deploy --env SMTP_KEY --env NODE_ENV=production
   ```

4. **Or import an env file.** Use an existing dotenv-style file as deployment input. The file is read for values and is not packaged as application source.
   
   ```
   $ ample deploy --env-file .env.production
   ```

5. **Redeploy build-time changes.** Public framework variables may be inlined during the build. Create a new deployment after changing them so the client bundle is rebuilt.

## What this supports

- Repeated encrypted --env values
- Dotenv-style --env-file imports
- Secret declarations in ample.toml
- Framework-specific public build variables

## Know the limits

- Literal secret values are rejected in ample.toml
- Public-prefixed variables are visible to browser users
- A missing secret cannot be inferred safely from source code

## Common failure modes

- **The app reports a missing variable** Confirm the key name, service, and deploy command, then inspect runtime logs.
- **A frontend value did not change** Use the framework's public prefix and redeploy so the production bundle is rebuilt.
- **A secret file is blocked from packaging** Keep the file out of the artifact and import its values with --env-file instead.
