Codenvy Command Line Interface


Control dev environments from the command line
This page contains instructions on installing the CLI, using Codenvy through the CLI, and where to find the reference documentation.

Codenvy makes SaaS developer environments to eliminate inefficiencies in software development from configuring environments. Developers interact in workspaces, where one or more projects exist. A workspace can either be permanent (named) or temporary. Users can also be named (have an account) or anonymous (does not have an account). Named and anonymous users may access both named and temporary workspaces, though only named users may gain R/W permissions in a named workspace. You will create a Codenvy account if you want to be a named user, have your own named workspace, and gain write / admin privileges to workspaces owned by others. You may also grant other users access privileges to projects in workspaces where you are the administrator.

You will need to have [Java version 6] or later installed on your system. Download the CLI library and unzip it into a directory. The start script depends upon the JAVA_HOME environment variable being set and pointing to your Java installation. Also update CLI_HOME to point to the directory where the CLI is installed. Then set your system PATH variable to point to the directory where the CLI is installed.

On MacOS or Linux, place this in your .bashrc file:

    export CLI_HOME=DIR_OF_CLI
    export PATH=$CLI_HOME:$JAVA_HOME/bin:$PATH

On Windows, update your system environment variables:


Verify the installation is working correctly:

$ codenvy

On a unix system, you may need to set the file to be executable and / or run it with an explicit bash command:

$ chmod +x codenvy

You may need to execute the script in a bash shell:

$ sh codenvy


Let’s create a new temporary workspace, start a Spring Java project inside of it, and create an anonymous user account to access the environment. We provide an environment generator, called a Factory, that reads recipes from JSON files and generates a template that is accessible through a URL. The Factory URL can be reused by others to create multiple environments from the same template.

$ codenvy

This will generate a new Factory URL that can be executed in your browser. The format will be along the lines of:

That was interesting, but it didn’t do much. Things get interesting when you take the URL and execute it in a browser. You can both create a Factory URL and launch it with the launch parameter.

$ codenvy --launch

Congratulations! You have created a Factory URL template from a JSON file. You have also executed the Factory URL which created an anonymous workspace, a new Spring Java project, and an anonymous user. Inside of your workspace you can edit, build, debug, deploy and collaborate. If you are idle or close the browser tab, the workspace will be destroyed along with the project inside of it. Creating a free Codenvy account will let you preserve projects indefinitely.

There are more Factories you can experiment with. You can browse the JSON for all Factories we host at This is a public GitHub project, and we’ll accept pull requests of any interesting factories that you feel should be added. A full list of the parameters that can be placed in a JSON file is provided here.


Only some of the Factory components can be generated from the CLI anonymously. For the really interesting things such as encoded Factories, storing images, or parameterization, you will need an API token issued from the remote Codenvy installation. You can create a token and save it in a Codenvy configuration file with the CLI.

Create an account at, or by selecting “Create Free Account” from within the temporary workspace you created earlier. Your email address will be used as the identifier for the account. Once you have a named account, you will want to generate a new token associated with this account.

$ codenvy auth --newToken --save --user [YOUR_CODENVY_USER_NAME] --password [YOUR_CODENVY_PASSWORD]

The –save parameter will save your your profile and token to a configuration file that is stored at $CLI_HOME/conf/config or %CLI_HOME%\conf\config, if on Windows. Properties stored in this file will be loaded by default and made available to the CLI on future command executions. If you have multiple accounts at, or you have accounts on different Codenvy Enterprise installations, you can store the configuration for each account by using the profile parameter. When executing commands against Codenvy installations with their own unique URL, you can point the CLI to these instances with the provider parameter.


$ codenvy remote factory:create --encoded --in

This will also generate a Factory from a JSON file, but the returned URL is encoded. When you encode a Factory, the parameters are stored in a Codenvy instance and you are returned a hashed Factory URL. Storing the properties on Codenvy enables us to offer a wide range of parameters that can affect how the Factory will run including policies (start / stop times), parameterization (pass in values into the execution), meta-data, and so on.

There was a different CLI format for this call. The codenvy JSON_FILE format is a shortcut to the codenvy remote factory:create call. A full list of our CLI functions can be seen here.