The Cordova Command-line Interface
This guide shows you how to create applications and deploy them to
various native mobile platforms using the
interface (CLI). This tool allows you to create new projects, build
them on different platforms, and run them within an emulator. You can
also use the CLI to initialize project code, after which you use
various platforms' IDEs to develop them further.
Before running any command-line tools, you need to install SDKs for each platform you wish to target.
To add support or rebuild a project for any platform, you need to run the command-line interface from the same machine that supports the platform's SDK. The CLI supports the following combinations:
- iOS (Mac)
- Android (Mac, Linux)
- BlackBerry (Mac, Windows)
- Windows Phone 7 (Windows)
- Windows Phone 8 (Windows)
On the Mac, the command-line is available via the Terminal application. On the PC, it's available as Command Prompt under Accessories.
The more likely it is that you run the CLI from different machines, the more it makes sense to maintain a remote source code repository, whose assets you pull down to local working directories.
To install the
cordova command-line tool, follow these steps:
Download and install Node.js. Following installation, you should be able to invoke
npmon your command line.
cordovautility. In Unix, prefixing the additional
sudocommand may be necessary to install development utilities in otherwise restricted directories:
$ sudo npm install -g cordova
The installation log may produce errors for any uninstalled
platform SDKs. Following installation, you should be able to run
cordova on the command line.
To ensure permissions are correct, run this command on Mac or Linux, changing LOGIN to match your account name:
$ sudo chown -R LOGIN /usr/local/lib/node_modules/cordova
After installing the
cordova utility, you can always update it to
the latest version by running the following command:
$ sudo npm update -g cordova
Use this syntax to install a specific version:
$ sudo npm install -g firstname.lastname@example.org
info command for a listing that includes the current version
along with other available version numbers:
$ npm info cordova
Create an App
Go to the directory where you maintain your source code, and run a command such as the following:
$ cordova create HelloWorld com.example.hello "Hello World"
The first argument specifies a HelloWorld directory to be generated
for your project. Its
www subdirectory houses your application's
home page, along with various resources under
which follow common web development file-naming conventions. The
config.xml file contains important metadata needed to generate and
distribute the application.
The other two arguments are optional: the
provides your project with a reverse-domain-style identifier, and the
"Hello World!" provides the application's display text. You can edit
both of these values later in the
All subsequent commands need to be run within the project's directory, or any subdirectories within its scope:
$ cd HelloWorld
Before you can build the project, you need to specify a set of target platforms. Your ability to run these commands depends on whether your machine supports each SDK, and whether you have already installed each SDK. Run any of these from a Mac:
$ cordova platform add ios $ cordova platform add android $ cordova platform add blackberry
Run any of these from a Windows machine, where wp refers to different versions of the Windows Phone operating system:
$ cordova platform add wp7 $ cordova platform add wp8 $ cordova platform add android $ cordova platform add blackberry
Run this to check your current set of platforms:
$ cordova platforms ls
platforms commands are synonymous.)
Run either of the following synonymous commands to remove a platform:
$ cordova platform remove blackberry $ cordova platform rm android
Running commands to add or remove platforms affects the contents of the project's platforms directory, where each specified platform appears as a subdirectory. The www source directory is reproduced within each platform's subdirectory, appearing for example in platforms/ios/www or platforms/android/assets/www. By default, each platform's configuration file is set up to be able to access all of Cordova's APIs.
If you wish, you can use an SDK at this point to open the project you created. However, any edits you make to the project within an SDK affect the derivative set of assets, not the original cross-platform source files. Use this approach if you simply want to initialize a project.
Read on if you wish to use command-line tools for the entire development cycle.
Build the App
By default, the
cordova create script generates a skeletal web-based
application whose home page is the project's
Edit this application however you want, but any initialization should
be specified as part of the
[deviceready](../../cordova/events/events.deviceready.html) event handler, referenced by
Run the following command to iteratively build the project:
$ cordova build
This generates platform-specific code within the project's
subdirectory. You can optionally limit the scope of each build to
$ cordova build ios
cordova build command is a shorthand for the following, which in
this example is also targeted to a single platform:
$ cordova prepare ios $ cordova compile ios
In this case, once you run
prepare, you can use Apple's Xcode SDK as
an alternative to modify and compile the platform-specific code that
Cordova generates within
platforms/ios. You can use the same
approach with other platforms' IDEs.
View the App in an Emulator
SDKs for mobile platforms come bundled with emulators that execute a device image, so that you can launch the app from the home screen and see how it interacts with many platform features. Run a command such as the following to rebuild the app and view it within a specific platform's emulator:
$ cordova emulate android
Some mobile platforms emulate a particular device by default, such as the iPhone for iOS projects. For other platforms, you may need to first associate a device with an emulator.
For example, you may first run the
android command to launch the
Android SDK, then run a particular device image, which launches it
according to its default behavior:
Following up with the
cordova emulate command refreshes the emulator
image to display the latest application, which is now available for
launch from the home screen: