README

devkit-env-profiles

Named .env profiles, safe switching with backups, and drift reports — all from one Composer binary.

Table of Contents

• Why this exists
• Use case — switching environments in seconds
• Prerequisites
• Install
• Running the CLI
• Commands at a glance
• Configuration
• Files and folders
• Commands
  • save
  • use
  • list
  • delete
  • diff
  • merge
• Library API
• Development
• Support
• License

Why this exists

Managing several environments usually means several files: .env, .env.staging, secrets in CI, and the nagging question — "does production still match what we think?"

This tool gives you a small profile store under your repo, a predictable use workflow (with backups and optional post-switch hooks), and a diff command to compare any set of env files side by side or as JSON.

Use case — switching environments in seconds

Imagine a typical Laravel app: local dev uses SQLite and the local filesystem, staging uses MySQL and S3-compatible storage, production uses RDS Aurora, S3, and a Redis queue. Without a tool like this, switching means manually editing .env, hunting down the right values, and hoping you didn't leave APP_DEBUG=true pointing at production.

With devkit-env-profiles:

# One-time setup: snapshot each environment into a named profile
./vendor/bin/devkit-env save local
./vendor/bin/devkit-env save staging
./vendor/bin/devkit-env save production

Then switching is a single command — with an automatic backup and optional post-switch hooks (cache clear, migrations, etc.) running for you:

./vendor/bin/devkit-env use staging
# ✔ Backup of .env written to env/backups/
# ✔ staging profile applied to .env
# ✔ php artisan config:clear
# ✔ php artisan cache:clear

./vendor/bin/devkit-env use production
# ✔ Backup of .env written to env/backups/
# ✔ production profile applied to .env
# ✔ php artisan config:clear
# ✔ php artisan cache:clear
# ✔ php artisan migrate --force --no-interaction

And when something feels off, diff tells you exactly what diverged:

./vendor/bin/devkit-env diff local production --format side-by-side

KEY               local               production
────────────────────────────────────────────────
DB_CONNECTION     sqlite              mysql
FILESYSTEM_DISK   local               s3
QUEUE_CONNECTION  sync                redis
CACHE_DRIVER      file                redis
LOG_LEVEL         debug               — missing —

The profiles live outside version control (auto-added to .gitignore) so secrets never accidentally land in your repo.

Prerequisites

Install

composer require --dev devkit/env-profiles

composer install

Running the CLI

The CLI resolves paths and .devkit-env.json relative to the directory you run it from. Always run from your application root (where composer.json and usually .env live).

# Recommended
./vendor/bin/devkit-env --help

# Alternatives
composer exec devkit-env -- --help
php vendor/bin/devkit-env --help

Windows: use vendor\bin\devkit-env.bat or php vendor\bin\devkit-env.

Commands at a glance

Configuration

Drop a .devkit-env.json in your project root to customise store paths and post-switch hooks.

Note: defaultEnv and targetEnv only affect use. When save runs without --from, it always reads ./.env — not these keys.

{
  "storeDir": "env",
  "backupDir": "env/backups",
  "defaultEnv": ".env",
  "afterSwitch": [
    "php artisan config:clear",
    "php artisan cache:clear"
  ],
  "afterSwitchProfiles": {
    "production": [
      "php artisan migrate --force --no-interaction"
    ]
  }
}

{
  "afterSwitch": [
    "php artisan config:clear",
    "php artisan cache:clear"
  ],
  "afterSwitchProfiles": {
    "staging": [
      "php artisan route:clear"
    ],
    "production": [
      "php artisan optimize",
      "php artisan config:cache"
    ]
  }
}

./vendor/bin/devkit-env use staging      # runs afterSwitch + staging hooks
./vendor/bin/devkit-env use production   # runs afterSwitch + production hooks
./vendor/bin/devkit-env use staging --skip-hooks  # skip all hooks

Files and folders

env/                  <- profile store (storeDir)
  staging.env
  production.env
  registry.json       <- name -> filename map
  backups/            <- timestamped backups (backupDir)

On first save, use, list, or delete, the store and backups directories are automatically appended to .gitignore. You can safely commit .devkit-env.json (paths only) — keep secrets and env/ local.

Commands

save — snapshot a file into a named profile

./vendor/bin/devkit-env save staging                           # save ./.env as "staging"
./vendor/bin/devkit-env save staging --from .env.staging       # save a different file
./vendor/bin/devkit-env save staging --force                   # overwrite without prompting

Interactive (TTY): run save with no name to pick from a list or type a new one.

use — apply a profile to your working env file

./vendor/bin/devkit-env use staging                            # apply "staging"
./vendor/bin/devkit-env use staging --target .env.local        # write to a specific file
./vendor/bin/devkit-env use staging --backup-dir /tmp/envs     # custom backup location
./vendor/bin/devkit-env use staging --no-backup                # skip backup entirely

Interactive (TTY): run use without a name to pick from a numbered list.

list — show saved profile names

./vendor/bin/devkit-env list

Prints one name per line, or (no profiles saved yet) if the store is empty.

delete — remove a profile from the store

./vendor/bin/devkit-env delete staging          # prompts for confirmation
./vendor/bin/devkit-env delete staging --force  # skip confirmation

Interactive (TTY): run delete without a name to pick from a list.

diff — drift between env files

Compares a baseline against one or more targets: missing keys, extra keys, and mismatched values. Sensitive-looking values are masked by default.

# Using saved profiles
./vendor/bin/devkit-env diff local staging
./vendor/bin/devkit-env diff local staging production

# Using explicit file paths
./vendor/bin/devkit-env diff \
  --baseline=local \
  --env local=examples/env/local.env \
  --env staging=examples/env/staging.env \
  --env production=examples/env/production.env

# Output formats
./vendor/bin/devkit-env diff local staging --format text
./vendor/bin/devkit-env diff local staging --format json
./vendor/bin/devkit-env diff local staging --format side-by-side

# Masking
./vendor/bin/devkit-env diff local staging --no-mask
./vendor/bin/devkit-env diff local staging --mask-key 'APP_*' --mask-key 'STRIPE_*'

Exit codes: 0 = no drift  ·  1 = drift found  ·  2 = error

merge — combine two .env files

# Merge two saved profiles (interactive confirm before overwrite)
./vendor/bin/devkit-env merge local staging

# Merge explicit files to an output file
./vendor/bin/devkit-env merge \
  --left examples/env/local.env \
  --right examples/env/staging.env \
  --out merged.env

# Print to stdout
./vendor/bin/devkit-env merge --left .env --right .env.staging

# Non-interactive (CI-friendly)
./vendor/bin/devkit-env merge --left .env --right .env.staging -n --prefer right --out merged.env

# Dry run
./vendor/bin/devkit-env merge --left .env --right .env.staging --dry-run

# Tickbox selection mode (interactive checklist of right-side changes)
./vendor/bin/devkit-env merge --left .env --right .env.staging --select

Library API

Most users only need the CLI. If you want to integrate programmatically:

require __DIR__ . '/vendor/autoload.php';

// Devkit\Env\Diff\EnvFileParser
// Devkit\Env\Store\ProjectConfig::load()

Development

composer run tests
composer run standards:check

Support

If this project saves you time, consider buying me a coffee:

License

MIT