Ephemeral Environments

Zoi allows you to enter temporary, isolated development environments using the zoi shell --package (or -p) command. This is similar to nix shell or nix-shell -p.

Entering an Ephemeral Shell

To enter a shell with specific packages available in your PATH without installing them globally or to your project, use:

zoi shell -p eza bat fd

This command will:

1. Resolve the requested packages and their dependencies.
2. Install any packages that are not already in your Zoi store.
3. Create a temporary directory with symlinks to all the binaries.
4. Spawn a new subshell with this temporary directory added to your PATH.
5. Clean up by uninstalling any packages that were added specifically for this session when you exit the shell.

Running a Single Command

You can also run a specific command within an ephemeral environment and exit immediately:

zoi shell -p node@20 --run "node --version"

Detection & Prompt Integration

When you are inside a Zoi ephemeral shell, Zoi sets several environment variables that you can use to customize your prompt or scripts:

• IN_ZOI_SHELL: Always set to ephemeral.
• ZOI_SHELL_PACKAGES: A comma-separated list of the packages requested for the session.

Integration with Starship

If you use Starship, you can add a custom module to show when you are in a Zoi shell:

Add the following to your ~/.config/starship.toml:

[custom.zoi_shell]
description = "Show an indicator when inside a Zoi ephemeral shell"
command = "echo zoi"
when = "test -n \"$IN_ZOI_SHELL\""
symbol = "🌀 "
format = "on [$symbol$output]($style) "
style = "bold cyan"

Manual Shell Prompt (Bash/Zsh)

You can add a simple check to your .bashrc or .zshrc:

# Add to the beginning of your PS1/PROMPT if in a Zoi shell
if [[ -n "$IN_ZOI_SHELL" ]]; then
  PS1="(zoi-shell) $PS1"
fi

Automatic Cleanup

Zoi is designed to keep your system clean. When you exit an ephemeral shell (via exit or Ctrl-D):

• The temporary directory containing the binary shims is deleted.
• Newly added packages (those that weren't already installed globally or in another project) are automatically uninstalled from the Zoi store.
• Packages that were already present in your store are preserved, so your global tools are never accidentally removed.

This makes zoi shell -p the perfect way to test new tools or run scripts with different language versions without permanently cluttering your machine.