envx
Run a program in a modified environment, or print the environment.
Mirrors GNU env. Run it as envx, or as gnux envx.
Synopsis
envx [OPTION]... [-] [NAME=VALUE]... [COMMAND [ARG]...]GNU reference
Description
envx sets each NAME to VALUE in the environment and runs COMMAND with the remaining arguments; without a COMMAND it prints the resulting environment, one NAME=VALUE per line. -i (or a lone '-') starts from an empty environment, -u removes a variable, -C changes the working directory for the command and -S splits a single string into arguments, which is what makes options usable on a '#!' line. Printed variables keep their inherited order: assigning an existing name replaces it in place, and new names are appended. COMMAND is looked up on the PATH of the modified environment. Where GNU env replaces itself with the command, envx runs it as a child process connected to the same standard streams and exits with the command's status, so the behavior is identical on platforms that cannot replace a running process. The exit status is 125 if envx itself fails, 126 if COMMAND is found but cannot be run, 127 if COMMAND cannot be found, and otherwise the exit status of COMMAND (128 plus the signal number when a signal killed it).
gnux's terminal view (BR-13): on a terminal, a listing of the environment has each name colored apart from its value and the '=' dimmed, and the ':' between the directories of PATH and every other *PATH variable dimmed too; the text is GNU's. The view's options must come before any assignment or -S string. --pretty[=WHEN] and --theme=NAME, options of gnux's own, choose the view (GNUX_PRETTY, GNUX_THEME); -0 and piped or redirected output are always GNU's.
Permissions
Printing the environment needs no permissions. Running a command needs execute permission on the program and search permission on the directories leading to it, plus search permission on the -C directory when one is given.
Use cases
- Setting variables for a single command in a way that works in every shell.
- Running a command with a clean, reproducible environment using
-i. - Locating an interpreter through PATH on a '#!' line, with arguments via
-S. - Dumping the environment for debugging, or NUL-separated with -0 for safe parsing.
- Removing a variable that changes a program's behavior (DEBUG, GOFLAGS, LANG) for one run with
-u. - Running a command in another directory with
-Cwithout changing the caller's directory. - Cross-compiling or configuring builds with per-command variables such as GOOS and GOARCH.
- Checking how a command fails: 127 when it is not found, 125 when
envxitself fails. - Tracing exactly which environment and arguments a command receives with
-v. - Running the
gnuxmulti-call binary as a chosen tool by setting its zeroth argument with-a.
Flags
-a, --argv0 ARG pass ARG as the zeroth argument of COMMAND
-C, --chdir DIR change working directory to DIR
-v, --debug print verbose information for each processing step
--help display this help and exit
-i, --ignore-environment start with an empty environment
-0, --null end each output line with NUL, not newline
--pretty WHEN[="always"] the gnux terminal view WHEN: 'always' (the default when WHEN is omitted), 'auto' (the default: on a terminal only), or 'never'; GNUX_PRETTY sets the default
-S, --split-string S process and split S into separate arguments;
used to pass multiple arguments on shebang lines
--theme NAME color the view with the built-in theme NAME (gnux theme picks and saves one); GNUX_THEME sets the default
-u, --unset NAME remove variable NAME from the environment
--version output version information and exitExamples
Print the current environment
envxShow only the first few variables
envx | headx -n 3Run a command with extra variables
envx GOOS=windows GOARCH=amd64 go build ./...Check that an assignment is appended to the printed environment
envx GREETING=hello | tailx -n 1Run a command with nothing but the variables given
envx -i PATH=/usr/bin HOME=/tmp make testPrint an empty environment plus a single variable
envx -i LANG=C.UTF-8Drop variables for one command (-u may be repeated)
envx -u HOME -u USER gnux shell -c 'echox "[$HOME] [$USER]"'Drop a variable and run in another directory
envx -u DEBUG -C build ./configureRun a tool in another directory without leaving this one
envx -C build pwdxPrint the environment NUL-separated, with the NULs made visible
envx -0 -i A=1 B=2 | catx -vSplit one string into a command and its arguments, as on a '#!' line
envx -S 'gnux shell -e' build.shTrace each step envx takes before running the command
envx -v -C build pwdxRun the gnux binary as rmx by setting its zeroth argument
envx -a rmx gnux -v old.logTell a missing command (status 127) from a failing one
envx no-such-command; echox "status: $?"Set a variable for a command run from the gnux shell
gnux shell -c 'envx GREETING=hi envx | tailx -n 1'Options
Each option has a page of its own, with its usage and examples.
- -a, --argv0: Pass ARG as the zeroth argument of COMMAND.
- -C, --chdir: Change working directory to DIR.
- -v, --debug: Print verbose information for each processing step.
- -i, --ignore-environment: Start with an empty environment.
- -0, --null: End each output line with NUL, not newline.
- --pretty: The
gnuxterminal view WHEN: 'always' (the default when WHEN is omitted), 'auto' (the default: on a terminal only), or 'never'; GNUX_PRETTY sets the default. - -S, --split-string: Process and
splitS into separate arguments; used to pass multiple arguments on shebang lines. - --theme: Color the view with the built-in theme NAME (
gnuxtheme picks and saves one); GNUX_THEME sets the default. - -u, --unset: Remove variable NAME from the environment.
Exit status
| Status | Meaning |
|---|---|
| 0-124, 128+ | the exit status of COMMAND (on Unix, 128+N when it is killed by signal N); with no COMMAND, 0 |
| 125 | envx itself failed: a bad option, a variable it could not unset, a directory it could not enter (-C), a write error |
| 126 | COMMAND was found but could not be run |
| 127 | COMMAND was not found |
Help in the terminal
envx --help # options, first examples, exit status
gnux help envx # this page: the full manual
gnux help envx --OPTION # one option in depth, with its examples