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, write to .env files or export to 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 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

Format

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

Non-scalars are emitted as minified JSON wrapped in single quotes.

YAML

dev:
  # Default profile to use when none is set with `--profile`
  default: true
  # Default output name for the `write` subcommand if not overridden by arguments
  output: development.env
  # Extend from other profiles
  extends:
    - staging
  env:
    HOST: localhost

staging:
  extends:
    - prod
  # Import dotenv files (relative to the current directory), supporting environment variables
  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 profile to use when none is set with `--profile`
default = true
# Default output name for the `write` subcommand if not overridden by arguments
output = 'development.env'
# Extend from other profiles
extends = ['staging']
[dev.env]
HOST = 'localhost'

[staging]
extends = ['prod']
# Import dotenv files (relative to the current directory), supporting environment variables
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 profiles override earlier ones. Within each profile, dotenv files load before that profile’s environment variables.

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 "secrets.env")

The layering order here is:

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

from lowest to highest priority (left to right).

Flags

All commands accept the following flags:

--file, -f      - Specify the profile file(s) to load
--profile, -p   - Specify the profile to use
--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, 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).

--verbose increases verbosity, see subcommands for details.

Subcommands

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

profiles / profs — List all profiles

• Usage:

  • envprof profiles

• Flags:

  • --verbose, -v – Mark active profile with asterisk

list / ls — List profile or the value of a variable in a profile

• Usage:

  • envprof list [flags] [variable]

• Flags:

  • --oneline, -o – Emit variables on a single line (implies --verbose=false)
  • --verbose, -v – Show variable origins

export / x — Export profile to stdout

• Usage:

  • envprof export [flags]

• Flags:

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

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

• Usage:

  • envprof write [flags] [file]

• Flags:

  • --all, -a – Write all profiles

shell / sh — Spawn a subshell with profile

• Usage:

  • envprof shell [flags]

• Flags:

  • --shell <shell>, -s <shell> – 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 [flags] -- <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'

Demo

Documentation

Overview

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