# Environment variables

> Environment variables - Manage environment variables and .env files in DataRobot templates with
> interactive configuration tools.

This Markdown file sits beside the HTML page at the same path (with a `.md` suffix). It summarizes the topic and lists links for tools and LLM context.

Companion generated at `2026-05-06T18:17:09.551759+00:00` (UTC).

## Primary page

- [Environment variables](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html): Full documentation for this topic (HTML).

## Sections on this page

- [File structure](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#file-structure): In-page section heading.
- [.env.template](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#env-template): In-page section heading.
- [Characteristics](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#characteristics): In-page section heading.
- [.env](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#env): In-page section heading.
- [Create environment files](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#create-environment-files): In-page section heading.
- [Use the wizard](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#use-the-wizard): In-page section heading.
- [Wizard workflow](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#wizard-workflow): In-page section heading.
- [Manual creation](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#manual-creation): In-page section heading.
- [Manage variables](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#manage-variables): In-page section heading.
- [Interactive editor](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#interactive-editor): In-page section heading.
- [Features](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#features-editor): In-page section heading.
- [Commands](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#commands): In-page section heading.
- [Wizard mode](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#wizard-mode): In-page section heading.
- [Advantages](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#advantages): In-page section heading.
- [Direct editing](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#direct-editing): In-page section heading.
- [Variable types](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#variable-types): In-page section heading.
- [Required variables](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#required-variables): In-page section heading.
- [Optional variables](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#optional-variables): In-page section heading.
- [Secret variables](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#secret-variables): In-page section heading.
- [Auto-detection](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#auto-detection): In-page section heading.
- [Display behavior](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#display-behavior): In-page section heading.
- [Security best practices](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#security-best-practices-secrets): In-page section heading.
- [Auto-generated secrets](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#auto-generated-secrets): In-page section heading.
- [Features](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#features-auto-generated): In-page section heading.
- [Conditional variables](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#conditional-variables): In-page section heading.
- [Environment variable discovery](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#environment-variable-discovery): In-page section heading.
- [1. Template file (.env.template)](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#template-file): In-page section heading.
- [2. Prompt definitions (.datarobot/prompts.yaml)](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#prompt-definitions): In-page section heading.
- [3. Existing .env file](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#existing-env-file): In-page section heading.
- [4. Current environment](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#current-environment): In-page section heading.
- [Merge priority](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#merge-priority): In-page section heading.
- [Common patterns](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#common-patterns): In-page section heading.
- [Database configuration](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#database-configuration): In-page section heading.
- [Authentication](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#authentication): In-page section heading.
- [Feature flags](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#feature-flags): In-page section heading.
- [Logging](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#logging): In-page section heading.
- [Security best practices](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#security-best-practices): In-page section heading.
- [Never commit .env files](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#never-commit-env-files): In-page section heading.
- [Use strong secrets](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#use-strong-secrets): In-page section heading.
- [Restrict file permissions](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#restrict-file-permissions): In-page section heading.
- [Use different configs per environment](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#use-different-configs-per-environment): In-page section heading.
- [Avoid hardcoding in code](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#avoid-hardcoding-in-code): In-page section heading.
- [Validation](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#validation): In-page section heading.
- [Validate with dr dotenv](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#validate-with-dr-dotenv): In-page section heading.
- [Example output](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#example-output): In-page section heading.
- [Use cases](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#use-cases): In-page section heading.
- [Required variables check](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#required-variables-check): In-page section heading.
- [Format validation](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#format-validation): In-page section heading.
- [Advanced features](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#advanced-features): In-page section heading.
- [Variable substitution](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#variable-substitution): In-page section heading.
- [Multi-line values](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#multi-line-values): In-page section heading.
- [Comments](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#comments): In-page section heading.
- [Troubleshooting](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#troubleshooting): In-page section heading.
- [Variables not loading](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#variables-not-loading): In-page section heading.
- [Secrets exposed](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#secrets-exposed): In-page section heading.
- [Permission errors](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#permission-errors): In-page section heading.
- [Variables not expanding](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#variables-not-expanding): In-page section heading.
- [Configuration not working](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#configuration-not-working): In-page section heading.
- [Common workflows](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#common-workflows): In-page section heading.
- [Initial setup](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#initial-setup): In-page section heading.
- [Update credentials](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#update-credentials): In-page section heading.
- [Validate before deployment](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#validate-before-deployment): In-page section heading.
- [Edit and validate](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#edit-and-validate): In-page section heading.
- [See also](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/environment-variables.html#see-also): In-page section heading.

## Related documentation

- [Agentic AI](https://docs.datarobot.com/en/docs/agentic-ai/index.html): Linked from this page.
- [CLI](https://docs.datarobot.com/en/docs/agentic-ai/cli/index.html): Linked from this page.
- [Template system](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/index.html): Linked from this page.
- [Interactive configuration](https://docs.datarobot.com/en/docs/agentic-ai/cli/template-system/interactive-config.html): Linked from this page.
- [Template structure](https://docs.datarobot.com/en/docs/agentic-ai/cli/development/structure.html): Linked from this page.
- [dotenv command](https://docs.datarobot.com/en/docs/agentic-ai/cli/commands/dotenv.html): Linked from this page.

## Documentation content

This page outlines how to manage environment variables and `.env` files in DataRobot templates. DataRobot templates use `.env` files to store configuration variables needed by your application. The CLI provides tools to:

- Create .env files from templates
- Interactively edit variables
- Validate configuration
- Securely manage secrets

## File structure

### .env.template

The template provided by the repository (committed to Git):

```
# Required configuration
APP_NAME=
DATAROBOT_ENDPOINT=
DATAROBOT_API_TOKEN=

# Optional configuration
# DEBUG=false
# LOG_LEVEL=info
# PORT=8080

# Database configuration
# DATABASE_URL=
# DATABASE_POOL_SIZE=10

# Cache configuration
# CACHE_ENABLED=false
# CACHE_URL=
```

#### Characteristics

- Committed to version control
- Contains empty required variables
- Comments indicate optional variables
- Includes documentation comments

### .env

The actual configuration file (never committed):

```
# Required configuration
APP_NAME=my-awesome-app
DATAROBOT_ENDPOINT=https://app.datarobot.com
DATAROBOT_API_TOKEN=***

# Optional configuration
DEBUG=true
LOG_LEVEL=debug
PORT=8000

# Database configuration
DATABASE_URL=postgresql://localhost:5432/mydb
DATABASE_POOL_SIZE=5
```

Characteristics: - Generated from `.env.template`.
- Contains actual values.
- Never committed (in `.gitignore`).
- User-specific configuration.

## Create environment files

### Use the wizard

The interactive wizard guides you through configuration.

```
# In a template directory
dr dotenv setup
```

or

```
# During template setup
dr templates setup
```

#### Wizard workflow

1. Loads .env.template .
2. Discovers configuration prompts.
3. Shows interactive questions.
4. Validates inputs.
5. Generates an .env file.

### Manual creation

To copy and edit a template manually:

```
# Copy the template
cp .env.template .env

# Edit the template with your preferred editor
vim .env

# Alternatively, use the CLI editor
dr dotenv
```

## Manage variables

### Interactive editor

Launch the built-in editor to manage variables:

```
dr dotenv
```

#### Features

- List all variables
- Mask secrets (passwords, API keys)
- Start wizard mode
- Directly edit variables

#### Commands

```
Variables found in .env:

APP_NAME: my-awesome-app
DATAROBOT_ENDPOINT: https://app.datarobot.com
DATAROBOT_API_TOKEN: ***
DEBUG: true

Press w to set up variables interactively.
Press e to edit the file directly.
Press enter to finish and exit.
```

### Wizard mode

You can also interactively configure a template with prompts.

```
dr dotenv setup
```

#### Advantages

- Guided setup
- Built-in validation
- Conditional prompts
- Help text for each variable

### Direct editing

To edit the file directly:

```
dr dotenv edit
# Press 'e' to enter editor mode

# Or use external editor
vim .env
```

## Variable types

### Required variables

The following variables must be set before running the application:

```
# .env.template shows these without comments
APP_NAME=
DATAROBOT_ENDPOINT=
DATAROBOT_API_TOKEN=
```

The wizard enforces that an application name must be provided.

```
Enter your application name
> _
(Cannot proceed without entering a value)
```

### Optional variables

The following variables are optional and can be left empty (shown as comments):

```
# .env.template shows these with # prefix
# DEBUG=false
# LOG_LEVEL=info
```

The wizard allows you to skip binding these variables:

```
Enable debug mode? (optional)
  > None (leave blank)
    Yes
    No
```

### Secret variables

Sensitive values that should be masked during input and display.

To define secret variables:

```
# In .datarobot/prompts.yaml
prompts:
  - key: "api_key"
    env: "API_KEY"
    type: "secret_string"
    help: "Enter your API key"
```

#### Auto-detection

Variables with names containing `PASSWORD`, `SECRET`, `KEY`, or `TOKEN` are automatically treated as secrets.

#### Display behavior

- The wizard input's secrets are masked with bullet characters (••••).
- The editor view displays secrets as *** .
- The actual file contains secrets as plain text values.

#### Security best practices

- Always add .env to .gitignore .
- Use secret_string type for all sensitive values.
- Never commit .env files to version control.

### Auto-generated secrets

You can cryptographically secure random values for application secrets:

```
prompts:
  - key: "session_secret"
    env: "SESSION_SECRET"
    type: "secret_string"
    generate: true
    help: "Session encryption key (auto-generated)"
```

#### Features

- Generates 32-character random string if no value exists.
- Uses base64 URL-safe encoding.
- Preserves existing values (only generates when empty).
- User can override secrets with a custom value.

### Conditional variables

These variables are only shown or required based on your other selections:

```
# In .datarobot/prompts.yaml
prompts:
  - key: "enable_database"
    options:
      - name: "Yes"
        requires: "database_config"
      - name: "No"

  - key: "database_url"
    section: "database_config"
    env: "DATABASE_URL"
    help: "Database connection string"
```

If `Enable database = No`, then `DATABASE_URL` is not shown.

## Environment variable discovery

The CLI discovers variables from multiple sources:

### 1. Template file (.env.template)

```
# Variables defined in template
APP_NAME=
PORT=8080
```

### 2. Prompt definitions (.datarobot/prompts.yaml)

```
prompts:
  - key: "app_name"
    env: "APP_NAME"
    help: "Application name"
```

### 3. Existing .env file

```
# Previously configured values
APP_NAME=my-app
```

### 4. Current environment

```
# Shell environment variables
export PORT=3000
```

### Merge priority

The CLI merges in the following order of priority (highest priority first):

1. User input from wizard.
2. Current shell environment.
3. Existing .env values.
4. Template defaults.

## Common patterns

### Database configuration

```
# PostgreSQL
DATABASE_URL=postgresql://user:password@localhost:5432/dbname
DATABASE_POOL_SIZE=10
DATABASE_TIMEOUT=30

# MySQL
DATABASE_URL=mysql://user:password@localhost:3306/dbname

# MongoDB
DATABASE_URL=mongodb://localhost:27017/dbname
```

### Authentication

```
# API Key
DATAROBOT_API_TOKEN=your_api_token_here

# OAuth
AUTH_PROVIDER=oauth2
AUTH_CLIENT_ID=client_id
AUTH_CLIENT_SECRET=***
AUTH_REDIRECT_URL=http://localhost:8080/callback

# JWT
JWT_SECRET=***
JWT_EXPIRATION=3600
```

### Feature flags

```
# Enable/disable features
FEATURE_ANALYTICS=true
FEATURE_MONITORING=false
FEATURE_CACHING=true

# Or as comma-separated list
ENABLED_FEATURES=analytics,caching
```

### Logging

```
# Log level
LOG_LEVEL=debug  # debug, info, warn, error

# Log format
LOG_FORMAT=json  # json, text

# Log output
LOG_OUTPUT=stdout  # stdout, file

# Log file path
LOG_FILE=/var/log/app.log
```

## Security best practices

### Never commit .env files

Ensure that `.gitignore` includes:

```
# Environment variables
.env
.env.local
.env.*.local

# Keep templates
!.env.template
!.env.example
```

### Use strong secrets

```
# ✓ Good - strong random secret
JWT_SECRET=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

# ✗ Bad - weak secret
JWT_SECRET=secret123
```

Generate secure secrets:

```
# Random 32-byte hex string
openssl rand -hex 32
```

### Restrict file permissions

```
# Only the owner can read/write
chmod 600 .env

# Verify
ls -la .env
# Should show: -rw------- (600)
```

### Use different configs per environment

```
# Development
.env.development

# Staging
.env.staging

# Production
.env.production
```

Load based on the environment:

```
export ENV=production
dr run deploy
```

### Avoid hardcoding in code

```
# ✗ Bad
api_token = "abc123"

# ✓ Good
import os
api_token = os.getenv("DATAROBOT_API_TOKEN")
```

## Validation

### Validate with dr dotenv

To validate your environment configuration against template requirements:

```
dr dotenv validate
```

This command validates the following:

- All required variables defined in .datarobot/prompts.yaml .
- Core DataRobot variables ( DATAROBOT_ENDPOINT , DATAROBOT_API_TOKEN ).
- Conditional requirements based on selected options.
- Both .env file and environment variables.

#### Example output

Successful validation:

```
Validating required variables:
  APP_NAME: my-app
  DATAROBOT_ENDPOINT: https://app.datarobot.com
  DATAROBOT_API_TOKEN: ***
  DATABASE_URL: postgresql://localhost:5432/db

Validation passed: all required variables are set.
```

Validation errors:

```
Validating required variables:
  APP_NAME: my-app
  DATAROBOT_ENDPOINT: https://app.datarobot.com

Validation errors:

Error: required variable DATAROBOT_API_TOKEN is not set
  Description: DataRobot API token for authentication
  Set this variable in your .env file or run `dr dotenv setup` to configure it.

Error: required variable DATABASE_URL is not set
  Description: PostgreSQL database connection string
  Set this variable in your .env file or run `dr dotenv setup` to configure it.
```

#### Use cases

- Pre-flight checks before running tasks.
- CI/CD pipeline validation.
- Debugging missing configuration.
- Troubleshooting application startup issues.

### Required variables check

Commands like `dr run` automatically validate required variables.

```
$ dr run dev
Error: Missing required environment variables:
  - APP_NAME
  - DATAROBOT_API_TOKEN

Please run: dr dotenv setup
```

### Format validation

For variables with specific formats:

```
# URL validation
DATAROBOT_ENDPOINT=https://app.datarobot.com  # ✓ Valid
DATAROBOT_ENDPOINT=not-a-url                   # ✗ Invalid

# Port validation
PORT=8080    # ✓ Valid
PORT=99999   # ✗ Invalid (out of range)

# Email validation
EMAIL=user@example.com  # ✓ Valid
EMAIL=invalid           # ✗ Invalid
```

## Advanced features

### Variable substitution

Reference other variables:

```
# Base URL
BASE_URL=https://app.datarobot.com

# API endpoint uses base URL
API_ENDPOINT=${BASE_URL}/api/v2

# Full URL becomes: https://app.datarobot.com/api/v2
```

### Multi-line values

For long values:

```
# Single line
PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIE..."

# Or use actual newlines
PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC...
-----END PRIVATE KEY-----"
```

### Comments

Document your configuration:

```
# Application Configuration
APP_NAME=my-app          # Application identifier
PORT=8080                # HTTP server port

# Database Configuration
# Format: protocol://user:password@host:port/database
DATABASE_URL=postgresql://localhost:5432/mydb
```

## Troubleshooting

### Variables not loading

```
# Check .env exists
ls -la .env

# Verify format
cat .env

# Check for syntax errors
# Each line should be: KEY=value
```

### Secrets exposed

```
# Check .gitignore includes .env
cat .gitignore | grep .env

# Check Git status
git status
# Should NOT show .env

# If .env is tracked, remove it
git rm --cached .env
git commit -m "Remove .env from tracking"
```

### Permission errors

```
# Fix permissions
chmod 600 .env

# Verify
ls -la .env
```

### Variables not expanding

```
# Ensure proper syntax for variable substitution
# Works:
API_URL=${BASE_URL}/api

# Doesn't work:
API_URL=$BASE_URL/api  # Missing braces
```

### Configuration not working

Use `dr dotenv validate` to diagnose issues:

```
# Validate configuration
dr dotenv validate

# If validation passes but issues persist, check:
# 1. Environment variables override .env
env | grep DATAROBOT

# 2. Ensure .env is in correct location (repository root)
pwd
ls -la .env

# 3. Check if application is loading .env file
# Some applications need explicit .env loading
```

## Common workflows

### Initial setup

```
cd my-template
dr dotenv setup
dr dotenv validate
dr run dev
```

### Update credentials

```
dr auth login
dr dotenv update
dr dotenv validate
```

### Validate before deployment

```
dr dotenv validate && dr run deploy
```

### Edit and validate

```
dr dotenv edit
dr dotenv validate
```

## See also

- Interactive configuration : Configuration wizard details.
- Template structure : Template organization.
- dotenv command : dotenv command reference.