envprof

README

envprof

Profile-based environment variable manager

---

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

Supports profile inheritance (layering) and importing of .env files.

Features

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

Installation

For a quick installation, you can use the provided installation script:

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

Usage

# list all profiles
envprof list

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

# list a specific variable
envprof list dev HOST

# write profile to a file
envprof env dev .env

# spawn a subshell with the environment loaded
envprof shell dev

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

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

Format

Complex types (arrays, maps) are serialized as JSON; all other values are simple strings.

YAML

dev:
  dotenv:
    - secrets.env
  extends:
    - staging
  env:
    HOST: localhost

staging:
  extends:
    - prod
  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]
extends = ['staging']
dotenv = ['secrets.env']
[dev.env]
HOST = 'localhost'

[staging]
extends = ['prod']
[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 profiles override earlier ones. dotenv files have the lowest priority and load first, before applying profile layers.

As an example, running envprof env dev .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 list dev -v shows the variables and their origins:

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

The layering order here is:

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

from lowest to highest priority (left to right).

Flags

All commands accept the following flag:

--file, -f

which 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, unless ENVPROF_FILE is set.

Subcommands

list / ls — List profiles or variables

• Usage:

  • envprof list [--verbose/-v] [profile] [variable]

• Flags:

  • --verbose, -v – Show variable origins
  • --oneline, -o – Emit variables on a single line

export / x — Export profile to stdout

• Usage:

  • envprof export [--prefix <string>] <profile>

• Flags:

  • --prefix – String to prefix variables (default: export )

write / w — Write profile(s) to file(s)

• Usage:
  • envprof write [profile] [file]

shell / sh — Spawn a subshell with profile

• Usage:

  • envprof shell [--isolate/-i] [--shell <string>] <profile>

• Flags:

  • --shell, -s – Force shell (default empty string -> detected)
  • --isolate, -i – Prevent inheriting current shell variables
  • --path, -p – Include the current PATH in the environment

exec / ex — Execute a command with profile

• Usage:

  • envprof exec [--isolate/-i] [--path/-p] <profile> <command> [args...]

• Flags:

  • --isolate, -i – Prevent inheriting current shell variables
  • --path, -p – Include the current PATH in the environment

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'

Function

For convenience, you can define a shell function to quickly switch profiles:

envprof-activate() {
  local output
  if output="$(envprof export "${1}" 2>&1)"; then
    eval "${output}"
  else
    echo "${output}" >&2
  fi
}

Use envprof-activate dev to switch to the dev profile.

[!NOTE] This will export variables into your current shell, potentially overwriting existing ones. Repeated use will also mix the variables from different profiles, as it won't unset them.

Demo

Documentation

Overview

Command envprof is a command-line tool for managing environment variables in profiles.