Xshe – Cross-Shell Environment Vars
xshe allows for setting Shell Environment Variables across multiple shells with a single TOML configuration file.
Simply write lines in a xshe.toml file like this:
CARGO_HOME = "~/.cargo"
Create a file like this once and use it everywhere, for every shell! xshe can convert this format into the format for every supported shell.
Installation
You can install xshe with Cargo (Rust's package manager) or with Homebrew (a package manager for macOS and Linux), provided you have one of them installed on your system.
If you don't have Cargo or Homebrew, or if you don't want to use either of them, you can also download the binaries for your system directly from GitHub, or install one of the two package managers before proceeding.
- Install Cargo/Rust for any platform
- Install Homebrew for macOS or Linux
Note: After installing xshe with Cargo or from a download, you might have to add the resulting xshe binary to your PATH. (what's that?)
With Cargo
If you have Cargo installed, use this command to install xshe from crates.io with Cargo:
cargo install -f xshe
With Homebrew
If you have Homebrew installed, it's recommended to install Xshe with Homebrew instead of Cargo.
Simply type:
brew install superatomic/xshe/xshe
As a File Download
Instead of using Cargo, you can download the latest release binary that corresponds with your system (or view all releases).
Make sure to add the xshe binary to your PATH, or remember to use the full path to the binary whenever you run xshe.
Setup
Creating a xshe.toml file
Create a file called xshe.toml in ~/.config. This is a TOML file that represents environment variables.
One variable is set per line. The file is read in order from top to bottom, so variables that appear earlier in the file can be used to define ones that appear later.
A typical line looks like this:
CARGO_HOME = "$XDG_DATA_HOME/cargo"
This will then be converted into the correct format for whatever shell is being used. For example, in bash, this line becomes:
export CARGO_HOME="$XDG_DATA_HOME/cargo";
While in fish, this line is:
set -gx CARGO_HOME "$XDG_DATA_HOME/cargo";
Dealing with PATH variables
To set variables that are arrays of values, like $PATH, use this syntax:
PATH = ["$PATH", "$BIN_HOME", "$CARGO_HOME/bin"]
xshe will join each element together based on the shell that is specified.
Shell Specific Environment Variables
To set environment variables for only one shell, add a .NAME prefix after the name of the environment variable, where NAME is one of bash, zsh, or fish. These environment variables will only be added if the given shell is used.
As an example, these lines make $HISTFILE be set to different values between different shells, and to have $ZSH_CACHE_DIR only be set in zsh, do this:
HISTFILE.bash = "$XDG_STATE_HOME/bash_history"
HISTFILE.zsh = "$XDG_STATE_HOME/zsh_history"
ZSH_CACHE_DIR.zsh = "$XDG_CACHE_HOME/oh-my-zsh"
You can use ._ instead of using a shell name to specify a default if an option doesn't apply to any of the shells. For example, these lines set the $EDITOR to nano on bash, but micro on everything else:
EDITOR.bash = "$(which nano)"
EDITOR._ = "$(which micro)"
Sourcing the xshe.toml file
Put the line corresponding to your shell in whatever file runs when loading environment variables. For bash, this is ~/.bash_profile, for zsh, this is ~/.zshenv, and for fish, this is ~/.config/fish/config.fish.
Bash
eval "$(xshe bash)"
Zsh
eval "$(xshe zsh)"
Fish
xshe fish | source
Use without xshe on PATH
If xshe isn't on your PATH (this is the cause of the error command not found: xshe), you will have to manually type out the location:
eval "$(/path/to/xshe zsh)"
Options
Using --file (or -f)
To specify a custom file that is not located at ~/.config/xshe.toml, pass the --file option, like so:
eval "$(xshe zsh --file ~/some/other/location.toml)"
Using --text (or -t)
To directly specify TOML to parse as a config file, use --text.
For example, this line directly parses the provided line and converts it to zsh:
xshe zsh --text 'BIN_HOME = "$HOME/.local/bin"'
Using --pipe (or -p)
To pass a TOML configuration from the standard input, use --pipe.
As an example, this command concatenates two files named global_xshe.toml and user_xshe.toml by using cat, and then pipes the output into xshe to be parsed:
cat global_xshe.toml user_xshe.toml | xshe zsh --pipe
Other CLI Options
Output Verbosity
You can control how much info is displayed when Xshe is run. The default behavior is to only display errors and warnings.
While this default behavior is recommended, you can customize it by using the following flags:
-qqsilences all output (this silences errors and is not advised)-qor--quietshows only errors and hides warnings-vor--verboseshows info messages-vvshows debug logs-vvvshows trace logs
Help and Version Information
Run xshe --help to display command usage.
Run xshe --version to display version information.
License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or opensource.org/licenses/MIT)
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
15 Apr 10, 2023
2 Jan 4, 2022
65 Sep 8, 2022
536 Apr 16, 2023
4 Dec 11, 2023
6 Dec 16, 2022
135 Dec 4, 2022
6 Apr 9, 2024
4 Dec 12, 2021
1 Apr 5, 2022
8 Nov 4, 2021
524 Dec 26, 2022
3 Mar 30, 2024
1 Jan 23, 2022
1 Apr 10, 2022
22 Sep 16, 2023
1 Jan 12, 2022
5 May 2, 2024