The command line tool to build, deploy and manage Cordova-based applications.
- SDKs for every platform you wish to support
cordova-cli has been tested on Mas OS X and Linux.
If you are using cordova-cli for building iOS applications, you will need to run the latest Mac OS with the latest XCode (4.5+) and XCode Command Line Tools.
In it's prototype stages, cordova-cli only works with Cordova v2.3.0.
npm install -g cordova
NOTE: on Mac OS X, you may want to change the owner of the cordova directory that npm installs to. This will allow you to run cordova as local user without requiring root permissions. Assuming your node_modules directory is in
/usr/local/lib/, you can do this by running:
sudo chown -R <username> /usr/local/lib/node_modules/cordova
cordova-cli has a single global
create command that creates new cordova projects into a specified directory. Once you create a project,
cd into it and you can execute a variety of project-level commands. Completely inspired by git's interface.
create <directory> [<id> [<name>]]create a new cordova project with optional name and id (package name, reverse-domain style)
platform [ls | list]list all platforms the project will build to
platform add <platform> [<platform> ...]add one (or more) platforms as a build target for the project
platform [rm | remove] <platform> [<platform> ...]removes one (or more) platforms as a build target for the project
plugin [ls | list]list all plugins added to the project
plugin add <path-to-plugin> [<path-to-plugin> ...]add one (or more) plugins to the project
plugin [rm | remove] <plugin-name> [<plugin-name> ...]remove one (or more) added plugins
build [<platform> [<platform> [...]]]compile the app and deploy to a connected + compatible device. With no parameters builds for all platforms added to the project, otherwise builds for the specified platforms
emulate [<platform> [<platform> [...]]]launch emulators and deploy app to them. With no parameters emulates for all platforms added to the project, otherwise emulates for the specified platforms
serve <platform> [port]launch a local web server for that platform's www directory on the given port (default 8000).
Project Directory Structure
A Cordova application built with cordova-cli will have the following directory structure:
myApp/ |-.cordova/ |- platforms/ |- plugins/ `- www/
This directory identifies a tree as a cordova project. Simple configuration information is stored in here (such as BlackBerry environment variables).
Commands other than
create operate against the project directory itself, rather than the current directory - a search up the current directory's parents is made to find the project directory. Thus, any command (other than
create) can be used from any subdirectory whose parent is a cordova project directory (same as git).
Platforms added to your application will have the native application project structures laid out within this directory.
Any added plugins will be extracted or copied into this directory.
Contains the project's web artifacts, such as .html, .css and .js files. These are your main application assets. The config.xml file within this directory is very important; read on to the next section!
Your Blanket: www/config.xml
This file is what you should be editing to modify your application's metadata. Any time you run any cordova-cli commands, the tool will look at the contents of
config.xml and use all relevant info from this file to define native application information. cordova-cli supports changing your application's data via the following elements inside the
- The user-facing name can be modified via the contents of the
- The package name (AKA bundle identifier or application id) can be modified via the
idattribute from the top-level
- The whitelist can be modified using the
<access>elements. Make sure the
originattribute of your
<access>element points to a valid URL (you can use
*as wildcard). For more information on the whitelisting syntax, see the docs.phonegap.com. You can use either attribute
origin(standards-compliant) to denote the domain.
- Platform-specific preferences can be customized via
<preference>tags. See docs.phonegap.com for a list of preferences you can use.
Projects created by cordova-cli have
after hooks for each project command. There are two types of hooks: project-specific ones and module-level ones.
These are located under the
.cordova/hooks directory in the root of your cordova project. Any scripts you add to these directories will be executed before and after the appropriate commands. Useful for integrating your own build systems or integrating with version control systems. Remember: make your scripts executable.
If you are using cordova-cli as a module within a larger node application, you can also use the standard
EventEmitter methods to attach to the events. The events include
before_plugin_rm. Additionally, there are
after_ flavours of all the above events.
Creating a new cordova project
This example shows how to create a project from scratch named KewlApp with iOS and Android platform support, and includes a plugin named Kewlio. The project will live in ~/MyProjects/KewlApp
cordova create ~/KewlApp KewlApp cd ~/KewlApp cordova platform add ios android cordova plugin add http://example.org/Kewlio-1.2.3.tar.gz cordova build
The directory structure of KewlApp now looks like this:
KewlApp/ |- .cordova/ |- platforms/ |- android/ | `- … `- ios/ `- … |- plugins/ `- Kewlio/ `- www/ `- index.html
TO-DO + Issues
Please check Cordova issues with the CLI Component. If you find issues with this tool, please be so kind as to include relevant information needed to debug issues such as:
- Your operating system and version
- The application name, directory location, and identifier used with
- Which mobile SDKs you have installed, and which version. Related to this: which Xcode version if you are submitting issues related to iOS
- Any error stack traces you received
Thanks to everyone for contributing! For a list of people involved, please see the