Skip to main content

Managing Variables

Learn how to add, edit, delete, and organize environment variables in your bundles.

Overview​

This guide covers all the essential operations for managing environment variables in EnvCat: adding individual variables, bulk importing from .env files, editing values, controlling secret masking, and deleting variables safely.

What you'll learn:

  • Adding variables one at a time or in bulk
  • Editing variable values and secret status
  • Revealing and copying secret values
  • Deleting single or multiple variables
  • Searching and filtering large variable lists

Time to complete: ~10 minutes

Prerequisites​

Before starting:

  • EnvCat installed and running
  • User account created and logged in
  • At least one bundle created

Need help? See Getting Started and Authentication Workflows.

Background​

Environment variables are the core of EnvCat. Each variable has:

  • Key: The environment variable name (e.g., DATABASE_URL)
  • Value: The actual secret or configuration value
  • Secret flag: Controls whether the value is masked in the UI

Use cases:

  • Managing API keys, database URLs, and credentials
  • Organizing configuration by environment (dev, staging, prod)
  • Securely sharing secrets across your team
  • Preparing variables for CLI-based approval flows

Adding Variables​

Method 1: Add Single Variable​

When to use: Adding one or two variables quickly.

Steps:

  1. Navigate to your bundle detail page (/bundles/[id])
  2. Click the "Add Variable" button in the top-right
  3. Fill in the form:
    • Key: Variable name (e.g., API_KEY)
    • Value: The secret or configuration value
    • Mark as secret: Enable to mask the value (recommended for credentials)
  4. Click "Add"

Result: The new variable appears in the list, masked if marked as secret.

Example:

Key: STRIPE_SECRET_KEY
Value: sk_test_abc123def456...
Mark as secret: ✓ (checked)

Method 2: Bulk Import from .env File​

When to use: Migrating existing .env files or adding many variables at once.

Steps:

  1. Click the "Import .env" button
  2. Paste your .env file contents into the text area
  3. Click "Import"

Supported formats:

# Comments are ignored
DATABASE_URL=postgres://localhost:5432/mydb

# Quoted values (quotes are stripped)
API_KEY="secret-value-here"
ANOTHER_KEY='single-quoted-value'

# Special characters preserved
PASSWORD=p@$$w0rd!#

# Multi-line values (use quotes)
PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA...
-----END RSA PRIVATE KEY-----"

What happens:

  • New variables are created
  • Existing variables (matching keys) are updated with new values
  • All imported variables are marked as secrets by default
  • Comments and blank lines are ignored

Result: A toast notification shows how many variables were created/updated:

✓ Imported 15 variables (12 created, 3 updated)

Method 3: Import from JSON​

When to use: Programmatic imports or integrating with other tools.

Steps:

  1. Click "Import .env" button
  2. Switch to JSON format (future enhancement)
  3. Or use the API directly:
curl -X POST http://localhost:8888/api/v1/bundles/YOUR_BUNDLE_ID/import \
  -H "Content-Type: application/json" \
  -d '{
    "format": "json",
    "data": {
      "API_KEY": "secret-value",
      "DATABASE_URL": "postgres://..."
    }
  }'

Response:

{
  "ok": true,
  "created": 2,
  "updated": 0
}

Editing Variables​

Edit Variable Value​

When to use: Updating credentials, fixing typos, or rotating secrets.

Steps:

  1. Find the variable in the list
  2. Click the edit icon (pencil) in the Actions column
  3. Modify the value or secret status
  4. Click "Save"

Important notes:

  • Keys cannot be changed after creation (delete and re-add if needed)
  • Editing preserves the secret flag unless you explicitly change it
  • Values are encrypted at rest automatically

Example use case: Rotating an API key:

Before: API_KEY = sk_old_key_12345
After:  API_KEY = sk_new_key_67890

Toggle Secret Status​

When to use: Changing whether a value should be masked.

Steps:

  1. Click the edit icon for the variable
  2. Check/uncheck "Mark as secret"
  3. Click "Save"

Behavior:

  • Secret = ON: Value shows as ***** (click to reveal for 10 seconds)
  • Secret = OFF: Value visible in plaintext always

Best practice: Keep credentials, API keys, and passwords marked as secrets.

Revealing and Copying Secrets​

Reveal Secret Values​

When to use: Viewing masked values temporarily.

Steps:

  1. Find the masked variable (shows as *****)
  2. Click the eye icon in the Value column
  3. Value reveals for 10 seconds, then auto-hides

Security note: Use this sparingly in shared environments. The value is visible in the UI while revealed.

Copy to Clipboard​

When to use: Pasting values into other applications.

Steps:

  1. Click the copy icon in the Actions column
  2. Toast confirms: ✓ Copied to clipboard

Pro tip: Copy works even when values are masked - you don't need to reveal first.

Deleting Variables​

Delete Single Variable​

When to use: Removing one obsolete or incorrect variable.

Steps:

  1. Click the delete icon (trash) for the variable
  2. Confirm deletion in the modal: 
    Delete 1 variable?
    - API_KEY

    This action cannot be undone.
  3. Click "Delete"

Result: Variable is permanently removed from the bundle.

Delete Multiple Variables​

When to use: Cleaning up bulk imports or removing entire sections.

Steps:

  1. Check the checkbox for each variable to delete
  2. Click "Delete Selected" button
  3. Review the list in the confirmation modal
  4. Click "Delete X variables"

Example: Removing all staging variables at once:

☑ STAGING_DB_URL
☑ STAGING_API_KEY
☑ STAGING_REDIS_URL

→ Delete 3 variables

Safety: Deletion requires explicit confirmation and cannot be undone.

Searching and Filtering​

Search by Key​

When to use: Finding variables in large bundles (50+ variables).

Steps:

  1. Type in the search box at the top
  2. Results filter instantly (< 50ms)

Search behavior:

  • Case-insensitive
  • Matches any part of the key name
  • Real-time (no "Enter" required)

Examples:

Search: "db"     → Matches: DATABASE_URL, DB_HOST, REDIS_DB
Search: "stripe" → Matches: STRIPE_KEY, STRIPE_WEBHOOK_SECRET
Search: "prod"   → Matches: PROD_API_URL, PRODUCTION_MODE

Filter by Secret Status​

When to use: Viewing only secrets or only non-secrets.

Steps:

  1. Use the filter dropdown:
    • All Variables (default)
    • Secrets Only
    • Non-Secrets Only

Use cases:

  • Secrets Only: Audit which values are encrypted
  • Non-Secrets Only: Review configuration (non-sensitive values)

Combine Search + Filter​

Example: Find all production database secrets:

Search: "prod db"
Filter: Secrets Only

→ Shows: PROD_DB_URL, PROD_DB_PASSWORD

Exporting Variables​

Export to .env File​

When to use: Creating a local .env file for development.

Steps:

  1. Click "Export" dropdown
  2. Select "Export .env"
  3. File downloads: your-bundle-name.env

Content (masked by default):

API_KEY=*****
DATABASE_URL=*****
PUBLIC_URL=https://example.com

Security: Values marked as secrets are masked in exports. To reveal, use the API with ?reveal=1 (requires DEV_ALLOW_PLAINTEXT=1).

Export to JSON​

When to use: Programmatic integrations or backups.

Steps:

  1. Click "Export" dropdown
  2. Select "Export JSON"
  3. File downloads: your-bundle-name.json

Content:

{
  "API_KEY": "*****",
  "DATABASE_URL": "*****",
  "PUBLIC_URL": "https://example.com"
}

Best Practices​

Security​

  • ✓ Do: Mark credentials, API keys, and passwords as secrets
  • ✓ Do: Use the reveal feature sparingly (10-second auto-hide prevents shoulder surfing)
  • ✓ Do: Copy masked values directly (no need to reveal)
  • ✗ Don't: Export with reveal=1 in production environments
  • ✗ Don't: Store secrets in non-secret variables

Organization​

  • ✓ Do: Use consistent naming conventions: 
    Good: DATABASE_URL, REDIS_URL, STRIPE_API_KEY
    Bad:  db, redis-connection, stripeKey
  • ✓ Do: Group related variables with prefixes: 
    AWS_ACCESS_KEY_ID
    AWS_SECRET_ACCESS_KEY
    AWS_REGION
  • ✓ Do: Delete obsolete variables immediately

Performance​

  • ✓ Do: Use search/filter for bundles with 50+ variables
  • ✓ Do: Bulk import instead of adding one-by-one
  • ✓ Do: Use bulk delete for cleanup operations

Common Issues​

Issue: Import doesn't recognize my .env format​

Symptom: Variables don't import correctly or values are truncated.

Cause: The .env parser expects KEY=value format with optional quotes.

Solution: Ensure your .env file follows this format:

# ✓ Good
DATABASE_URL=postgres://localhost/db
API_KEY="quoted-value"

# ✗ Bad (will be skipped)
export DATABASE_URL=...  # "export" prefix not supported
DATABASE_URL : value     # colon instead of equals

Issue: Can't find a variable in a large bundle​

Symptom: Scrolling through 100+ variables is tedious.

Solution: Use the search box:

  1. Type part of the key name
  2. Results filter instantly
  3. Combine with "Secrets Only" filter if needed

Issue: Accidentally deleted a variable​

Symptom: Variable is gone after confirmation.

Cause: Deletion is permanent (no undo).

Solution:

  • Prevention: Always review the confirmation modal before clicking "Delete"
  • Recovery: Re-add manually or re-import from your original .env file

Issue: Secret value won't stay revealed​

Symptom: Value hides after 10 seconds.

Cause: Intentional security feature (auto-hide timer).

Solution:

  • Quick view: Click reveal again (repeatable)
  • Copy: Use the copy button (works even when masked)
  • Persistent access: Click "Edit" to see the value without auto-hide

Advanced Topics​

Handling Multi-line Values​

Use case: Storing SSH keys, certificates, or JSON configs.

Format:

PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA...
-----END RSA PRIVATE KEY-----"

Import behavior: Preserves newlines inside quotes.

Special Characters​

Supported characters:

PASSWORD=p@$$w0rd!#%^&*()
URL=postgres://user:pass@localhost:5432/db?sslmode=require

Escaping: No escaping needed inside quotes.

API-Based Management​

For automation: Use the REST API directly:

# Add variable
curl -X POST http://localhost:8888/api/v1/bundles/BUNDLE_ID/items \
  -H "Content-Type: application/json" \
  -d '{"key": "API_KEY", "value": "secret", "is_secret": true}'

# Delete variable
curl -X DELETE http://localhost:8888/api/v1/bundles/BUNDLE_ID/items/API_KEY

See API Reference: Bundles for full details.

Next Steps​

Now that you can manage variables, learn how to:

  • Organize Bundles - Best practices for bundle structure
  • CLI Approval Flow - Request variables from the terminal (coming soon)
  • Authentication - Manage your account and sessions

Additional Resources​

Feedback​

Found an issue with this guide? Open an issue or suggest improvements.