Know your shell setup.

Plain shell files, a few useful helpers, and explicit choices about what runs.

Start with the macOS guide or Linux guide. EnvManager supports Bash and Zsh on both platforms. The repository also documents Android's separate manual installation.

Installation behavior

The installer reuses recognized installations and preserves local choices. New installations use the core preset. That preset includes environment initialization, user binary directories, and shared telemetry preferences; it disables the optional tool recipes. The full preset enables those recipes for future shell loads and is intended for users who have reviewed them.

Existing standalone HOME/tilde loader hooks are adopted in place, preserving their original command and startup order. The installer can repair a legacy hook plus the duplicate managed block appended by v0.1.0. Unfamiliar active references, multiple legacy hooks, conflicting markers, and edited managed blocks stop migration for inspection before edits begin. Planning never evaluates shell configuration.

Keep paths in order

Use em_add_path VARIABLE entry [mode] with PATH, MANPATH, CDPATH, or another colon-separated variable. Entries are literal and do not have to exist. Every successful call exports the variable in your current shell.

# Append an entry, or keep it where it already is (the default).
em_add_path PATH "$HOME/bin"

# Prepend an absent entry; keep an existing entry in place.
em_add_path PATH "$HOME/tools/bin" prepend

# Put this entry first, removing its other copies.
em_add_path PATH "$HOME/preferred/bin" prepend-move

# Preserve system manual paths, including when MANPATH was unset.
em_add_path MANPATH "$HOME/share/man"

Other entries retain their order. Existing empty components are preserved. Empty entries, entries containing a colon, invalid variable names, and unknown modes return status 2.

Choose modules deliberately

em_status
em_disabled_scripts
em_enable nvm python
em_disable tmux

# Apply configuration again in this shell, when intended.
em_load_scripts

Enable and disable operations change future loads; enabling does not immediately run an installer. Names omit the numeric prefix and platform suffix: em_disable gpg covers its OS variants. Optional modules include Node/NVM, Python, pnpm, tmux, SDKMAN, and tool-specific environment settings. Some modules install software or clone configuration; inspect the corresponding script before enabling it.

Local configuration

Set explicit environment preferences before the loader runs. Tool path helpers preserve nonempty values and reuse existing tool homes before selecting new XDG locations. Keep machine-specific code in a top-level *.local.sh file in your checkout; these files are ignored by Git.

Eligible scripts load in global filename order. A matching 01-example.local.sh sorts before 01-example.sh; local suffixes do not imply a later override pass. Use a later numeric prefix when you need a later assignment.

Limit concurrent commands

# At most two invocations share this slot group across shells.
em_run_concurrent --key builds 2 npm run build

# Without a key, the exact command and arguments identify the group.
em_run_concurrent 1 -- my-command "argument with spaces"

Waiting commands run when a slot opens. Use the same limit for each invocation sharing a key. Commands keep their arguments, I/O, and exit status, and execute in a subshell. Changes to variables or directories do not propagate to the caller. This is a single-host limit; nesting the same key can deadlock when all slots are held.

Startup timing in Zsh

Interactive Zsh startup reports commands exceeding the configured timing budget at the first prompt. Set ENVMANAGER_BENCHMARK=false before loading EnvManager to disable it, or change ENVMANAGER_BENCHMARK_BUDGET_MS. Noninteractive shells remain quiet. The repository guide explains the measured scope and tracing overhead.

Troubleshooting

• Missing Git or downloader: install Git and curl or wget, then rerun the installer.
• Missing startup integration: rerun the original command with the same shell selection. An installed release is reused.
• Modified checkout during upgrade: preserve or commit local changes first. Keep personal scripts in ignored *.local.sh files.
• Installer lock: a live installer keeps its lock. A stale PID lock is recovered on the next run; an incomplete or unexpected lock asks for inspection.
• Module failure: disable the named module and check its prerequisites and source. The core preset is the small starting point.
• Unmatched managed markers: inspect the marked block in the reported file. The installer stops instead of discarding the rest of that file.

For the complete implementation and platform policy, read the source repository. For release history and checksums, visit GitHub Releases.