These docs are under active development and cover the v0.20 Kobicha security model.
Peios Learn
On this page
reference 2 min read

env

env runs a command with a changed environment — the set of NAME=VALUE variables a process inherits. Run with no command, it prints the current environment instead.

env [options] [NAME=VALUE]... [command [arg]...]

$ env LANG=C TZ=UTC my-program
$ env
PATH=/usr/local/bin:/usr/bin
HOME=/home/jack
...

How it works

You give env a list of NAME=VALUE assignments, then a command. env applies the assignments to its own environment and then runs the command, which inherits the result. The assignments affect only that one run — your shell's environment is untouched.

This is the clean way to run something with a particular variable set, without changing it for everything else, and the standard way to run a command with one variable temporarily different.

With no command, env simply prints the environment it would have used — which, with no options, is the current one.

Building the environment

Option Effect
-i, --ignore-environment Start from an empty environment, not the inherited one — so the command sees only what you assign. A bare - argument means the same.
-u, --unset=NAME Remove NAME from the environment.
--file=FILE Read NAME=VALUE lines from a .env-style FILE and apply them.

The order is: start (inherited, or empty with -i), apply --file, apply --unset, apply the NAME=VALUE arguments.

Running the command

Option Effect
-C, --chdir=DIR Change to DIR before running the command.
--argv0=NAME Run the command but present NAME as its zeroth argument.
-S, --split-string=S Split S into separate arguments. This exists for script interpreter lines, where everything after the interpreter arrives as one string.

Signal handling

env can adjust how the command treats signals before launching it:

Option Effect
--ignore-signal[=SIG] Set the named signals to be ignored.
--default-signal[=SIG] Reset the named signals to their default handling.
--block-signal[=SIG] Block delivery of the named signals while the command runs.
--list-signal-handling List the signal-handling changes the other options requested.

Other options

Option Effect
-0, --null When printing the environment, end each line with a NUL character instead of a newline. Not valid together with a command.
-v, --debug Print each processing step env performs.

Exit status

When env runs a command, it exits with that command's status. The exception is a failure in env itself:

Code Meaning
(command's own) The command ran; this is its exit status.
125 env itself failed — for example, a bad option.
126 The command was found but could not be run.
127 The command was not found.

See also