Getting Started with the Codenvy CLI


Welcome to Codenvy. Codenvy provisions, shares and scales developer environments. The Codenvy Developer Environment Cloud is offered as SaaS or on-premises. You can work with projects online or offline and contain plug-ins to configure behavior. Projects within your environment can be edited, compiled, run and debugged within any IDE. Configuration is automated freeing you from the shackles of development: clone environments, share hack spaces, add more RAM and CPU, use multiple machines, run many environments with separation processing, and set restrictive policies.

All Codenvy services are accessible via CLI, API or our browser IDE. The CLI and API can be used to interface with projects, take them offline, or execute critical developer services.


You need [Java version 6] or later and [Maven version 3.1.1] or later installed.

$ git clone
$ cd cli
$ mvn clean install

Add CLI to your system environment PATH variable. On Unix systems, edit .profile or .bashrc. On Windows systems, set the PATH variable in your system environment variables.

$ export PATH=/{directory-to-cli}:$PATH

You may want to create CLI_HOME environment variable and avoid using a full path to bin directory. In this case you will add $CLI_HOME to PATH.


$ SET PATH={directory-to-cli};%PATH%

If the path is correctly setup, entering the command cli help will show the help.

$ codenvy help
                                 | |
         _           ___ ___   __| | ___ _ ____   ___   _
 {    ('   )    }   / __/ _ \ / _` |/ _ \ '_ \ \ / / | | |
{{  ('       )  }} | (_| (_) | (_| |  __/ | | \ V /| |_| |
 { (__,__,__,_) }   \___\___/ \__,_|\___|_| |_|\_/  \__, |
                                                     __/ |

  Codenvy CLI (2.2.0)

build          Build a project
clone-local    Clone a remote Codenvy project to a local directory
create-factory Create a factory
create-project Create a project
delete-project Delete a project
info           Display information for a project, runner, or builder
list           List workspaces, projects and processes
login          Login to a remote Codenvy cloud
logout         Logout to a remote Codenvy cloud
logs           Display output logs for a runner or builder
open           Starts a browser session to access a project, builder or runner
privacy        Change privacy for a project
pull           Update project sync point directory created by clone-local
push           Push local project changes back to Codenvy
remote         Add or remove remote Codenvy cloud references
run            Run a project
stop           Stop one or more runner processes

  default* []

There is an interactive mode, too, giving you auto-complete, shell syntax and session state.

$ codenvy

(without any command after)

We store configuration parameters for the CLI at %HOME%\.codenvy or $HOME/.codenvy. There is a JSON file there that remembers your remote configuration. Deleting this file will have the CLI forget any previous state or tokens.

Your First Project

There are two ways to get started with Codenvy:

  • Sync your existing remote Codenvy projects to your local environment, or:
  • Create a new developer environment locally, and send it to Codenvy. After sending it to Codenvy, you can sync it back to your local directory.

Once a project is loaded within Codenvy’s servers, it can be modified, cloned, shared, restricted, and scaled.

Let’s have some fun.

Login to Codenvy

Create a directory for a project and login to Codenvy. Your login credentials were provided in the validation email sent to you when you created the account. If you used oAuth to create an account, your password is randomly generated, and you may need to use the User Dashboard to set a password that can be used with the CLI.

$ mkdir cdec
$ cd cdec
$ codenvy login my_password

This will create an active session between you and a remote Codenvy cloud. By default, the CLI connects to the remote hosted at Codenvy can be installed on premises or in multiple public clouds. You can use the ‘codenvy remote’ command to see the list of remotes or configure additional ones. The ‘login –remote’ option can be used to access different systems simultaneously.

Present a list of the projects that you have membership rights to.

List Projects

$ codenvy list

ID       REMOTE   WORKSPACE  PROJECT                    TYPE       PRIVACY  
p4f4526  default  eivantsov  blank                      blank      public   
p8fb35a  default  eivantsov  c_sample                   blank      public   
p5140d0  default  eivantsov  cassandra                  maven      public   
p97341d  default  eivantsov  cchbase                    maven      public   
p306578  default  eivantsov  desktop-c-plus-plus-basic  blank      public

If this is your first time using Codenvy, you are a member of a single workspace that belongs to your account. You can also be a member of other workspaces if the administrators of those workspaces invite you. Let’s get some historical details on this project. Each project has a unique hash identifier that can be used as a reference in other commands.

$ codenvy info p22ca68

ID                p22ca68
PROJECT           gwt
WORKSPACE NAME    eivantsov
WORKSPACE ID      workspace2a3osgl3h6hz5eel
PROJECT TYPE      maven
CREATION DATE     17 Aug 2014 07:43:58 
LAST MODIFICATION 17 Aug 2014 07:44:23 
PRIVACY           public
BUILDERS          none
RUNNERS           none

You can either input the entire code, or just the initial three letters (as a shortcut).

$ codenvy info p22

ID                p22ca68
PROJECT           gwt
WORKSPACE NAME    eivantsov
WORKSPACE ID      workspace2a3osgl3h6hz5eel
PROJECT TYPE      maven
CREATION DATE     17 Aug 2014 07:43:58 
LAST MODIFICATION 17 Aug 2014 07:44:23 
PRIVACY           public
BUILDERS          none
RUNNERS           none

This project is in a developer environment that is hosted at Codenvy. Within this environment is the project, type structure, code, builder (for dependency analysis, compiling, unit tests, and packaging), runner (for executing the application and debugging), and plugins, such as the SCM client like subversion. The CLI can interact with the remote developer environment.

Build Project

Let’s place a request at Codenvy to build the project identified by hash p24. Please remember to replace this hash with one generated for your projects. Your request is queued at Codenvy and processed with the first available elf (slave).

$ codenvy build p24
$ codenvy logs p24

The CLI will execute in the foreground or background, with overrides provided by --bg and --fg. Sending commands to the background can be beneficial since you can launch multiple builder and runner processes simultaneously. If you have executed a process in the background, the codenvy logs command retrieves the output of the process.

Run Project

Let’s execute your application in a remote Codenvy runner.

$ codenvy run --bg p24
$ codenvy info p68

In this case, when you do a run, Codenvy creates a runner which is another process. This new process can be short- or long-lived depending upon how your account is configured. Each runner gets its own runner ID, and it is possible for you to launch as many runners as you desire as long as your account’s RAM has not exceeded its quota. You can use codenvy info with project, builder or runner IDs. If you need to stop your application, you can use the runner ID as a parameter. Let’s stop the runner that we started, run a new one, and then launch the browser to visit the application’s user interface.

$ codenvy stop p68
$ codenvy run p24
$ codenvy open p97

Synchronize Projects for Offline Use

Pull a copy of the project from Codenvy.

$ codenvy clone-local p24

Now, open your favorite IDE, make an edit and perform any kind of local build or run. Save your changes. You can make these changes whether you are online or offline.

$ codenvy push

This will push your changes back to Codenvy. Codenvy supports a last-write wins policy. This allows for a direct push / pull connection to Codenvy. For projects where there are multiple users accessing the same project, you can also use your source code repository with a hosted provider like BitBucket or GitHub. From within Codenvy, you can have your project be mapped to a local clone of a remote repository, and then use the clone within the remote Codenvy environment or on your local machine. We are working on an operational transforms system that will allow your local directory to act as a direct sync point with the remote environment, so that as changes are made locally, they are instantly pushed back into the remote space. This will ship as part of the 3.X release train.

Now, let’s open up Codenvy to see the changes made on the remote project.

$ codenvy open p24

Codenvy also comes with a browser IDE of its own that gives you a full range of developer functions right in your browser. This command opens the environment without the need to install or download software.

Create a Project from Local Files

If you have an existing, local project that needs to be pushed into Codenvy, you can use the create-project command to perform in one step the creation and the import of your local files to the remote project.

Let’s start by creating a project from local files that we touch. Create a new directory for a project, and create some source files for your project.

$ mkdir local_project
$ cd local_project
$ touch some_files

Let’s import that project into Codenvy, triggering the Codenvy project construction process within the Codenvy cloud. Codenvy goes through an automation sequence that detects the project type, configures the builders, install the runners, set privacy, and add plug-ins.

$ cd ..
$ codenvy create-project local_project

After this command is completed, the CLI synchronizes the Codenvy metadata that is stored with every project into your local directory that contains the local copy of your project. Your local directory is now automatically connected as a synchronization point with the newly created remote project. Let’s inspect the configuration of your newly created project. The configuration for the project is stored at \local_project\.codenvy\project.json.

  "type" : "blank",
  "builder" : {},
  "runner" : {},
  "attributes" : {}

The project we have created is a blank project type and does not have any attributes set for it. There will be no associated compiler and runner for the project. You will need to associate those as you build up the project. As you define projects with various builders, runners, plug-ins, and policies, the configuration file will be updated with the right properties. You can get the current state of the project’s configuration within the IDE by doing File->Export Config. You can also export the state of any Codenvy project by invoking /api/factory/{ws-id}/{projectname}.

Create a Project From a Git Repository (or GitHub Project)

We have created a shortcut that allows you to create a remote project where the source code is cloned from another git repository.

$ codenvy create-project

This instructs Codenvy to create a project from a set of sources that are contained at a remote URL location. In this case, the remote URL points to a git repository. We automatically detect that the remote URL is a git type and specify a git importer that provides instructions on how the source code should be cloned into the project. The ––importer [git | zip | svn] could optionally be provided to instructs Codenvy which importer to use for the packaging imported. You can also specify the name of the new project by using the ––name my-project flag.

Create a Project from a Factory

If you’d like to create a new project within Codenvy where the source code for that project is externally hosted and the new Project has a specialized set of source, builder, runner, policy, and action attributes, you can do so using a Factory configuration. A Factory configuration file contains a set of instructions for Codenvy to follow when constructing a new project.

$ mkdir local_project
$ cd local_project
$ touch some_files

Create a factory.json file.

 "v" : "2.0",
 "project" : { "attributes" : { "language" : [ "java" ] },
      "builders" : { "default" : "maven" },
      "name" : "hello-world-jsp",
      "runners" : { "configs" : { "system:/java/web/tomcat7" : { "options" : {  },
                  "ram" : 0,
                  "variables" : {  }
                } },
          "default" : "system:/java/web/tomcat7"
      "type" : "maven",
      "visibility" : "public"
  "source" : { "project" : { "location" : "",
          "type" : "git"
      "runners" : {  }
  "variables" : [  ]

The file includes parameters to instruct Codenvy on what to do if there is no predefined workspace, the location of the external source code which should be used during the import, and policies which may restrict who may execute the project construction process. Within the factory.json is a project : {} object that is identical to the project configuration kept within Codenvy. So, factory.json is a super set JSON object of project : {}. There are many things that can be configured in your JSON files. Browse the configuration reference.

In this example, we are defining the builder type to be “maven”. Codenvy has many built-in builder types, which are programmed to maintain project structure, manage dependencies, and perform structured builds. The environment type for runners will be “system:/java/web/tomcat7″, which is a type of runner category that will associate a group of Docker runners that are able to run applications packaged as WAR files. You can learn more about our built-in builders and runners, or customizing your own in the User Guide.

The “source” object in the factory now specifies the location of the external source code that should be imported along with instructions for how it should be managed after the cloning operation.

Once you have created the configuration file, create your project:

$ codenvy create-project factory.json NewProjectName

You provide the name of your configuration file and the identifier name of your new Project. The CLI will generate the name of the URL that hosts your new project when its completed.

Create a Project from a Factory URL

You can also generate a Factory URL, which is a template for creating new projects. Creating a Factory URL does not generate a new project. However, each user that clicks or invokes the URL will get a new project for each invocation of it. This allows Factory URLs to be shared with many people, each of which will get their own project constructed into either a temporary workspace or their own.

You can create a Factory URL either from a factory.json configuration file or from an existing remote project stored at Codenvy.

$ codenvy create-factory factory.json


$ codenvy create-factory p24

The command will generate an encoded Factory URL that has a hash code that uniquely identifies the Factory:

You can paste this URL into a browser, or you can use the ––invoke option with the command to both create the URL and invoke it at the same time.

Where to Go Next

Codenvy is a system that is designed to be flexible. You can swap out builders and runners, create new project types, and execute many runners at the same time, giving you not only flexibility, but access to a virtual super computer. If you are adventurous, you can browse the full configuration format of Codenvy. To continue with the CLI, see all of the commands and options available in the CLI command syntax.