Envi - Environment Initialiser

Home Download SourceForge Project

Scripts are great for automating tasks, but a slight change in environment (e.g., running as a different user, or running from cron or Task Scheduler) can cause a script to fail. Envi is a multi-platform tool which ensures your script's environment is the same every time no matter where it's invoked from.

Envi also provides an easy way to run your automated tasks. Just drop tasks into the tasks directory, then run them on the command line with `envi taskname`. You can run tasks from any environment because envi always tears down the current environment and builds up the correct one before executing a task.

Envi lets you create playlists to execute a list of tasks with a single command. Once you've created a playlist, you can run it on the command line with `envi myplaylist`.

Envi can also control the environment of your terminal. Running `envi my-task env bash` gives you a command line prompt with the special environment of my-task (replace 'bash' with 'cmd' on Windows). You can use this for, among other things, debugging task environments.

Envi lets you create task aliases, so a single task can be called by different names. This allows for variations of tasks because a task can check the name it was called with and change its behavior or environment accordingly.

Envi is great for running multiple versions of a particular piece of software on the same machine. For example, you could install a series of JDKs and create a task for each, with adjusted values for JAVA_HOME and PATH. Now you can run, for example, `envi java5 env bash` and start compiling things with java v5, or `envi java6 env bash` and start compiling things under java v6.

Envi actually helps to keep your user profile environment clean too. If you use a particular program solely in automated tasks (e.g., a C++ compiler), you could install it into the appropriate envi environment(s), but leave it out of your main working environment.

Envi tasks can also take command line arguments. However, using this feature is not recommended if you can avoid it, as it defeats the purpose of envi!


Prerequisites: You need perl to run envi, and you need subversion to check it out.

  1. Download and uncompress envi to a sensible location like "C:\Program Files\envi" on Windows, or "/usr/local/envi" on Linux.

  2. For convenience, you should add the bin directory to the PATH variable of your system or user profile, to allow you to run `envi` on the command line. You can skip this step, but you will have to run envi by its full path ("C:\Program Files\envi\bin\envi", or "/usr/local/envi/bin/envi"). Under Linux add this line to your profile:

    export PATH=/usr/local/envi/bin:$PATH
    Under Windows, use Control Panel to append ";C:\Program Files\envi\bin" to the PATH environment variable.

  3. Give envi a base environment. This will be the starting point for all task environments. Create the file envi/etc/environment.pl, and using perl code, define a base PATH. E.g., for Linux:

    $ENV{'PATH'} = "/bin:/usr/bin";
    And for windows:
    $ENV{'PATH'} = "C:\Windows;C:\Windows\System32;C:\Program Files\Perl\bin";

    Note: The perl interpreter must be on the PATH specified here.

Now you can test your installation of envi using the basic commands below.

Basic Envi Commands

To get display welcome message and a version number, run:


To get a dump of you base environment, run:

envi env

Creating Tasks

A task can go in one of two places, depending on who it should be visible to:

  1. envi/etc/tasks - visible to any user.
  2. YOUR_HOME_DIRECTORY/.envi/tasks - visible only to you.

Note: "YOUR_HOME_DIRECTORY" above means the folder allocated by your operating system for your user files. On Vista, it's "C:\Users\username". On XP it's "C:\Documents and Settings\username". On Linux it's usually "/home/username".

Note: For (2), you will need to create the '.envi' and '.envi/tasks' directories yourself.

Tasks take the form of a directory containing a set of perl scripts and other files:


This file is the perl script that gets executed when you run the task. An (overly simple) example:

print "This is my first task\n";

If you don't like writing perl code, just have task.pl call another script or executable. To do this, you can use the $ENV{'TASK_HOME'} variable, which always contains the path to the task directory. E.g., to call a shell script (task.sh), put it in the directory alongside task task.pl and add this to task.pl:

system( "$ENV{'TASK_HOME'}/task.sh" );


This file is a perl script that sets up the environment for the task. It should modify the ENV hash to build up the environment as needed. Keep in mind that the starting point for the environment is the base environment defined in 'envi/etc/environment.pl'. E.g.:

$ENV{'JAVA_HOME'} = "/opt/jdk1.6.0_12";
$ENV{'PATH'} = "$ENV{'JAVA_HOME'}/bin:$ENV{'PATH'}";

If you don't like writing perl code, or if you have existing scripts which modify the environment, then you can make use of the 'source_bash_script' and 'source_batch_script' functions within environment.pl. These functions execute the given script and allow it to modify the task environment. E.g.:



This file contains a list of aliases for the task, one per line. If this file does not exist, then the task is taken to have exactly one name which is the name of the directory the task is contained in.

Note: If aliases.txt exists, the name of the task directory will not be automatically taken as one of the names for the task. If you want the task to be callable by the name of the task directory, please add this name to aliases.txt.

Running Tasks

To view a list of available tasks, run:

envi tasks

Once your tasks are in place, you can run a selected task with:

envi taskname

To get a dump of the environment for a particular task, run:

envi taskname env

To run an arbitrary executable (binary file, script etc.) in the environment of a particular task, run:

envi taskname env /path/to/executable

Therefore, to get an interactive command prompt, initialised with the environment of a particular task, run:

envi taskname env {bash|cmd|other-shell}

To run a task with arguments, run:

envi taskname arg1 arg2 arg3 ...

Special Environment Variables

All task environments contain some special environment variables which store certain information about envi itself:


Aliases offer a way to provide several variations of a task. Each alias should represent an alternative behavior selected by the task's creator.

Aliases are preferred over arguments as a way to change a tasks behavior. Each arguments add a dimension to the number of ways your task can be invoked, but the point of envi is to keep things as constant as possible. Therefore, creating a handful of aliases is preferable to letting a task accept arguments.

A task can check what name it has been called with by examining the TASK_NAME environment variable in task.pl or environment.pl. E.g.:

my $menu_color;
if ( $ENV{'TASK_NAME'} eq "export-menu-red" ) {
	$menu_color = "#aa0000";
} elsif ( $ENV{'TASK_NAME'} eq "export-menu-blue" ) {
	$menu_color = "#0000aa";
} else {
	die "Unrecognised alias!\n";

export_menu( "Restaurant Menu", $menu_color ); #a hypothetical function

Creating and Running Playlists

Playlists offer a way to run multiple tasks with one command. Tasks will be executed one after the other, with the environment for each task being built up before it is executed, then torn down again once execution is complete.

A can go in one of two places, depending on who it should be visible to:

  1. envi/etc/playlists - visible to any user.
  2. YOUR_HOME_DIRECTORY/.envi/playlists - visible only to you.

Playlists take the form of a file with no extension:


Inside the file, specify the tasks to be executed, one per line. E.g.:


The tasks in a playlist can also take arguments.

To view a list of available playlists, run:

envi playlists