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

---

## Before you start

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

---

## How to do it

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

### Good fit

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