envprof

Profile-based environment variable manager

envprof is a CLI tool for managing named environment profiles in YAML or TOML.

• Define multiple environment profiles in a single YAML or TOML file, with templating, inheritance and dotenv support
• List profiles, write to .env files or export to the current shell, execute a command or spawn a subshell with the selected environment

Installation

curl -sSL https://raw.githubusercontent.com/idelchi/envprof/refs/heads/main/install.sh | sh -s -- -d ~/.local/bin

Usage

# list all profiles
envprof profiles

# list all variables in a profile with inheritance information
envprof --profile dev list -v

# list a specific variable
envprof --profile dev list HOST

# write profile to a file
envprof --profile dev write .env

# spawn a subshell with the environment loaded
envprof --profile dev shell

# export to current shell
eval "$(envprof --profile dev export)"

# Execute a command with the profile's environment
envprof --profile dev exec -- ls -la

# or via stdin
echo "ls -la" | envprof --profile dev exec -

Configuration

Each profile supports the following keys:

• default – mark this profile as the default if --profile is not given
• output – file to write with the write subcommand (defaults to <profile>.env)
• extends – list of other profiles or .env files to inherit from
• env – environment variables defined directly in this profile

Extends

Entries can point to either profiles or dotenv files:

• profile:<name> – another profile
• dotenv:<path> – a dotenv file

If the prefix is omitted, profile: is assumed.

⚠️ If your profile name contains a :, always use the explicit profile: form.

Dotenv paths are resolved relative to the current working directory unless absolute. Globs are supported (see filepath.Glob).

Env

• Scalars (strings, numbers, booleans) are emitted as plain strings.
• Complex values (arrays, maps) are serialized as compact JSON and wrapped in single quotes.

Example:

env:
  PORT: 5432
  FEATURES:
    - x
    - y
  CONFIG:
    foo: bar

→

PORT=5432
FEATURES='["x","y"]'
CONFIG='{"foo":"bar"}'

Templating

The entire configuration file is processed as a Go template:

• Access environment variables with {{ .HOME }}
• Use any function provided by slim-sprig

The environment variables available for templating come from your runtime environment (the process' os.Environ), not from profiles.

In addition, the following are always defined:

• ENVPROF_FILE, the path to the config file
• ENVPROF_DIR, the directory containing the config file

YAML

dev:
  default: true
  output: development.env
  extends:
    - staging
  env:
    HOST: localhost

staging:
  extends:
    - prod
    - dotenv:secrets.env
  env:
    HOST: staging.example.com
    DEBUG: true

prod:
  env:
    HOST: prod.example.com
    PORT: 80
    DEBUG: false

The env key alternatively accepts a sequence of key-value pairs:

dev:
  env:
    - HOST=localhost
    - DEBUG=true

TOML

[dev]
default = true
output = 'development.env'
extends = ['staging']
[dev.env]
HOST = 'localhost'

[staging]
extends = ['prod', 'dotenv:secrets.env']
[staging.env]
DEBUG = true
HOST = 'staging.example.com'

[prod.env]
DEBUG = false
HOST = 'prod.example.com'
PORT = 80

Inheritance Behavior

Inheritance is resolved in order: later imports override earlier ones.

As an example, running envprof --profile dev write .env with the previous YAML definition as well as a sample secrets.env:

TOKEN=secret

produces the following .env file:

# Active profile: "dev"
DEBUG=true
HOST=localhost
PORT=80
TOKEN=secret

envprof --profile dev list -v shows the variables and their origins:

DEBUG=true              (inherited from "staging")
HOST=localhost
PORT=80                 (inherited from "prod")
TOKEN=secret            (inherited from "staging" -> "secrets.env")

The layering order here is:

prod -> secrets.env -> staging -> dev

from lowest to highest priority (left to right).

envprof --profile dev list --dry will visualize the layering as a table:

Flags

All commands accept the following flags:

--file, -f      - Specify the profile file(s) to load
--profile, -p   - Specify the profile to use
--overlay, -o   - Overlay other profiles
--verbose, -v   - Increase verbosity

--file can be used to specify a file (or a list of fallback files) to load. Defaults to the first found among envprof.yaml, envprof.yml, or envprof.toml in the current folder or in ~/.config/envprof, unless ENVPROF_FILE is set.

--profile specifies the profile to activate. If no profile is specified, the default profile will be used (if it exists).

--overlay allows you to specify additional profiles to overlay on top of the selected profile.

--verbose increases verbosity, see subcommands for details.

Subcommands

For details, run envprof <command> --help for the specific subcommand.

Shell integration

When using the shell subcommand, envprof sets ENVPROF_ACTIVE_PROFILE in the environment.

This variable is used to detect if you’re already in an envprof subshell, preventing nested sessions.

Prompt

Use ENVPROF_ACTIVE_PROFILE to customize a starship prompt:

starship.toml

[env_var.envprof]
variable = "ENVPROF_ACTIVE_PROFILE"
format = '[\[envprof: $env_value\]]($style)'
style = 'bold bright-green'

Demo