> ## Documentation Index
> Fetch the complete documentation index at: https://docs.leanmcp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment Variables

> Manage Lambda environment variables with the CLI

# Environment Variables

Manage environment variables for your deployed Lambda functions directly from the CLI.

## Overview

The `leanmcp env` command provides a complete set of tools for managing environment variables on your running Lambda deployments. Changes are applied immediately (causing a cold start on next invocation).

<Warning>
  System variables like `PORT`, `AWS_LWA_*` cannot be modified or deleted as they are required for Lambda Web Adapter.
</Warning>

## List Environment Variables

View all environment variables for your deployment:

```bash theme={null}
leanmcp env list
```

### Options

| Flag           | Short | Description          |
| -------------- | ----- | -------------------- |
| `--reveal`     | `-r`  | Show unmasked values |
| `--project-id` | `-p`  | Specify project ID   |

### Examples

```bash theme={null}
# Basic list (values masked)
leanmcp env list

# Show actual values
leanmcp env list --reveal

# List for specific project
leanmcp env list --project-id proj_abc123
```

**Example Output:**

```
Environment Variables for my-mcp-server

────────────────────────────────────────────────
  API_KEY: ••••••••
  DATABASE_URL: ••••••••
  DEBUG_MODE: ••••••••
  PORT: 8080 (system)

Total: 4 variables
```

**With --reveal:**

```
Environment Variables for my-mcp-server

────────────────────────────────────────────────
  API_KEY: sk-1234567890abcdef
  DATABASE_URL: postgres://user:pass@host:5432/db
  DEBUG_MODE: true
  PORT: 8080 (system)

Total: 4 variables
```

## Set Environment Variable

Add or update an environment variable:

```bash theme={null}
leanmcp env set KEY=value
```

### Options

| Flag           | Short | Description        |
| -------------- | ----- | ------------------ |
| `--project-id` | `-p`  | Specify project ID |

### Examples

```bash theme={null}
# Set a single variable
leanmcp env set API_KEY=sk-1234567890abcdef

# Set for specific project
leanmcp env set DATABASE_URL=postgres://localhost:5432/db --project-id proj_abc123

# Set multiple variables at once
leanmcp env set API_KEY=sk-abc123 DEBUG_MODE=true MAX_RETRIES=3
```

**Example Output:**

```
Setting environment variable(s) for my-mcp-server...

Successfully updated:
  ✓ API_KEY
  ✓ DEBUG_MODE
  ✓ MAX_RETRIES

Variables updated successfully!
Note: Changes will take effect after a cold start.
```

<Tip>
  Variable keys are automatically converted to uppercase and sanitized to match Lambda environment variable naming rules.
</Tip>

## Get Environment Variable

Retrieve a specific environment variable:

```bash theme={null}
leanmcp env get KEY
```

### Options

| Flag           | Short | Description         |
| -------------- | ----- | ------------------- |
| `--reveal`     | `-r`  | Show unmasked value |
| `--project-id` | `-p`  | Specify project ID  |

### Examples

```bash theme={null}
# Get masked value
leanmcp env get API_KEY

# Get actual value
leanmcp env get API_KEY --reveal

# Get from specific project
leanmcp env get DATABASE_URL --project-id proj_abc123
```

**Example Output:**

```
API_KEY=••••••••
```

**With --reveal:**

```
API_KEY=sk-1234567890abcdef
```

## Remove Environment Variable

Delete an environment variable:

```bash theme={null}
leanmcp env remove KEY
```

### Options

| Flag           | Short | Description              |
| -------------- | ----- | ------------------------ |
| `--project-id` | `-p`  | Specify project ID       |
| `--yes`        | `-y`  | Skip confirmation prompt |

### Examples

```bash theme={null}
# Remove with confirmation
leanmcp env remove API_KEY

# Skip confirmation
leanmcp env remove DEBUG_MODE --yes

# Remove from specific project
leanmcp env remove OLD_CONFIG --project-id proj_abc123
```

**Example Output:**

```
? Are you sure you want to delete API_KEY? (y/N) y

Removing environment variable: API_KEY

Variable removed successfully!
Note: Changes will take effect after a cold start.
```

<Warning>
  This action cannot be undone. The variable will be permanently deleted from your Lambda function.
</Warning>

## Pull Environment Variables

Download environment variables to a local `.env` file:

```bash theme={null}
leanmcp env pull
```

### Options

| Flag           | Short | Description                                  |
| -------------- | ----- | -------------------------------------------- |
| `--output`     | `-o`  | Output file path (default: `.env`)           |
| `--project-id` | `-p`  | Specify project ID                           |
| `--overwrite`  |       | Overwrite existing file without confirmation |

### Examples

```bash theme={null}
# Pull to .env (default)
leanmcp env pull

# Pull to custom file
leanmcp env pull --output .env.production

# Overwrite without confirmation
leanmcp env pull --overwrite

# Pull from specific project
leanmcp env pull --project-id proj_abc123
```

**Example Output:**

```
Pulling environment variables from my-mcp-server...

Downloaded 4 variables to .env

✓ API_KEY
✓ DATABASE_URL
✓ DEBUG_MODE
✓ MAX_RETRIES

Note: System variables (PORT, AWS_LWA_*) are excluded.
```

**Generated .env file:**

```bash theme={null}
# Environment variables from my-mcp-server
# Downloaded: 2026-01-21T22:12:00Z

API_KEY=sk-1234567890abcdef
DATABASE_URL=postgres://user:pass@host:5432/db
DEBUG_MODE=true
MAX_RETRIES=3
```

## Push Environment Variables

Upload environment variables from a local `.env` file:

```bash theme={null}
leanmcp env push
```

### Options

| Flag           | Short | Description                             |
| -------------- | ----- | --------------------------------------- |
| `--file`       | `-f`  | Input file path (default: `.env`)       |
| `--project-id` | `-p`  | Specify project ID                      |
| `--merge`      |       | Merge with existing variables (default) |
| `--replace`    |       | Replace all existing variables          |

### Examples

```bash theme={null}
# Push from .env (merge mode)
leanmcp env push

# Push from custom file
leanmcp env push --file .env.production

# Replace all variables
leanmcp env push --replace

# Push to specific project
leanmcp env push --project-id proj_abc123
```

**Example Output (Merge Mode):**

```
Pushing environment variables from .env...

Parsing file...
Found 5 variables

? This will update 3 and add 2 variables. Continue? (Y/n) y

Updating variables on my-mcp-server...

Successfully updated:
  ✓ API_KEY (updated)
  ✓ DATABASE_URL (updated)
  ✓ DEBUG_MODE (updated)
  ✓ NEW_VAR_1 (added)
  ✓ NEW_VAR_2 (added)

Variables pushed successfully!
Note: Changes will take effect after a cold start.
```

**Example Output (Replace Mode):**

```
Pushing environment variables from .env...

⚠️  WARNING: Replace mode will delete all existing variables!

Current variables (4):
  - API_KEY
  - DATABASE_URL
  - DEBUG_MODE
  - OLD_CONFIG

New variables (3):
  + API_KEY
  + DATABASE_URL
  + NEW_CONFIG

? This will DELETE 2 variables and set 3 variables. Continue? (y/N) y

Replacing all variables on my-mcp-server...

Variables replaced successfully!
Note: Changes will take effect after a cold start.
```

<Warning>
  In `--replace` mode, all existing user variables will be deleted and replaced with the contents of your file. System variables are always preserved.
</Warning>

## Full Workflow Example

Complete workflow for managing environment variables:

```bash theme={null}
# 1. Pull current variables to local file
leanmcp env pull --output .env.backup

# 2. Check current variables
leanmcp env list --reveal

# 3. Add new variables
leanmcp env set NEW_API_KEY=sk-new123 FEATURE_FLAG=enabled

# 4. Update .env file locally (edit as needed)
# Edit .env file...

# 5. Push updated variables
leanmcp env push

# 6. Verify changes
leanmcp env list

# 7. Get specific variable
leanmcp env get NEW_API_KEY --reveal

# 8. Remove old variable
leanmcp env remove OLD_API_KEY --yes
```

## Protected Variables

The following variables are protected and cannot be modified:

**AWS Reserved:**

* `AWS_*` (all AWS-prefixed variables)

**Lambda Web Adapter System:**

* `PORT`
* `AWS_LWA_PORT`
* `AWS_LWA_INVOKE_MODE`
* `AWS_LWA_READINESS_CHECK_MIN_UNHEALTHY_STATUS`

<Info>
  These variables are automatically managed by AWS Lambda and the Lambda Web Adapter. Attempting to modify them will result in them being skipped with a warning.
</Info>

## Troubleshooting

### Not Authenticated

```
Not authenticated
Run 'leanmcp login' to authenticate.
```

**Solution:** Run `leanmcp login` and enter your API key.

### No Deployment Found

```
No Lambda deployment found for current project
```

**Solution:** Deploy your project first using `leanmcp deploy .`

### Variable Name Validation

```
Invalid variable name: my-key
Variable names must match: /^[A-Z][A-Z0-9_]*$/
```

**Solution:** Use only uppercase letters, numbers, and underscores. Must start with a letter.

### File Not Found

```
File not found: .env
```

**Solution:** Ensure the `.env` file exists or specify a different file with `--file`.

### Parse Error

```
Failed to parse .env file
Invalid format at line 5: "INVALID LINE"
```

**Solution:** Ensure your `.env` file uses `KEY=VALUE` format (one per line).

## Next Steps

<CardGroup cols={2}>
  <Card title="Deploy Projects" icon="rocket" href="/cli/deployment">
    Deploy your MCP server to the cloud
  </Card>

  <Card title="Monitor Deployments" icon="chart-line" href="https://leanmcp.com">
    View deployment status and logs
  </Card>
</CardGroup>