Skip to main content

Bundles

Bundles are named collections of keys that help you organize environment variables by project, environment, or purpose.

What is a Bundle?​

A bundle groups related keys together under a meaningful name:

  • Example: dev/api - Development environment for API service
  • Example: prod/database - Production database credentials
  • Example: staging/frontend - Staging environment for frontend app

Bundle Structure​

Each bundle contains:

  • Name - Unique identifier (e.g., dev/api, prod/db)
  • Description - Optional documentation
  • Attached Keys - References to keys in your library
  • Key Order - Custom ordering (optional)

Benefits​

Organization

  • Group keys by environment (dev, staging, prod)
  • Separate keys by service (api, frontend, worker)
  • Organize by purpose (database, auth, features)

Reusability

  • Same key can be in multiple bundles
  • Update key once, affects all bundles

Convenience

  • Request entire bundle with one CLI command
  • Approve and inject all variables at once

Creating Bundles​

Via Web UI​

  1. Go to https://env.cat/bundles
  2. Click "+ Create Bundle"
  3. Fill in details:
    • Name: dev/api (use / for namespacing)
    • Description: "Development environment for API service"
  4. Click "Create"

Naming Best Practices​

Use hierarchical names:

✅ dev/api
✅ staging/frontend
✅ prod/database
✅ team-alpha/service-x

❌ dev_api
❌ api-dev
❌ DevAPI

Common patterns:

{environment}/{service}
  - dev/api
  - staging/api
  - prod/api

{team}/{project}
  - team-alpha/mobile-app
  - team-beta/analytics

{service}/{environment}
  - api/dev
  - api/prod
  - frontend/dev

Via API​

curl -X POST https://env.cat/api/v1/bundles \
  -H "Content-Type: application/json" \
  -d '{
    "name": "dev/api",
    "description": "Development environment for API service"
  }'

Attaching Keys​

Method 1: From Bundle Page​

  1. Open your bundle (e.g., https://env.cat/bundles/dev-api)
  2. Click "Attach Keys"
  3. Select keys from your library:
    • DATABASE_URL
    • REDIS_URL
    • API_KEY
    • PORT
  4. Click "Attach"

Method 2: From Key Page​

  1. Go to a key detail page
  2. Click "Add to Bundle"
  3. Select bundle (e.g., dev/api)
  4. Click "Add"

Reordering Keys​

Drag and drop keys to reorder them. The order affects:

  • CLI output (variables exported in order)
  • .env file generation
  • Approval UI display

Example order:

1. DATABASE_URL     (infrastructure first)
2. REDIS_URL
3. API_KEY          (auth keys)
4. JWT_SECRET
5. PORT             (config last)
6. LOG_LEVEL

Managing Bundles​

View Bundle Details​

  1. Go to https://env.cat/bundles
  2. Click on a bundle name
  3. See:
    • All attached keys (values masked)
    • Key count
    • Created/updated timestamps
    • "Try It Out" terminal

Edit Bundle​

  1. Open bundle details page
  2. Click "Edit"
  3. Update name or description
  4. Click "Save"

Note: Renaming a bundle updates its identifier. CLI commands using the old name will fail until updated.

Delete Bundle​

Warning: This removes the bundle but does NOT delete the keys (they remain in your library).

  1. Open bundle details page
  2. Click "Delete"
  3. Confirm deletion

Keys can be reused in other bundles or new bundles.

Detach Keys​

Remove a key from a bundle without deleting it:

  1. Open bundle details page
  2. Click the × next to a key
  3. Confirm detachment

The key remains in your library and other bundles.

Using Bundles​

Request via CLI​

Request all keys in a bundle:

envcat get --bundle dev/api --api-base https://env.cat

Output:

export DATABASE_URL='postgres://...'
export REDIS_URL='redis://...'
export API_KEY='sk_live_abc123'
export PORT='3000'

Request Specific Keys​

Request only some keys from a bundle:

envcat get --bundle dev/api --keys DATABASE_URL,REDIS_URL --api-base https://env.cat

Output:

export DATABASE_URL='postgres://...'
export REDIS_URL='redis://...'

Write to .env File​

envcat get --bundle dev/api --api-base https://env.cat --file .env

Creates .env:

DATABASE_URL=postgres://...
REDIS_URL=redis://...
API_KEY=sk_live_abc123
PORT=3000

Import & Export​

Export Bundle​

Format: ENV

  1. Open bundle details page
  2. Click "Export" → ".env"
  3. Choose:
    • Masked (default): DATABASE_URL=••••••••
    • Revealed (dev mode): DATABASE_URL=postgres://...

Download: dev-api.env

Format: JSON

{
  "name": "dev/api",
  "description": "Development environment",
  "keys": [
    {
      "name": "DATABASE_URL",
      "value": "postgres://...",
      "is_secret": true
    },
    {
      "name": "PORT",
      "value": "3000",
      "is_secret": false
    }
  ]
}

Import from File​

From .env:

  1. Go to bundles page
  2. Click "Import" → "From .env"
  3. Upload file or paste contents: 
    DATABASE_URL=postgres://...
    API_KEY=sk_live_abc123
    PORT=3000
  4. Specify bundle name (e.g., imported/from-env)
  5. Mark secrets (toggle "Secret" for sensitive values)
  6. Click "Import"

env.cat will:

  • Create keys in your library (if they don't exist)
  • Create the bundle
  • Attach all keys to the bundle

From JSON:

Similar to .env import, but with structured data including is_secret flags.

Try It Out​

Every bundle has a "Try It Out" terminal for testing the CLI flow without leaving your browser.

How it works:

  1. Open bundle details page
  2. Click "Try It Out"
  3. Terminal drawer opens with pre-filled command: 
    envcat get --bundle dev/api --api-base https://env.cat
  4. Click "Run"
  5. CLI runs in browser (simulated)
  6. Approval page opens automatically
  7. Approve → see variables injected

Perfect for:

  • Testing the approval flow
  • Verifying bundle contents
  • Demoing to team members
  • Learning CLI commands

Learn more →

Bundle Patterns​

By Environment​

dev/api       - Development API
staging/api   - Staging API
prod/api      - Production API

Use case: Same keys, different values per environment.

By Service​

api/database      - API database credentials
api/redis         - API cache credentials
api/auth          - API auth keys

Use case: Separate concerns within one service.

By Team​

team-alpha/mobile
team-beta/web
team-gamma/backend

Use case: Multi-tenant setup with team isolation.

By Purpose​

database/postgres   - PostgreSQL credentials
database/mongo      - MongoDB credentials
cache/redis         - Redis credentials
auth/jwt            - JWT secrets

Use case: Organize by infrastructure component.

Advanced Features​

Bundle Templates​

Coming soon:

  • Save bundle as template
  • Create new bundles from templates
  • Share templates across tenants

Version History​

Coming soon:

  • Track bundle changes over time
  • Rollback to previous key sets
  • Audit who changed what

Bundle Sharing​

Coming soon (SaaS):

  • Share bundles with team members
  • Role-based access (read-only, edit)
  • Audit logs for bundle access

Troubleshooting​

Can't Create Bundle​

Issue: "Bundle name already exists"

Solution:

  • Bundle names must be unique within your tenant
  • Use a different name or namespace (e.g., dev/api-v2)
  • Or delete the existing bundle first

Bundle Empty After Import​

Issue: Imported .env but bundle has no keys

Solution:

  • Check .env file format (KEY=VALUE, no quotes needed)
  • Ensure file isn't empty
  • Look for import errors in UI toast notifications

CLI Can't Find Bundle​

Issue: envcat get --bundle dev/api returns "not found"

Solution:

  • Verify bundle name matches exactly (case-sensitive)
  • Check you're logged into correct tenant
  • Ensure --api-base points to correct environment

Best Practices​

Naming​

  • Use consistent naming conventions across team
  • Include environment in name (dev/, prod/)
  • Use / for logical grouping
  • Keep names short but descriptive

Organization​

  • One bundle per service + environment combo
  • Separate secrets from config when possible
  • Document bundle purpose in description field

Security​

  • Don't create "all secrets" bundles (reduce blast radius)
  • Use specific bundles for specific purposes
  • Regularly audit bundle contents
  • Remove unused bundles

Workflow​

  • Create dev bundles first (test the flow)
  • Clone to staging/prod (update values)
  • Use CLI to verify all bundles work
  • Document bundle relationships

Next Steps​

Now that you understand bundles:

  1. Approval Flow - Learn how secrets are delivered
  2. Try It Out - Test the CLI in your browser
  3. CLI Reference - Master CLI commands
  4. Keys Guide - Deep dive into key management

Need Help?​