Groom your app’s Cloud Foundry environment with
cfenv to pick a Cloud Foundry environment for your application and reduce the number of logins and targeting that you do.
Powerful in development. Specify your app’s Cloud Foundry environment once, in a single file. Changing directrories changes your Cloud Foundry environment.
One thing well.
cfenv is concerned solely with switching Cloud Foundry environments. It’s simple and predictable. A plugin architecture lets you tailor it to suit your needs.
rbenv this project would not exist.
rbenv provided to be amazingly high quality and amenable to the modifications that make
cfenv possible. I cannot recommend
rbenv enough if you’re a Ruby developer and it’s a model for a well written project for everyone else. Finally, thanks to Dan Mikusa for the inspiration to create this project.
Table of Contents
- How It Works
- Command Reference
How It Works
At a high level,
cfenv intercepts the
cf command using a shim executable injected into your
PATH, determines which Cloud Foundry environment has been specified by your application, and passes your commands along after setting
CF_HOME to the appropriate location.
When you run a command like
cf, your operating system searches through a list of directories to find an executable file with that name. This list of directories lives in an environment variable called
PATH, with each directory in the list separated by a colon:
PATH are searched from left to right, so a matching executable in a directory at the beginning of the list takes precedence over another one at the end. In this example, the
/usr/local/bin directory will be searched first, then
cfenv works by inserting a directory of shims at the front of your
Through a process called rehashing,
cfenv maintains a
cf shim in that directory.
The shim is a lightweight executables that simply passes your command along to
cfenv. So with
cfenv installed, when you run,
cf, your operating system will do the following:
- Search your
PATHfor an executable file named
- Find the
cfat the beginning of your
- Run the shim named
cf, which in turn passes the command along to
Choosing the Cloud Foundry Environment
When you execute the shim,
cfenv determines which Cloud Foundry environment to use by reading it from the following sources, in this order:
CFENV_ENVIRONMENTenvironment variable, if specified. You can use the
cfenv shellcommand to set this environment variable in your current shell session.
.cf-environmentfile found by searching the directory of the script you are executing and each of its parent directories until reaching the root of your filesystem.
.cf-environmentfile found by searching the current working directory and each of its parent directories until reaching the root of your filesystem. You can modify the
.cf-environmentfile in the current working directory with the
~/.cfenv/environmentfile. You can modify this file using the
cfenv globalcommand. If the global environment file is not present,
cfenvassumes you want to use the “system” Cloud Foundry environment—i.e. whatever environment would be used if `cfenv weren’t in your path.
Locating the Cloud Foundry Environment
cfenv has determined which Cloud Foundry environment your application has specified, it passes the prepends the corresponding
CF_HOME environment variable to the command.
Each Cloud Foundry environment is installed into its own directory under
~/.cfenv/environments. For example, you might have these environments
Environment names to
cfenv are simply the names of the directories in
If you’re on Mac OS X, consider installing with Homebrew.
Basic GitHub Checkout
This will get you going with the latest version of
cfenv and make it easy to fork and contribute any changes back upstream.
$ git clone https://github.com/nebhale/cfenv.git ~/.cfenv
$PATHfor access to the
$ echo 'export PATH="$HOME/.cfenv/bin:$PATH"' >> ~/.bash_profile
Ubuntu Desktop note: Modify your
Zsh note: Modify your
~/.zshrcfile instead of
cfenv initto your shell to enable shims and autocompletion.
$ echo 'eval "$(cfenv init -)"' >> ~/.bash_profile
Same as in previous step, use
~/.bashrcon Ubuntu, or
Restart your shell so that PATH changes take effect. (Opening a new terminal tab will usually do it.) Now check if
cfenvwas set up:
$ type cfenv #=> "cfenv is a function"
If you’ve installed
cfenv manually using git, you can upgrade your installation to the cutting-edge version at any time.
$ cd ~/.cfenv $ git pull
To use a specific release of cfenv, check out the corresponding tag:
$ cd ~/.cfenv $ git fetch $ git checkout v0.3.0
If you’ve installed via Homebrew, then upgrade via its
$ brew update $ brew upgrade cfenv cf-build
Homebrew on Mac OS X
$ brew tap nebhale/personal $ brew update $ brew install cfenv cf-build
Afterwards you’ll still need to add
eval "$(cfenv init -)" to your profile as stated in the caveats. You’ll only ever have to do this once.
cfenv hooks into your shell
Skip this section unless you must know what every line in your shell profile is doing.
cfenv init is the only command that crosses the line of loading extra commands into your shell. Here’s what
cfenv init actually does:
Sets up your shims path. This is the only requirement for
cfenvto function properly. You can do this by hand by prepending
Installs autocompletion. This is entirely optional but pretty useful. Sourcing
~/.cfenv/completions/cfenv.bashwill set that up. There is also a
~/.cfenv/completions/cfenv.zshfor Zsh users.
Rehashes shims. From time to time you’ll need to rebuild your shim files. Doing this automatically makes sure everything is up to date. You can always run
Installs the sh dispatcher. This bit is also optional, but allows
cfenvand plugins to change variables in your current shell, making commands like
cfenv shellpossible. The sh dispatcher doesn’t do anything crazy like override
cdor hack your shell prompt, but if for some reason you need
cfenvto be a real script rather than a shell function, you can safely skip it.
cfenv init - for yourself to see exactly what happens under the hood.
Creating Cloud Foundry Environments
cfenv create command doesn’t ship with
cfenv out of the box, but is provided by the cf-build project. If you installed it either as part of GitHub checkout process outlined above or via Homebrew, you should be able to:
$ cfenv install development
Alternatively to the
create command, you can create an environment manually as a subdirectory of
~/.cfenv/environments/. An entry in that directory can also be a symlink to a Cloud Foundry environment installed elsewhere on the filesystem.
cfenv doesn’t care; it will simply treat any entry in the
environments/ directory as a separate Cloud Foundry environment.
Destroying Cloud Foundry Environments
As time goes on, Cloud Foundry environments you create will accumulate in your
To remove old Cloud Foundry environments, simply
rm -rf the directory of the environment you want to remove. You can find the directory of a particular Cloud Foundry environment with the
cfenv prefix command, e.g.
cfenv prefix development.
The cf-build plugin provides an
cfenv destroy command to automate the removal process.
cfenv command delegates to subcommands based on its first argument. The most common subcommands are:
Sets a local application-specific Cloud Foundry environment by writing the environment name to a
.cf-environment file in the current directory. This environment overrides the global environment, and can be overridden itself by setting the
CFENV_ENVIRONMENT environment variable or with the
cfenv shell command.
$ cfenv local development
When run without an environment name,
cfenv local reports the currently configured local environment. You can also unset the local environment:
$ cfenv local --unset
Sets the global Cloud Foundry environment to be used in all shells by writing the environment name to the
~/.cfenv/environment file. This environment can be overridden by an application-specific
.cf-environment file, or by setting the
CFENV_ENVIRONMENT environment variable.
$ cfenv global test
The special environment name
cfenv to use the system Cloud Foundry environment.
When run without an environment name,
cfenv global reports the currently configured global environment.
Sets a shell-specific Cloud Foundry environment by setting the
CFENV_ENVIRONMENT environment variable in your shell. This environment overrides application-specific environments and the global environment.
$ cfenv shell production
When run without an environment name,
cfenv shell reports the current value of
CFENV_ENVIRONMENT. You can also unset the shell environment:
$ cfenv shell --unset
Note that you’ll need
rbenv’s shell integration enabled (step 3 of the installation instructions) in order to use this command. If you prefer not to use shell integration, you may simply set the
CFENV_ENVIRONMENT variable yourself:
$ export CFENV_ENVIRONMENT=production
Lists all Cloud Foundry environments known to
cfenv, and shows an asterisk next to the currently active environment.
$ cfenv environments development test * production (set by /Users/bhale/.cfenv/environment)
Displays the currently active Cloud Foundry environment, along with information on how it was set.
$ cfenv environment production (set by /Users/bhale/dev/sources/nebhale/build-monitor/.cf-environment)
$ cfenv rehash
Displays the full path to the executable that
cfenv will invoke when you run the given command.
$ cfenv which cf /Users/bhale/.cfenv/environments/test/bin/cf
Lists all Cloud Foundry environments with the given command installed.
$ cfenv whence cf development test production
cfenv source code is hosted on GitHub. It’s clean, modular, and easy to understand, even if you’re not a shell hacker.
Tests are executed using Bats:
$ bats test $ bats test/<file>.bats
Please feel free to submit pull requests and file bugs on the issue tracker.
1.0.0 (June 2, 2014)
- Initial public release.
(The MIT license)
Copyright © 2013 Ben Hale
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.